@morshoto/framekit 0.1.6 → 0.1.11

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 (43) hide show
  1. package/bin/framekit.mjs +2 -1
  2. package/dist-package/adapters/final-cut/typescript/src/assets.js +157 -35
  3. package/dist-package/adapters/final-cut/typescript/src/background-export.js +384 -0
  4. package/dist-package/adapters/final-cut/typescript/src/background-materialization.js +175 -0
  5. package/dist-package/adapters/final-cut/typescript/src/canonical.js +189 -32
  6. package/dist-package/adapters/final-cut/typescript/src/connection.js +55 -17
  7. package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +33 -7
  8. package/dist-package/adapters/final-cut/typescript/src/fcpxml-console-experiment.js +74 -0
  9. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +615 -49
  10. package/dist-package/adapters/final-cut/typescript/src/index.js +10 -0
  11. package/dist-package/adapters/final-cut/typescript/src/library-inspection.js +390 -0
  12. package/dist-package/adapters/final-cut/typescript/src/live.js +16 -6
  13. package/dist-package/adapters/final-cut/typescript/src/media.js +151 -0
  14. package/dist-package/adapters/final-cut/typescript/src/native-session.js +412 -0
  15. package/dist-package/adapters/final-cut/typescript/src/native.js +1192 -364
  16. package/dist-package/adapters/final-cut/typescript/src/publisher.js +225 -32
  17. package/dist-package/adapters/final-cut/typescript/src/session.js +163 -17
  18. package/dist-package/adapters/final-cut/typescript/src/shadow-mutation.js +120 -0
  19. package/dist-package/adapters/final-cut/typescript/src/sqlite-inspection.js +433 -0
  20. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +372 -0
  21. package/dist-package/adapters/final-cut/typescript/src/unattended-editing.js +66 -0
  22. package/dist-package/apps/mcp-server/src/headless-sessions.js +112 -0
  23. package/dist-package/apps/mcp-server/src/main.js +41 -8
  24. package/dist-package/apps/mcp-server/src/materialization-jobs.js +326 -0
  25. package/dist-package/apps/mcp-server/src/routing.js +227 -39
  26. package/dist-package/apps/mcp-server/src/server.js +642 -97
  27. package/dist-package/apps/mcp-server/src/version.js +109 -1
  28. package/dist-package/packages/runtime/src/application/media-analysis-service.js +1 -3
  29. package/dist-package/packages/runtime/src/application/project-service.js +46 -7
  30. package/dist-package/packages/runtime/src/capabilities.js +55 -7
  31. package/dist-package/packages/runtime/src/context/project-catalog.js +159 -0
  32. package/dist-package/packages/runtime/src/domain/capabilities.js +33 -0
  33. package/dist-package/packages/runtime/src/domain/context.js +14 -1
  34. package/dist-package/packages/runtime/src/domain/index.js +1 -0
  35. package/dist-package/packages/runtime/src/domain/timeline-target.js +217 -0
  36. package/dist-package/packages/runtime/src/editing/edit-service.js +15 -1
  37. package/dist-package/packages/runtime/src/editing/intent.js +178 -2
  38. package/dist-package/packages/runtime/src/index.js +3 -0
  39. package/dist-package/packages/runtime/src/runtime.js +2 -2
  40. package/dist-package/packages/runtime/src/timeline/drift-reconciliation.js +295 -0
  41. package/dist-package/packages/runtime/src/timeline/editing-session.js +490 -0
  42. package/dist-package/packages/testkit/src/in-memory-editor.js +5 -4
  43. package/package.json +12 -6
@@ -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,17 +37,20 @@ 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
  ],
@@ -52,24 +74,36 @@ const operationRequirements = {
52
74
  nativeRequirement("timelineFocus"),
53
75
  nativeRequirement("undo"),
54
76
  ],
77
+ "artifact.edit": [
78
+ editorRequirement("projectRead"),
79
+ editorRequirement("timelineSnapshotRead"),
80
+ editorRequirement("timelineArtifactWrite"),
81
+ editorRequirement("readAfterWrite"),
82
+ editorRequirement("rollback"),
83
+ ],
55
84
  "timeline.publish.new-project": [
56
85
  {
86
+ name: "editor.artifactPublish",
57
87
  label: "editor.artifactPublish",
88
+ category: "native-ui",
58
89
  satisfied: (context) => Boolean(context.editor?.capabilities.editor.artifactPublish
59
90
  || context.editor?.capabilities.editor.timelinePublishNewProject),
91
+ descriptor: (context) => context.editor?.capabilities.families?.publishing.projectCreation,
60
92
  },
61
93
  ],
62
- "timeline.export": [
63
- editorRequirement("videoExport"),
64
- ],
94
+ "timeline.export": [editorRequirement("videoExport", "native-ui")],
65
95
  };
66
96
  export function resolveEditingRoute(request, context) {
67
97
  const requirements = operationRequirements[request.operation];
68
98
  const requiredCapabilities = requirements.map((requirement) => requirement.label);
69
- const missingCapabilities = requirements
70
- .filter((requirement) => !requirement.satisfied(context))
71
- .map((requirement) => requirement.label);
99
+ const missingRequirements = requirements.filter((requirement) => !requirement.satisfied(context));
100
+ const missingCapabilities = missingRequirements.map((requirement) => requirement.label);
72
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;
73
107
  if (request.fallback === "external-renderer") {
74
108
  const cause = externalFallbackCause(context, missingCapabilities);
75
109
  return {
@@ -79,7 +113,7 @@ export function resolveEditingRoute(request, context) {
79
113
  requiredCapabilities,
80
114
  missingCapabilities,
81
115
  ...(editor ? { editor } : {}),
82
- workflow: [...EDITOR_FIRST_WORKFLOW],
116
+ workflow: [...workflow],
83
117
  reason: {
84
118
  code: "EXTERNAL_FALLBACK_SELECTED",
85
119
  message: "The external renderer was selected explicitly; Framekit will not invoke it or bypass the editor silently.",
@@ -88,9 +122,10 @@ export function resolveEditingRoute(request, context) {
88
122
  },
89
123
  };
90
124
  }
91
- const offlineArtifactEdit = request.operation === "timeline.edit"
92
- && context.editor?.capabilities.editor.timelineArtifactWrite === true;
93
- 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") {
94
129
  return {
95
130
  operation: request.operation,
96
131
  status: "unavailable",
@@ -98,11 +133,11 @@ export function resolveEditingRoute(request, context) {
98
133
  requiredCapabilities,
99
134
  missingCapabilities,
100
135
  ...(editor ? { editor } : {}),
101
- workflow: [...EDITOR_FIRST_WORKFLOW],
102
- reason: editorUnavailableReason(context, missingCapabilities),
136
+ workflow: [...workflow],
137
+ reason: editorUnavailableReason(context, missingRequirements),
103
138
  };
104
139
  }
105
- if (missingCapabilities.length > 0 || !context.editor) {
140
+ if (missingRequirements.length > 0 || !context.editor) {
106
141
  return {
107
142
  operation: request.operation,
108
143
  status: "unavailable",
@@ -110,41 +145,193 @@ export function resolveEditingRoute(request, context) {
110
145
  requiredCapabilities,
111
146
  missingCapabilities,
112
147
  ...(editor ? { editor } : {}),
113
- workflow: [...EDITOR_FIRST_WORKFLOW],
114
- reason: {
115
- code: "CAPABILITY_UNAVAILABLE",
116
- message: `The connected editor cannot satisfy ${request.operation}; no alternate editor path was selected.`,
117
- connectionState: context.connection.state,
118
- },
148
+ workflow: [...workflow],
149
+ reason: capabilityUnavailableReason(context, missingRequirements, request.operation),
119
150
  };
120
151
  }
152
+ const provider = selectedProvider(request.operation, context);
121
153
  return {
122
154
  operation: request.operation,
123
155
  status: "editor-selected",
124
- selectedPath: "editor",
156
+ selectedPath: selectedPath(request.operation, provider),
125
157
  requiredCapabilities,
126
158
  missingCapabilities: [],
159
+ ...(provider ? { provider } : {}),
127
160
  editor,
128
- workflow: [...EDITOR_FIRST_WORKFLOW],
161
+ workflow: [...workflow],
129
162
  reason: {
130
163
  code: "EDITOR_SELECTED",
131
- message: "The connected editor satisfies the required capabilities; continue with the preview and execute contract.",
164
+ message: selectedMessage(request.operation),
132
165
  connectionState: context.connection.state,
133
166
  },
134
167
  };
135
168
  }
136
- function editorRequirement(capability) {
169
+ function canonicalRequirement() {
137
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) {
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}`,
138
228
  label: `editor.${capability}`,
139
- 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),
140
235
  };
141
236
  }
142
237
  function nativeRequirement(capability) {
143
238
  return {
239
+ name: `native.${capability}`,
144
240
  label: `native.${capability}`,
145
- 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"}`,
146
326
  };
147
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
+ }
148
335
  function externalFallbackCause(context, missingCapabilities) {
149
336
  if (context.connection.state !== "ready") {
150
337
  return context.connection.lastError ?? {
@@ -163,25 +350,26 @@ function externalFallbackCause(context, missingCapabilities) {
163
350
  message: "The caller explicitly selected the external renderer even though the editor is available.",
164
351
  };
165
352
  }
166
- function editorUnavailableReason(context, missingCapabilities) {
353
+ function editorUnavailableReason(context, missingRequirements) {
167
354
  if (context.connection.state !== "ready") {
168
355
  return {
169
356
  code: "EDITOR_UNAVAILABLE",
170
357
  message: `The expected editor is unavailable while the connection is ${context.connection.state}.`,
171
358
  connectionState: context.connection.state,
172
359
  ...(context.connection.lastError ? { cause: context.connection.lastError } : {}),
360
+ ...(unavailableEvidence(context, missingRequirements) ? { unavailable: unavailableEvidence(context, missingRequirements) } : {}),
173
361
  };
174
362
  }
175
- if (missingCapabilities.length > 0 || !context.editor) {
176
- return {
177
- code: "CAPABILITY_UNAVAILABLE",
178
- message: "The connected editor does not advertise every capability required by this operation.",
179
- connectionState: context.connection.state,
180
- };
181
- }
363
+ return capabilityUnavailableReason(context, missingRequirements);
364
+ }
365
+ function capabilityUnavailableReason(context, missingRequirements, operation) {
366
+ const unavailable = unavailableEvidence(context, missingRequirements);
182
367
  return {
183
368
  code: "CAPABILITY_UNAVAILABLE",
184
- 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.",
185
372
  connectionState: context.connection.state,
373
+ ...(unavailable ? { unavailable } : {}),
186
374
  };
187
375
  }