@morshoto/framekit 0.1.5 → 0.1.10

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 (40) hide show
  1. package/bin/framekit.mjs +2 -1
  2. package/dist-package/adapters/final-cut/typescript/src/assets.js +223 -15
  3. package/dist-package/adapters/final-cut/typescript/src/background-export.js +384 -0
  4. package/dist-package/adapters/final-cut/typescript/src/canonical.js +588 -0
  5. package/dist-package/adapters/final-cut/typescript/src/connection.js +20 -5
  6. package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +33 -7
  7. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +805 -51
  8. package/dist-package/adapters/final-cut/typescript/src/index.js +5 -0
  9. package/dist-package/adapters/final-cut/typescript/src/library-inspection.js +390 -0
  10. package/dist-package/adapters/final-cut/typescript/src/live.js +6 -3
  11. package/dist-package/adapters/final-cut/typescript/src/media.js +151 -0
  12. package/dist-package/adapters/final-cut/typescript/src/native-session.js +412 -0
  13. package/dist-package/adapters/final-cut/typescript/src/native.js +2271 -424
  14. package/dist-package/adapters/final-cut/typescript/src/publisher.js +225 -32
  15. package/dist-package/adapters/final-cut/typescript/src/session.js +145 -17
  16. package/dist-package/apps/mcp-server/src/main.js +73 -17
  17. package/dist-package/apps/mcp-server/src/routing.js +242 -39
  18. package/dist-package/apps/mcp-server/src/server.js +677 -89
  19. package/dist-package/apps/mcp-server/src/version.js +109 -1
  20. package/dist-package/packages/runtime/src/application/media-analysis-service.js +3 -4
  21. package/dist-package/packages/runtime/src/application/project-service.js +46 -7
  22. package/dist-package/packages/runtime/src/audio/dialogue-normalization.js +9 -0
  23. package/dist-package/packages/runtime/src/capabilities.js +62 -9
  24. package/dist-package/packages/runtime/src/context/project-catalog.js +159 -0
  25. package/dist-package/packages/runtime/src/domain/capabilities.js +33 -0
  26. package/dist-package/packages/runtime/src/domain/context.js +14 -1
  27. package/dist-package/packages/runtime/src/domain/editing.js +27 -1
  28. package/dist-package/packages/runtime/src/domain/index.js +1 -0
  29. package/dist-package/packages/runtime/src/domain/skills.js +2 -0
  30. package/dist-package/packages/runtime/src/domain/timeline-target.js +217 -0
  31. package/dist-package/packages/runtime/src/editing/edit-service.js +57 -1
  32. package/dist-package/packages/runtime/src/editing/intent.js +178 -2
  33. package/dist-package/packages/runtime/src/index.js +1 -0
  34. package/dist-package/packages/runtime/src/runtime.js +2 -2
  35. package/dist-package/packages/runtime/src/skills/builtin.js +314 -39
  36. package/dist-package/packages/runtime/src/skills/requirements.js +1 -0
  37. package/dist-package/packages/runtime/src/skills/runtime.js +33 -8
  38. package/dist-package/packages/runtime/src/verification/verification.js +81 -4
  39. package/dist-package/packages/testkit/src/in-memory-editor.js +130 -4
  40. package/package.json +12 -2
@@ -1,6 +1,6 @@
1
1
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
2
2
  import { InMemoryEditorAdapter } from "../../../packages/testkit/src/index.js";
3
- import { createCommandAnalyzers, createFinalCutLiveAdapter, FcpxmlDocumentAdapter, FinalCutAssetRegistry, FinalCutConnectionManager, FinalCutNativeAutomationAdapter, DisposableNativeEditWorkflow, FinalCutProjectPublisher, FinalCutVideoExporter, FinalCutSessionAdapter, createNativeOperationLease, isFinalCutVideoProbeAvailable, } from "../../../adapters/final-cut/typescript/src/index.js";
3
+ import { createCommandAnalyzers, createFinalCutLiveAdapter, FcpxmlDocumentAdapter, FinalCutAssetRegistry, FinalCutMediaRegistry, FinalCutConnectionManager, assertCanonicalProviderConfiguration, FinalCutCanonicalNativeProvider, FinalCutCanonicalSnapshotSource, FinalCutLibraryInspectionProvider, FinalCutNativeAutomationAdapter, createFinalCutNativeTargetResolver, DisposableNativeEditWorkflow, FinalCutProjectPublisher, FinalCutVideoExporter, FinalCutSessionAdapter, createNativeOperationLease, createDisposableNativeOperationSession, isFinalCutVideoProbeAvailable, } from "../../../adapters/final-cut/typescript/src/index.js";
4
4
  import { FixtureAudioAnalyzer, FixtureMetadataAnalyzer, FixtureSpeechAnalyzer, FixtureVisualAnalyzer } from "../../../packages/testkit/src/index.js";
5
5
  import { AgentVideoRuntime } from "../../../packages/runtime/src/index.js";
6
6
  import { createMcpServer } from "./server.js";
@@ -51,29 +51,81 @@ const fixture = new InMemoryEditorAdapter({
51
51
  const liveMode = process.env.FRAMEKIT_EDITOR === "final-cut-live";
52
52
  const headlessFinalCut = liveMode && process.env.FRAMEKIT_FINAL_CUT_HEADLESS === "1";
53
53
  const fcpxmlPath = liveMode ? process.env.FRAMEKIT_FCPXML_PATH : undefined;
54
- const connection = liveMode ? new FinalCutConnectionManager({ headless: headlessFinalCut }) : undefined;
54
+ const canonicalNativeProviderEnabled = liveMode && process.env.FRAMEKIT_FINAL_CUT_CANONICAL_PROVIDER === "native";
55
+ if (canonicalNativeProviderEnabled && headlessFinalCut) {
56
+ throw new Error("FINAL_CUT_CANONICAL_NATIVE_REQUIRES_HEADED: set FRAMEKIT_FINAL_CUT_HEADLESS=0 for the native provider");
57
+ }
58
+ if (canonicalNativeProviderEnabled && process.env.FRAMEKIT_FINAL_CUT_NATIVE_WRITES !== "1") {
59
+ throw new Error("FINAL_CUT_CANONICAL_NATIVE_REQUIRES_WRITES: set FRAMEKIT_FINAL_CUT_NATIVE_WRITES=1 for the native provider");
60
+ }
61
+ const canonicalProviderRequired = liveMode
62
+ && process.env.FRAMEKIT_FINAL_CUT_CANONICAL_REQUIRED === "1"
63
+ && !canonicalNativeProviderEnabled;
64
+ assertCanonicalProviderConfiguration({ required: canonicalProviderRequired || canonicalNativeProviderEnabled, fcpxmlPath });
65
+ const connection = liveMode
66
+ ? new FinalCutConnectionManager({ headless: headlessFinalCut, canonicalProviderRequired })
67
+ : undefined;
55
68
  const autoConnect = liveMode && process.env.FRAMEKIT_AUTO_CONNECT !== "0";
56
69
  if (autoConnect)
57
70
  connection?.startAutoConnect();
58
71
  const liveAdapter = liveMode ? createFinalCutLiveAdapter() : undefined;
72
+ const backgroundLibraryProvider = liveMode ? new FinalCutLibraryInspectionProvider() : undefined;
59
73
  const nativeOperationLease = autoConnect
60
74
  ? createNativeOperationLease(() => connection?.stopAutoConnect(), () => connection?.startAutoConnect())
61
75
  : undefined;
76
+ const nativeEditor = liveMode
77
+ ? new FinalCutNativeAutomationAdapter({
78
+ enabled: !headlessFinalCut && process.env.FRAMEKIT_FINAL_CUT_NATIVE_WRITES === "1",
79
+ liveState: () => liveAdapter.readLiveState(),
80
+ nativeOperationLease,
81
+ })
82
+ : undefined;
83
+ const canonicalNativeMutationEditor = canonicalNativeProviderEnabled
84
+ ? new FinalCutNativeAutomationAdapter({
85
+ enabled: true,
86
+ nativeOperationLease,
87
+ })
88
+ : nativeEditor;
89
+ const canonicalNativeProvider = canonicalNativeProviderEnabled
90
+ ? new FinalCutCanonicalNativeProvider({
91
+ live: liveAdapter,
92
+ native: {
93
+ renameSelectedClip: async (name) => {
94
+ const result = await canonicalNativeMutationEditor.edit({ type: "rename-selected-clip", name });
95
+ return { operationId: result.operationId, undoAvailable: result.undoAvailable };
96
+ },
97
+ undo: async (operationId) => {
98
+ const result = await canonicalNativeMutationEditor.undo(operationId);
99
+ return { undone: result.undone, verification: result.verification };
100
+ },
101
+ },
102
+ readSnapshot: () => new FinalCutCanonicalSnapshotSource().readSnapshot(),
103
+ resolveTarget: createFinalCutNativeTargetResolver(nativeEditor),
104
+ backgroundCatalog: backgroundLibraryProvider,
105
+ })
106
+ : undefined;
107
+ const configuredAssetRoots = parseRoots(process.env.FRAMEKIT_FINAL_CUT_ASSET_ROOTS) ?? [];
108
+ const configuredMediaRoots = parseRoots(process.env.FRAMEKIT_FINAL_CUT_MEDIA_ROOTS) ?? [];
62
109
  const editor = liveMode
63
110
  ? new FinalCutSessionAdapter({
64
- live: liveAdapter,
65
- ...(fcpxmlPath
111
+ live: canonicalNativeProvider ?? liveAdapter,
112
+ ...(!canonicalNativeProvider && backgroundLibraryProvider
113
+ ? { backgroundCatalog: backgroundLibraryProvider }
114
+ : {}),
115
+ ...(fcpxmlPath && !canonicalNativeProviderEnabled
66
116
  ? (() => {
67
117
  const document = new FcpxmlDocumentAdapter(fcpxmlPath);
68
118
  return { snapshot: document, mutation: document };
69
119
  })()
70
120
  : {}),
71
121
  assets: new FinalCutAssetRegistry({
72
- roots: process.env.FRAMEKIT_FINAL_CUT_ASSET_ROOTS
73
- ?.split(process.platform === "win32" ? ";" : ":")
74
- .map((root) => root.trim())
75
- .filter(Boolean),
122
+ roots: configuredAssetRoots.length > 0 ? configuredAssetRoots : undefined,
123
+ nativeTitleProvider: nativeEditor?.capabilities().titleDiscovery ? nativeEditor : undefined,
124
+ nativeTransitionProvider: nativeEditor?.capabilities().transitionDiscovery ? nativeEditor : undefined,
76
125
  }),
126
+ ...(configuredMediaRoots.length > 0
127
+ ? { media: new FinalCutMediaRegistry({ roots: configuredMediaRoots }) }
128
+ : {}),
77
129
  })
78
130
  : fixture;
79
131
  const analyzers = liveMode
@@ -91,13 +143,6 @@ const analyzers = liveMode
91
143
  metadataAnalyzer: new FixtureMetadataAnalyzer(),
92
144
  };
93
145
  const runtime = new AgentVideoRuntime(editor, analyzers);
94
- const nativeEditor = liveMode
95
- ? new FinalCutNativeAutomationAdapter({
96
- enabled: !headlessFinalCut && process.env.FRAMEKIT_FINAL_CUT_NATIVE_WRITES === "1",
97
- liveState: () => liveAdapter.readLiveState(),
98
- nativeOperationLease,
99
- })
100
- : undefined;
101
146
  const disposableNative = liveMode && !headlessFinalCut && !fcpxmlPath && nativeEditor
102
147
  ? new DisposableNativeEditWorkflow({
103
148
  native: nativeEditor,
@@ -105,9 +150,12 @@ const disposableNative = liveMode && !headlessFinalCut && !fcpxmlPath && nativeE
105
150
  readCanonicalCapabilities: async () => (await runtime.inspectEditor()).capabilities,
106
151
  })
107
152
  : undefined;
108
- const projectPublisher = liveMode && !headlessFinalCut && fcpxmlPath && process.env.FRAMEKIT_FINAL_CUT_NATIVE_WRITES === "1"
153
+ const nativeOperationSession = disposableNative && nativeEditor
154
+ ? createDisposableNativeOperationSession({ workflow: disposableNative, native: nativeEditor })
155
+ : undefined;
156
+ const projectPublisher = liveMode && fcpxmlPath
109
157
  ? new FinalCutProjectPublisher({
110
- enabled: true,
158
+ enabled: !headlessFinalCut && process.env.FRAMEKIT_FINAL_CUT_NATIVE_WRITES === "1",
111
159
  sourcePath: fcpxmlPath,
112
160
  liveState: () => liveAdapter.readLiveState(),
113
161
  })
@@ -128,6 +176,7 @@ const server = createMcpServer(runtime, {
128
176
  connectionStatus: () => connection?.getStatus(),
129
177
  nativeEditor,
130
178
  disposableNative,
179
+ nativeOperationSession,
131
180
  projectPublisher,
132
181
  videoExporter,
133
182
  });
@@ -153,3 +202,10 @@ function parseTimeout(value) {
153
202
  const timeout = Number(value);
154
203
  return Number.isFinite(timeout) && timeout > 0 ? timeout : undefined;
155
204
  }
205
+ function parseRoots(value) {
206
+ const roots = value
207
+ ?.split(process.platform === "win32" ? ";" : ":")
208
+ .map((root) => root.trim())
209
+ .filter(Boolean);
210
+ return roots && roots.length > 0 ? roots : undefined;
211
+ }
@@ -10,6 +10,25 @@ export const EDITOR_FIRST_WORKFLOW = [
10
10
  "edit.diff",
11
11
  "edit.verify",
12
12
  ];
13
+ export const BACKGROUND_LIBRARY_WORKFLOW = [
14
+ "connection.status",
15
+ "editor.inspect",
16
+ "editing.route",
17
+ "project.list",
18
+ "editor.live.inspect",
19
+ ];
20
+ export const BACKGROUND_ARTIFACT_WORKFLOW = [
21
+ "connection.status",
22
+ "editor.inspect",
23
+ "artifact.inspect",
24
+ "project.inspect",
25
+ "editing.route",
26
+ "artifact.edit.preview",
27
+ "artifact.edit.execute",
28
+ "artifact.edit.diff",
29
+ "artifact.edit.verify",
30
+ "artifact.edit.undo",
31
+ ];
13
32
  export const EDITOR_FIRST_MCP_INSTRUCTIONS = [
14
33
  "Framekit uses an editor-first workflow for every editing request.",
15
34
  "1. Call connection.status to establish whether the expected editor is connected.",
@@ -18,43 +37,73 @@ export const EDITOR_FIRST_MCP_INSTRUCTIONS = [
18
37
  "4. Call editing.route and use only a path whose required capabilities are advertised.",
19
38
  "5. Resolve intent when needed, then preview before execute; never mutate on an unavailable capability.",
20
39
  "6. Observe the result, then use edit.diff and edit.verify to confirm the change.",
40
+ "Background project and live metadata may use project.list and editor.live.inspect without canonical timeline proof.",
41
+ "For an explicit FCPXML artifact, select artifact.edit; its background workflow uses artifact.inspect, artifact.edit.preview, artifact.edit.execute, artifact.edit.diff, artifact.edit.verify, and artifact.edit.undo, and never claims to change the open Final Cut timeline.",
21
42
  "An external renderer is never an implicit substitute for a connected editor. Select fallback: external-renderer explicitly and report the structured reason returned by editing.route.",
22
43
  ].join("\n");
23
44
  const operationRequirements = {
45
+ "project.list": [backgroundLibraryRequirement()],
46
+ "project.select": [editorRequirement("projectSelection", "native-ui")],
47
+ "project.inspect": [canonicalRequirement()],
48
+ "timeline.inspect": [canonicalRequirement()],
49
+ "editor.live.inspect": [observationRequirement("timeline")],
24
50
  "timeline.edit": [
25
51
  editorRequirement("projectRead"),
26
52
  editorRequirement("timelineSnapshotRead"),
27
- {
28
- label: "editor.timelineWrite|editor.timelineArtifactWrite",
29
- satisfied: (context) => Boolean(context.editor?.capabilities.editor.timelineWrite
30
- || context.editor?.capabilities.editor.timelineArtifactWrite),
31
- },
53
+ editorArtifactWriteRequirement(),
32
54
  editorRequirement("readAfterWrite"),
33
55
  editorRequirement("rollback"),
34
56
  ],
57
+ "timeline.mask.add": [
58
+ editorRequirement("projectRead"),
59
+ editorRequirement("timelineSnapshotRead"),
60
+ editorRequirement("timelineWrite"),
61
+ editorRequirement("readAfterWrite"),
62
+ editorRequirement("rollback"),
63
+ editorRequirement("masking"),
64
+ ],
35
65
  "editor.native.edit": [
36
66
  nativeRequirement("selectionEdit"),
37
67
  nativeRequirement("timelineFocus"),
38
68
  nativeRequirement("undo"),
39
69
  ],
70
+ "editor.native.picture-in-picture": [
71
+ nativeRequirement("pictureInPicture"),
72
+ nativeRequirement("mediaSelection"),
73
+ nativeRequirement("timelineOccurrenceLocate"),
74
+ nativeRequirement("timelineFocus"),
75
+ nativeRequirement("undo"),
76
+ ],
77
+ "artifact.edit": [
78
+ editorRequirement("projectRead"),
79
+ editorRequirement("timelineSnapshotRead"),
80
+ editorRequirement("timelineArtifactWrite"),
81
+ editorRequirement("readAfterWrite"),
82
+ editorRequirement("rollback"),
83
+ ],
40
84
  "timeline.publish.new-project": [
41
85
  {
86
+ name: "editor.artifactPublish",
42
87
  label: "editor.artifactPublish",
88
+ category: "native-ui",
43
89
  satisfied: (context) => Boolean(context.editor?.capabilities.editor.artifactPublish
44
90
  || context.editor?.capabilities.editor.timelinePublishNewProject),
91
+ descriptor: (context) => context.editor?.capabilities.families?.publishing.projectCreation,
45
92
  },
46
93
  ],
47
- "timeline.export": [
48
- editorRequirement("videoExport"),
49
- ],
94
+ "timeline.export": [editorRequirement("videoExport", "native-ui")],
50
95
  };
51
96
  export function resolveEditingRoute(request, context) {
52
97
  const requirements = operationRequirements[request.operation];
53
98
  const requiredCapabilities = requirements.map((requirement) => requirement.label);
54
- const missingCapabilities = requirements
55
- .filter((requirement) => !requirement.satisfied(context))
56
- .map((requirement) => requirement.label);
99
+ const missingRequirements = requirements.filter((requirement) => !requirement.satisfied(context));
100
+ const missingCapabilities = missingRequirements.map((requirement) => requirement.label);
57
101
  const editor = context.editor?.identity;
102
+ const workflow = request.operation === "artifact.edit"
103
+ ? BACKGROUND_ARTIFACT_WORKFLOW
104
+ : request.operation === "project.list"
105
+ ? BACKGROUND_LIBRARY_WORKFLOW
106
+ : EDITOR_FIRST_WORKFLOW;
58
107
  if (request.fallback === "external-renderer") {
59
108
  const cause = externalFallbackCause(context, missingCapabilities);
60
109
  return {
@@ -64,7 +113,7 @@ export function resolveEditingRoute(request, context) {
64
113
  requiredCapabilities,
65
114
  missingCapabilities,
66
115
  ...(editor ? { editor } : {}),
67
- workflow: [...EDITOR_FIRST_WORKFLOW],
116
+ workflow: [...workflow],
68
117
  reason: {
69
118
  code: "EXTERNAL_FALLBACK_SELECTED",
70
119
  message: "The external renderer was selected explicitly; Framekit will not invoke it or bypass the editor silently.",
@@ -73,9 +122,10 @@ export function resolveEditingRoute(request, context) {
73
122
  },
74
123
  };
75
124
  }
76
- const offlineArtifactEdit = request.operation === "timeline.edit"
77
- && context.editor?.capabilities.editor.timelineArtifactWrite === true;
78
- if (context.connection.state !== "ready" && !offlineArtifactEdit) {
125
+ const offlineArtifactEdit = (request.operation === "artifact.edit" || request.operation === "timeline.edit")
126
+ && Boolean(context.editor?.capabilities.editor.timelineArtifactWrite
127
+ && (context.editor.capabilities.families?.canonicalDocument.artifactWrite.available ?? true));
128
+ if (context.connection.state !== "ready" && !offlineArtifactEdit && request.operation !== "project.list") {
79
129
  return {
80
130
  operation: request.operation,
81
131
  status: "unavailable",
@@ -83,11 +133,11 @@ export function resolveEditingRoute(request, context) {
83
133
  requiredCapabilities,
84
134
  missingCapabilities,
85
135
  ...(editor ? { editor } : {}),
86
- workflow: [...EDITOR_FIRST_WORKFLOW],
87
- reason: editorUnavailableReason(context, missingCapabilities),
136
+ workflow: [...workflow],
137
+ reason: editorUnavailableReason(context, missingRequirements),
88
138
  };
89
139
  }
90
- if (missingCapabilities.length > 0 || !context.editor) {
140
+ if (missingRequirements.length > 0 || !context.editor) {
91
141
  return {
92
142
  operation: request.operation,
93
143
  status: "unavailable",
@@ -95,41 +145,193 @@ export function resolveEditingRoute(request, context) {
95
145
  requiredCapabilities,
96
146
  missingCapabilities,
97
147
  ...(editor ? { editor } : {}),
98
- workflow: [...EDITOR_FIRST_WORKFLOW],
99
- reason: {
100
- code: "CAPABILITY_UNAVAILABLE",
101
- message: `The connected editor cannot satisfy ${request.operation}; no alternate editor path was selected.`,
102
- connectionState: context.connection.state,
103
- },
148
+ workflow: [...workflow],
149
+ reason: capabilityUnavailableReason(context, missingRequirements, request.operation),
104
150
  };
105
151
  }
152
+ const provider = selectedProvider(request.operation, context);
106
153
  return {
107
154
  operation: request.operation,
108
155
  status: "editor-selected",
109
- selectedPath: "editor",
156
+ selectedPath: selectedPath(request.operation, provider),
110
157
  requiredCapabilities,
111
158
  missingCapabilities: [],
159
+ ...(provider ? { provider } : {}),
112
160
  editor,
113
- workflow: [...EDITOR_FIRST_WORKFLOW],
161
+ workflow: [...workflow],
114
162
  reason: {
115
163
  code: "EDITOR_SELECTED",
116
- message: "The connected editor satisfies the required capabilities; continue with the preview and execute contract.",
164
+ message: selectedMessage(request.operation),
117
165
  connectionState: context.connection.state,
118
166
  },
119
167
  };
120
168
  }
121
- function editorRequirement(capability) {
169
+ function canonicalRequirement() {
170
+ return {
171
+ name: "canonicalDocument.read",
172
+ label: "canonicalDocument.read",
173
+ category: "canonical-snapshot",
174
+ satisfied: (context) => {
175
+ const descriptor = context.editor?.capabilities.families?.canonicalDocument.read;
176
+ return descriptor ? descriptor.available : Boolean(context.editor?.capabilities.editor.projectRead
177
+ && context.editor.capabilities.editor.timelineSnapshotRead);
178
+ },
179
+ descriptor: (context) => context.editor?.capabilities.families?.canonicalDocument.read,
180
+ };
181
+ }
182
+ function observationRequirement(operation) {
122
183
  return {
184
+ name: `observation.${operation}`,
185
+ label: `observation.${operation}`,
186
+ category: "background-api",
187
+ satisfied: (context) => {
188
+ const descriptor = context.editor?.capabilities.families?.observation[operation];
189
+ return Boolean(context.editor?.capabilities.editor.liveStateRead
190
+ || descriptor?.available && descriptor.guarantee === "observed");
191
+ },
192
+ descriptor: (context) => context.editor?.capabilities.families?.observation[operation],
193
+ };
194
+ }
195
+ function backgroundLibraryRequirement() {
196
+ return {
197
+ name: "observation.library",
198
+ label: "observation.library",
199
+ category: "background-api",
200
+ satisfied: (context) => context.editor?.capabilities.families?.observation.library.available === true,
201
+ descriptor: (context) => context.editor?.capabilities.families?.observation.library,
202
+ };
203
+ }
204
+ function editorArtifactWriteRequirement() {
205
+ return {
206
+ name: "editor.timelineWrite|editor.timelineArtifactWrite",
207
+ label: "editor.timelineWrite|editor.timelineArtifactWrite",
208
+ category: "canonical-snapshot",
209
+ satisfied: (context) => {
210
+ const families = context.editor?.capabilities.families;
211
+ if (families) {
212
+ return families.canonicalDocument.write.available || families.canonicalDocument.artifactWrite.available;
213
+ }
214
+ return Boolean(context.editor?.capabilities.editor.timelineWrite
215
+ || context.editor?.capabilities.editor.timelineArtifactWrite);
216
+ },
217
+ descriptor: (context) => {
218
+ const families = context.editor?.capabilities.families;
219
+ if (families?.canonicalDocument.write.available)
220
+ return families.canonicalDocument.write;
221
+ return families?.canonicalDocument.artifactWrite;
222
+ },
223
+ };
224
+ }
225
+ function editorRequirement(capability, category = "canonical-snapshot") {
226
+ return {
227
+ name: `editor.${capability}`,
123
228
  label: `editor.${capability}`,
124
- satisfied: (context) => Boolean(context.editor?.capabilities.editor[capability]),
229
+ category,
230
+ satisfied: (context) => {
231
+ const descriptor = editorDescriptor(context, capability);
232
+ return descriptor ? descriptor.available : Boolean(context.editor?.capabilities.editor[capability]);
233
+ },
234
+ descriptor: (context) => editorDescriptor(context, capability),
125
235
  };
126
236
  }
127
237
  function nativeRequirement(capability) {
128
238
  return {
239
+ name: `native.${capability}`,
129
240
  label: `native.${capability}`,
130
- satisfied: (context) => context.native?.[capability] === true,
241
+ category: "native-ui",
242
+ satisfied: (context) => {
243
+ const descriptor = nativeDescriptor(context, capability);
244
+ return descriptor ? descriptor.available : context.native?.[capability] === true;
245
+ },
246
+ descriptor: (context) => nativeDescriptor(context, capability),
247
+ };
248
+ }
249
+ function editorDescriptor(context, capability) {
250
+ const families = context.editor?.capabilities.families;
251
+ if (!families)
252
+ return undefined;
253
+ switch (capability) {
254
+ case "projectRead":
255
+ case "timelineSnapshotRead":
256
+ return families.canonicalDocument.read;
257
+ case "timelineWrite":
258
+ return families.canonicalDocument.write;
259
+ case "timelineArtifactWrite":
260
+ return families.canonicalDocument.artifactWrite;
261
+ case "readAfterWrite":
262
+ case "rollback":
263
+ return families.canonicalDocument.write.available
264
+ ? families.canonicalDocument.write
265
+ : families.canonicalDocument.artifactWrite;
266
+ case "videoExport":
267
+ return families.export.timeline;
268
+ case "artifactPublish":
269
+ case "timelinePublishNewProject":
270
+ return families.publishing.projectCreation;
271
+ default:
272
+ return undefined;
273
+ }
274
+ }
275
+ function nativeDescriptor(context, capability) {
276
+ const operation = {
277
+ selectionEdit: "selectionWrite",
278
+ timelineFocus: "timelineFocus",
279
+ undo: "undo",
280
+ pictureInPicture: "pictureInPicture",
281
+ mediaSelection: "mediaSelection",
282
+ timelineOccurrenceLocate: "timelineOccurrenceLocate",
283
+ }[capability];
284
+ return operation ? context.editor?.capabilities.families?.native[operation] : undefined;
285
+ }
286
+ function selectedProvider(operation, context) {
287
+ const requirements = operationRequirements[operation];
288
+ const descriptor = operation === "timeline.edit"
289
+ ? requirements.find((requirement) => requirement.name === "editor.timelineWrite|editor.timelineArtifactWrite")?.descriptor(context)
290
+ : requirements[0]?.descriptor(context);
291
+ return descriptor?.available
292
+ ? { backend: descriptor.backend, guarantee: descriptor.guarantee }
293
+ : undefined;
294
+ }
295
+ function selectedPath(operation, provider) {
296
+ if (operation === "artifact.edit")
297
+ return "artifact";
298
+ if (operation === "project.list" || operation === "editor.live.inspect") {
299
+ return provider?.guarantee === "observed" ? "background" : "editor";
300
+ }
301
+ if (operation.startsWith("editor.native."))
302
+ return "native";
303
+ return "editor";
304
+ }
305
+ function selectedMessage(operation) {
306
+ if (operation === "project.list" || operation === "editor.live.inspect") {
307
+ return "The background observation provider satisfies the requested metadata fields; no canonical timeline proof is implied.";
308
+ }
309
+ if (operation === "artifact.edit") {
310
+ return "The managed FCPXML artifact satisfies the required capabilities; continue with its background preview and execute contract without Final Cut UI access.";
311
+ }
312
+ return "The connected editor satisfies the required capabilities; continue with the preview and execute contract.";
313
+ }
314
+ function unavailableEvidence(context, requirements) {
315
+ const requirement = requirements[0];
316
+ if (!requirement)
317
+ return undefined;
318
+ const descriptor = requirement.descriptor(context);
319
+ const category = requirement.category;
320
+ return {
321
+ category,
322
+ capability: requirement.name,
323
+ backend: descriptor?.backend ?? context.editor?.identity.backend ?? "unknown",
324
+ guarantee: descriptor?.guarantee ?? "none",
325
+ message: `${categoryMessage(category)}: ${descriptor?.unavailableReason ?? "the required capability is unavailable"}`,
131
326
  };
132
327
  }
328
+ function categoryMessage(category) {
329
+ switch (category) {
330
+ case "background-api": return "background API support is unavailable";
331
+ case "canonical-snapshot": return "canonical snapshot support is unavailable";
332
+ case "native-ui": return "native UI access is unavailable";
333
+ }
334
+ }
133
335
  function externalFallbackCause(context, missingCapabilities) {
134
336
  if (context.connection.state !== "ready") {
135
337
  return context.connection.lastError ?? {
@@ -148,25 +350,26 @@ function externalFallbackCause(context, missingCapabilities) {
148
350
  message: "The caller explicitly selected the external renderer even though the editor is available.",
149
351
  };
150
352
  }
151
- function editorUnavailableReason(context, missingCapabilities) {
353
+ function editorUnavailableReason(context, missingRequirements) {
152
354
  if (context.connection.state !== "ready") {
153
355
  return {
154
356
  code: "EDITOR_UNAVAILABLE",
155
357
  message: `The expected editor is unavailable while the connection is ${context.connection.state}.`,
156
358
  connectionState: context.connection.state,
157
359
  ...(context.connection.lastError ? { cause: context.connection.lastError } : {}),
360
+ ...(unavailableEvidence(context, missingRequirements) ? { unavailable: unavailableEvidence(context, missingRequirements) } : {}),
158
361
  };
159
362
  }
160
- if (missingCapabilities.length > 0 || !context.editor) {
161
- return {
162
- code: "CAPABILITY_UNAVAILABLE",
163
- message: "The connected editor does not advertise every capability required by this operation.",
164
- connectionState: context.connection.state,
165
- };
166
- }
363
+ return capabilityUnavailableReason(context, missingRequirements);
364
+ }
365
+ function capabilityUnavailableReason(context, missingRequirements, operation) {
366
+ const unavailable = unavailableEvidence(context, missingRequirements);
167
367
  return {
168
368
  code: "CAPABILITY_UNAVAILABLE",
169
- message: "The connected editor does not advertise every capability required by this operation.",
369
+ message: operation
370
+ ? `The connected editor cannot satisfy ${operation}; no alternate editor path was selected.`
371
+ : "The connected editor does not advertise every capability required by this operation.",
170
372
  connectionState: context.connection.state,
373
+ ...(unavailable ? { unavailable } : {}),
171
374
  };
172
375
  }