@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.
- package/bin/framekit.mjs +2 -1
- package/dist-package/adapters/final-cut/typescript/src/assets.js +223 -15
- package/dist-package/adapters/final-cut/typescript/src/background-export.js +384 -0
- package/dist-package/adapters/final-cut/typescript/src/canonical.js +588 -0
- package/dist-package/adapters/final-cut/typescript/src/connection.js +20 -5
- package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +33 -7
- package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +805 -51
- package/dist-package/adapters/final-cut/typescript/src/index.js +5 -0
- package/dist-package/adapters/final-cut/typescript/src/library-inspection.js +390 -0
- package/dist-package/adapters/final-cut/typescript/src/live.js +6 -3
- package/dist-package/adapters/final-cut/typescript/src/media.js +151 -0
- package/dist-package/adapters/final-cut/typescript/src/native-session.js +412 -0
- package/dist-package/adapters/final-cut/typescript/src/native.js +2271 -424
- package/dist-package/adapters/final-cut/typescript/src/publisher.js +225 -32
- package/dist-package/adapters/final-cut/typescript/src/session.js +145 -17
- package/dist-package/apps/mcp-server/src/main.js +73 -17
- package/dist-package/apps/mcp-server/src/routing.js +242 -39
- package/dist-package/apps/mcp-server/src/server.js +677 -89
- package/dist-package/apps/mcp-server/src/version.js +109 -1
- package/dist-package/packages/runtime/src/application/media-analysis-service.js +3 -4
- package/dist-package/packages/runtime/src/application/project-service.js +46 -7
- package/dist-package/packages/runtime/src/audio/dialogue-normalization.js +9 -0
- package/dist-package/packages/runtime/src/capabilities.js +62 -9
- package/dist-package/packages/runtime/src/context/project-catalog.js +159 -0
- package/dist-package/packages/runtime/src/domain/capabilities.js +33 -0
- package/dist-package/packages/runtime/src/domain/context.js +14 -1
- package/dist-package/packages/runtime/src/domain/editing.js +27 -1
- package/dist-package/packages/runtime/src/domain/index.js +1 -0
- package/dist-package/packages/runtime/src/domain/skills.js +2 -0
- package/dist-package/packages/runtime/src/domain/timeline-target.js +217 -0
- package/dist-package/packages/runtime/src/editing/edit-service.js +57 -1
- package/dist-package/packages/runtime/src/editing/intent.js +178 -2
- package/dist-package/packages/runtime/src/index.js +1 -0
- package/dist-package/packages/runtime/src/runtime.js +2 -2
- package/dist-package/packages/runtime/src/skills/builtin.js +314 -39
- package/dist-package/packages/runtime/src/skills/requirements.js +1 -0
- package/dist-package/packages/runtime/src/skills/runtime.js +33 -8
- package/dist-package/packages/runtime/src/verification/verification.js +81 -4
- package/dist-package/packages/testkit/src/in-memory-editor.js +130 -4
- 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
|
|
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
|
-
...(
|
|
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:
|
|
73
|
-
|
|
74
|
-
|
|
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
|
|
153
|
+
const nativeOperationSession = disposableNative && nativeEditor
|
|
154
|
+
? createDisposableNativeOperationSession({ workflow: disposableNative, native: nativeEditor })
|
|
155
|
+
: undefined;
|
|
156
|
+
const projectPublisher = liveMode && fcpxmlPath
|
|
109
157
|
? new FinalCutProjectPublisher({
|
|
110
|
-
enabled:
|
|
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
|
|
55
|
-
|
|
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: [...
|
|
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
|
|
78
|
-
|
|
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: [...
|
|
87
|
-
reason: editorUnavailableReason(context,
|
|
136
|
+
workflow: [...workflow],
|
|
137
|
+
reason: editorUnavailableReason(context, missingRequirements),
|
|
88
138
|
};
|
|
89
139
|
}
|
|
90
|
-
if (
|
|
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: [...
|
|
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:
|
|
156
|
+
selectedPath: selectedPath(request.operation, provider),
|
|
110
157
|
requiredCapabilities,
|
|
111
158
|
missingCapabilities: [],
|
|
159
|
+
...(provider ? { provider } : {}),
|
|
112
160
|
editor,
|
|
113
|
-
workflow: [...
|
|
161
|
+
workflow: [...workflow],
|
|
114
162
|
reason: {
|
|
115
163
|
code: "EDITOR_SELECTED",
|
|
116
|
-
message:
|
|
164
|
+
message: selectedMessage(request.operation),
|
|
117
165
|
connectionState: context.connection.state,
|
|
118
166
|
},
|
|
119
167
|
};
|
|
120
168
|
}
|
|
121
|
-
function
|
|
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
|
-
|
|
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
|
-
|
|
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,
|
|
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
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
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:
|
|
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
|
}
|