@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 { execFile as execFileCallback } from "node:child_process";
2
2
  import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
3
- import { createHash } from "node:crypto";
3
+ import { createHash, randomUUID } from "node:crypto";
4
4
  import { basename, join } from "node:path";
5
5
  import { tmpdir } from "node:os";
6
6
  import { promisify } from "node:util";
@@ -11,24 +11,144 @@ export class FinalCutProjectPublisher {
11
11
  sourcePath;
12
12
  executor;
13
13
  liveState;
14
+ targetBinding;
14
15
  verificationTimeoutMs;
15
16
  pollIntervalMs;
17
+ publishJobs = new Map();
18
+ publishJobRuntime = new Map();
16
19
  constructor(options) {
17
20
  this.enabled = options.enabled ?? false;
18
21
  this.sourcePath = options.sourcePath;
19
22
  this.executor = options.executor ?? runAppleScript;
20
23
  this.liveState = options.liveState;
24
+ this.targetBinding = options.targetBinding;
21
25
  this.verificationTimeoutMs = Math.max(0, options.verificationTimeoutMs ?? 15_000);
22
26
  this.pollIntervalMs = Math.max(0, options.pollIntervalMs ?? options.waitMs ?? 100);
23
27
  }
24
28
  isAvailable() {
25
29
  return this.enabled;
26
30
  }
31
+ async preparePublish(request) {
32
+ const { identity } = await this.readValidatedSource(request);
33
+ const job = {
34
+ jobId: `publish-job-${randomUUID()}`,
35
+ state: "awaiting-confirmation",
36
+ nextAction: "confirm",
37
+ retryable: false,
38
+ executionMode: "headed-only",
39
+ sourceTransactionId: request.sourceTransactionId,
40
+ sourcePath: this.sourcePath,
41
+ sourceTarget: { kind: "artifact", artifactPath: this.sourcePath },
42
+ artifactDigest: request.artifactDigest,
43
+ projectName: identity.projectName,
44
+ sequenceName: identity.sequenceName,
45
+ confirmationRequired: true,
46
+ handoff: {
47
+ mode: "headed-only",
48
+ backgroundSupported: false,
49
+ reason: "Final Cut has no supported non-UI project publishing contract; use the explicit headed handoff and verify the created target.",
50
+ },
51
+ };
52
+ this.publishJobs.set(job.jobId, job);
53
+ return clonePublishJob(job);
54
+ }
55
+ getPublishJob(jobId) {
56
+ const job = this.publishJobs.get(jobId);
57
+ if (!job)
58
+ throw new Error(`PUBLISH_JOB_NOT_FOUND: unknown publish job ${jobId}`);
59
+ return clonePublishJob(job);
60
+ }
61
+ async executePublishJob(jobId, confirm) {
62
+ const job = this.publishJobs.get(jobId);
63
+ if (!job)
64
+ throw new Error(`PUBLISH_JOB_NOT_FOUND: unknown publish job ${jobId}`);
65
+ if (job.state === "verified")
66
+ return clonePublishJob(job);
67
+ if (job.state === "failed" && !job.retryable)
68
+ return clonePublishJob(job);
69
+ if (!confirm)
70
+ throw new Error("PUBLISH_CONFIRMATION_REQUIRED: set confirm=true to create a new Final Cut project");
71
+ if (!this.enabled) {
72
+ job.state = "awaiting-final-cut";
73
+ job.nextAction = "retry";
74
+ job.retryable = true;
75
+ job.error = {
76
+ code: "CAPABILITY_UNAVAILABLE",
77
+ message: "Final Cut project publishing is unavailable; bring Final Cut Pro to the front and retry this job",
78
+ };
79
+ return clonePublishJob(job);
80
+ }
81
+ if (!this.liveState)
82
+ return this.markAwaitingFinalCut(job, "FINAL_CUT_PUBLISH_VERIFICATION_UNAVAILABLE", "Final Cut project state verification is unavailable; retry this job when the live provider is ready");
83
+ if (job.state === "verification-pending")
84
+ return this.resumePublishVerification(job);
85
+ let validated;
86
+ try {
87
+ validated = await this.readValidatedSource({
88
+ sourceTransactionId: job.sourceTransactionId,
89
+ artifactPath: job.sourcePath,
90
+ artifactDigest: job.artifactDigest,
91
+ });
92
+ }
93
+ catch (error) {
94
+ return this.markFailed(job, error);
95
+ }
96
+ let targetBinding;
97
+ try {
98
+ if (!this.targetBinding) {
99
+ throw new Error("FINAL_CUT_PUBLISH_TARGET_BINDING_UNAVAILABLE: no native provider can bind the imported artifact to a created target; no import was attempted");
100
+ }
101
+ targetBinding = await this.targetBinding();
102
+ if (!targetBinding.projectId.trim() || !targetBinding.sequenceId.trim()) {
103
+ throw new Error("FINAL_CUT_PUBLISH_TARGET_BINDING_UNAVAILABLE: native target binding did not return project and sequence identities; no import was attempted");
104
+ }
105
+ }
106
+ catch (error) {
107
+ return this.markFailed(job, error);
108
+ }
109
+ let beforeLive;
110
+ try {
111
+ beforeLive = await readLiveState(this.liveState, "before import");
112
+ }
113
+ catch (error) {
114
+ const normalized = publishError(error);
115
+ return this.markAwaitingFinalCut(job, normalized.code, normalized.message);
116
+ }
117
+ const runtime = { beforeLive, identity: validated.identity, targetBinding };
118
+ this.publishJobRuntime.set(job.jobId, runtime);
119
+ job.state = "verification-pending";
120
+ job.nextAction = "status";
121
+ job.retryable = false;
122
+ try {
123
+ const result = await this.importAndVerify({
124
+ sourceTransactionId: job.sourceTransactionId,
125
+ artifactPath: job.sourcePath,
126
+ artifactDigest: job.artifactDigest,
127
+ confirm: true,
128
+ }, validated.source, validated.identity, beforeLive, runtime);
129
+ return this.markVerified(job, result);
130
+ }
131
+ catch (error) {
132
+ job.state = "verification-pending";
133
+ job.nextAction = "retry";
134
+ job.retryable = true;
135
+ job.error = publishError(error);
136
+ return clonePublishJob(job);
137
+ }
138
+ }
27
139
  async publishNewProject(request) {
28
140
  if (!this.enabled)
29
141
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing is disabled; configure FRAMEKIT_EDITOR=final-cut-live and FRAMEKIT_FCPXML_PATH, and ensure Final Cut is reachable through FRAMEKIT_FINAL_CUT_SOCKET");
30
142
  if (!request.confirm)
31
143
  throw new Error("PUBLISH_CONFIRMATION_REQUIRED: set confirm=true to create a new Final Cut project");
144
+ const { source, identity } = await this.readValidatedSource(request);
145
+ if (!this.liveState) {
146
+ throw new Error("FINAL_CUT_PUBLISH_VERIFICATION_UNAVAILABLE: live project and sequence state is required");
147
+ }
148
+ const beforeLive = await readLiveState(this.liveState, "before import");
149
+ return this.importAndVerify(request, source, identity, beforeLive);
150
+ }
151
+ async readValidatedSource(request) {
32
152
  if (!request.sourceTransactionId.trim())
33
153
  throw new Error("INVALID_PUBLISH_REQUEST: sourceTransactionId is required");
34
154
  if (!request.artifactDigest.trim())
@@ -43,46 +163,77 @@ export class FinalCutProjectPublisher {
43
163
  if (!source.includes("<fcpxml") || !source.includes("<project")) {
44
164
  throw new Error("FINAL_CUT_PUBLISH_VALIDATION_FAILED: source is not a valid FCPXML project artifact");
45
165
  }
46
- const identity = projectIdentityFromXml(source);
47
- if (!this.liveState) {
166
+ return { source, identity: projectIdentityFromXml(source) };
167
+ }
168
+ async importAndVerify(request, source, identity, beforeLive, runtime) {
169
+ if (!this.liveState)
48
170
  throw new Error("FINAL_CUT_PUBLISH_VERIFICATION_UNAVAILABLE: live project and sequence state is required");
171
+ if (runtime && !runtime.targetBinding) {
172
+ throw new Error("FINAL_CUT_PUBLISH_TARGET_BINDING_UNAVAILABLE: no stable created-target identity was retained across verification; no publish success was reported");
49
173
  }
50
- const beforeLive = await readLiveState(this.liveState, "before import");
51
174
  const directory = await mkdtemp(join(tmpdir(), "framekit-finalcut-publish-"));
52
175
  const importedPath = join(directory, basename(this.sourcePath));
176
+ if (runtime)
177
+ runtime.importedPath = importedPath;
53
178
  await writeFile(importedPath, source, "utf8");
54
179
  try {
55
180
  await this.executor(importXmlScript(importedPath));
56
- const live = await waitForImportedProject(this.liveState, identity, beforeLive, this.verificationTimeoutMs, this.pollIntervalMs);
57
- return {
58
- sourceTransactionId: request.sourceTransactionId,
59
- sourcePath: this.sourcePath,
60
- sourceTarget: { kind: "artifact", artifactPath: this.sourcePath },
61
- importedPath,
62
- projectName: identity.projectName,
63
- createdTarget: {
64
- kind: "editor.project",
65
- ...(live?.project?.id ? { projectId: live.project.id } : {}),
66
- ...(live?.sequence?.id ? { sequenceId: live.sequence.id } : {}),
67
- projectName: identity.projectName,
68
- ...(live?.sequence?.name ? { sequenceName: live.sequence.name } : {}),
69
- },
70
- activeProject: {
71
- ...(beforeLive.project ? { before: beforeLive.project } : {}),
72
- ...(live.project ? { after: live.project } : {}),
73
- ...(beforeLive.project && live.project
74
- ? { changed: beforeLive.project.id !== live.project.id || beforeLive.project.name !== live.project.name }
75
- : {}),
76
- },
77
- verified: true,
78
- ...(live.project?.name ? { liveProject: live.project.name } : {}),
79
- ...(live.sequence?.name ? { liveSequence: live.sequence.name } : {}),
80
- };
181
+ const live = await waitForImportedProject(this.liveState, identity, beforeLive, runtime?.targetBinding, this.verificationTimeoutMs, this.pollIntervalMs);
182
+ return publishResult(request, importedPath, identity, beforeLive, live);
81
183
  }
82
184
  finally {
83
185
  await rm(directory, { recursive: true, force: true });
84
186
  }
85
187
  }
188
+ async resumePublishVerification(job) {
189
+ const runtime = this.publishJobRuntime.get(job.jobId);
190
+ if (!runtime || !this.liveState) {
191
+ return this.markAwaitingFinalCut(job, "FINAL_CUT_PUBLISH_VERIFICATION_UNAVAILABLE", "Final Cut project state verification is unavailable; retry this job when the live provider is ready");
192
+ }
193
+ if (!runtime.targetBinding) {
194
+ return this.markFailed(job, new Error("FINAL_CUT_PUBLISH_TARGET_BINDING_UNAVAILABLE: no stable created-target identity was retained across verification; no publish success was reported"));
195
+ }
196
+ try {
197
+ const live = await waitForImportedProject(this.liveState, runtime.identity, runtime.beforeLive, runtime.targetBinding, this.verificationTimeoutMs, this.pollIntervalMs);
198
+ const result = publishResult({
199
+ sourceTransactionId: job.sourceTransactionId,
200
+ artifactPath: job.sourcePath,
201
+ artifactDigest: job.artifactDigest,
202
+ confirm: true,
203
+ }, runtime.importedPath ?? job.sourcePath, runtime.identity, runtime.beforeLive, live);
204
+ return this.markVerified(job, result);
205
+ }
206
+ catch (error) {
207
+ job.state = "verification-pending";
208
+ job.nextAction = "retry";
209
+ job.retryable = true;
210
+ job.error = publishError(error);
211
+ return clonePublishJob(job);
212
+ }
213
+ }
214
+ markVerified(job, result) {
215
+ job.state = "verified";
216
+ job.nextAction = "none";
217
+ job.retryable = false;
218
+ job.createdTarget = structuredClone(result.createdTarget);
219
+ job.result = structuredClone(result);
220
+ delete job.error;
221
+ return clonePublishJob(job);
222
+ }
223
+ markAwaitingFinalCut(job, code, message) {
224
+ job.state = "awaiting-final-cut";
225
+ job.nextAction = "retry";
226
+ job.retryable = true;
227
+ job.error = { code, message };
228
+ return clonePublishJob(job);
229
+ }
230
+ markFailed(job, error) {
231
+ job.state = "failed";
232
+ job.nextAction = "none";
233
+ job.retryable = false;
234
+ job.error = publishError(error);
235
+ return clonePublishJob(job);
236
+ }
86
237
  }
87
238
  async function runAppleScript(script) {
88
239
  try {
@@ -271,7 +422,7 @@ async function readLiveState(liveState, phase) {
271
422
  throw new Error(`FINAL_CUT_PUBLISH_STATE_UNAVAILABLE: ${phase}: ${detail}`);
272
423
  }
273
424
  }
274
- async function waitForImportedProject(liveState, identity, before, timeoutMs, pollIntervalMs) {
425
+ async function waitForImportedProject(liveState, identity, before, targetBinding, timeoutMs, pollIntervalMs) {
275
426
  const deadline = Date.now() + timeoutMs;
276
427
  let latest;
277
428
  let lastError;
@@ -279,7 +430,7 @@ async function waitForImportedProject(liveState, identity, before, timeoutMs, po
279
430
  try {
280
431
  latest = await readLiveState(liveState, "after import");
281
432
  lastError = undefined;
282
- if (isImportedProject(latest, identity, before))
433
+ if (isImportedProject(latest, identity, before, targetBinding))
283
434
  return latest;
284
435
  }
285
436
  catch (error) {
@@ -293,13 +444,20 @@ async function waitForImportedProject(liveState, identity, before, timeoutMs, po
293
444
  throw lastError;
294
445
  const observedProject = latest?.project?.name ?? "none";
295
446
  const observedSequence = latest?.sequence?.name ?? "none";
447
+ if (targetBinding && latest?.project && latest.sequence
448
+ && (latest.project.id !== targetBinding.projectId || latest.sequence.id !== targetBinding.sequenceId)) {
449
+ throw new Error(`FINAL_CUT_PUBLISH_TARGET_MISMATCH: expected bound target ${targetBinding.projectId}/${targetBinding.sequenceId}, observed ${latest.project.id}/${latest.sequence.id}`);
450
+ }
296
451
  throw new Error(`FINAL_CUT_PUBLISH_VERIFICATION_FAILED: expected new project ${identity.projectName} / sequence ${identity.sequenceName}, observed ${observedProject} / ${observedSequence}`);
297
452
  }
298
- function isImportedProject(live, identity, before) {
453
+ function isImportedProject(live, identity, before, targetBinding) {
299
454
  if (!live.project || !live.sequence)
300
455
  return false;
301
456
  if (live.project.name !== identity.projectName || live.sequence.name !== identity.sequenceName)
302
457
  return false;
458
+ if (targetBinding
459
+ && (live.project.id !== targetBinding.projectId || live.sequence.id !== targetBinding.sequenceId))
460
+ return false;
303
461
  if (before.project && live.project.id === before.project.id)
304
462
  return false;
305
463
  if (before.sequence && live.sequence.id === before.sequence.id)
@@ -312,3 +470,38 @@ function delay(milliseconds) {
312
470
  function hash(content) {
313
471
  return createHash("sha256").update(content).digest("hex");
314
472
  }
473
+ function clonePublishJob(job) {
474
+ return structuredClone(job);
475
+ }
476
+ function publishResult(request, importedPath, identity, beforeLive, live) {
477
+ return {
478
+ sourceTransactionId: request.sourceTransactionId,
479
+ sourcePath: request.artifactPath,
480
+ sourceTarget: { kind: "artifact", artifactPath: request.artifactPath },
481
+ importedPath,
482
+ projectName: identity.projectName,
483
+ createdTarget: {
484
+ kind: "editor.project",
485
+ ...(live.project?.id ? { projectId: live.project.id } : {}),
486
+ ...(live.sequence?.id ? { sequenceId: live.sequence.id } : {}),
487
+ projectName: identity.projectName,
488
+ ...(live.sequence?.name ? { sequenceName: live.sequence.name } : {}),
489
+ },
490
+ activeProject: {
491
+ ...(beforeLive.project ? { before: beforeLive.project } : {}),
492
+ ...(live.project ? { after: live.project } : {}),
493
+ ...(beforeLive.project && live.project
494
+ ? { changed: beforeLive.project.id !== live.project.id || beforeLive.project.name !== live.project.name }
495
+ : {}),
496
+ },
497
+ verified: true,
498
+ ...(live.project?.name ? { liveProject: live.project.name } : {}),
499
+ ...(live.sequence?.name ? { liveSequence: live.sequence.name } : {}),
500
+ };
501
+ }
502
+ function publishError(error) {
503
+ const message = error instanceof Error ? error.message : String(error);
504
+ const separator = message.indexOf(":");
505
+ const code = separator > 0 ? message.slice(0, separator) : "FINAL_CUT_PUBLISH_FAILED";
506
+ return { code, message };
507
+ }
@@ -1,4 +1,4 @@
1
- import { withCanonicalTimelineMode, withCapabilityFamilies } from "../../../../packages/runtime/src/index.js";
1
+ import { projectSelectionMode, reconcileProjectCatalog, validateProjectCatalog, withCanonicalTimelineMode, withCapabilityFamilies, } from "../../../../packages/runtime/src/index.js";
2
2
  /** Composes the independent Final Cut live, snapshot, and mutation surfaces. */
3
3
  export class FinalCutSessionAdapter {
4
4
  options;
@@ -17,8 +17,14 @@ export class FinalCutSessionAdapter {
17
17
  }
18
18
  if (this.options.snapshot)
19
19
  return this.options.snapshot.getIdentity();
20
- if (this.options.live)
21
- return this.options.live.getIdentity();
20
+ if (this.options.live) {
21
+ try {
22
+ return await this.options.live.getIdentity();
23
+ }
24
+ catch {
25
+ return { name: "Final Cut Pro", version: "unknown", backend: "final-cut-session" };
26
+ }
27
+ }
22
28
  return { name: "Final Cut Pro", version: "unknown", backend: "final-cut-session" };
23
29
  }
24
30
  async getManagedArtifact() {
@@ -29,10 +35,10 @@ export class FinalCutSessionAdapter {
29
35
  async getManagedArtifactDigest() {
30
36
  return this.options.snapshot?.getManagedArtifactDigest?.();
31
37
  }
32
- async getCapabilities() {
33
- const snapshot = await this.options.snapshot?.getCapabilities();
34
- const mutation = await this.options.mutation?.getCapabilities();
35
- const live = await optionalCapabilities(this.options.live);
38
+ async getCapabilities(options = {}) {
39
+ const snapshot = await this.options.snapshot?.getCapabilities(options);
40
+ const mutation = await this.options.mutation?.getCapabilities(options);
41
+ const live = await optionalCapabilities(this.options.live, options);
36
42
  const hasExplicitDocumentPair = Boolean(this.options.snapshot && this.options.mutation);
37
43
  const useLiveCanonical = !this.options.snapshot && !this.options.mutation;
38
44
  const liveSnapshot = Boolean(useLiveCanonical
@@ -68,7 +74,24 @@ export class FinalCutSessionAdapter {
68
74
  && hasTransactionMethods
69
75
  && canReadAfterWrite);
70
76
  const operationFamilies = operationRuntimeCapabilities?.families;
71
- const readFamilies = readCapabilities?.families;
77
+ const readFamilies = readCapabilities?.families
78
+ ?? (!this.options.snapshot && !this.options.mutation ? live?.families : undefined);
79
+ const backgroundMediaDiscovery = Boolean(this.options.media?.listMedia);
80
+ const backgroundLibraryInspection = Boolean(operationCapabilities?.backgroundLibraryInspection
81
+ || this.options.backgroundCatalog
82
+ || (!this.options.snapshot
83
+ && this.options.live?.listProjects
84
+ && live?.editor.projectCatalogRead
85
+ && live.editor.canonicalTimelineMode === "metadata-only"));
86
+ const backgroundLibrary = backgroundLibraryInspection
87
+ ? readFamilies?.observation.library.available
88
+ ? readFamilies.observation.library
89
+ : {
90
+ available: true,
91
+ backend: "final-cut-background-library",
92
+ guarantee: "observed",
93
+ }
94
+ : false;
72
95
  return withCapabilityFamilies({
73
96
  editor: {
74
97
  ...operationCapabilities,
@@ -80,11 +103,16 @@ export class FinalCutSessionAdapter {
80
103
  incrementalChanges: Boolean(live?.editor.incrementalChanges),
81
104
  rollback: Boolean(operationCapabilities?.rollback && operationAdapter?.restore),
82
105
  assetDiscovery: Boolean(snapshot?.editor.assetDiscovery || this.options.assets?.listAssets),
106
+ backgroundMediaDiscovery,
107
+ backgroundTemplateDiscovery: Boolean(this.options.assets),
108
+ backgroundLibraryInspection,
83
109
  liveStateRead: Boolean(live?.editor.liveStateRead),
84
110
  playheadWrite: Boolean(live?.editor.playheadWrite),
85
111
  frameCapture: false,
86
112
  playbackControl: Boolean(live?.editor.playbackControl),
87
- projectCatalogRead: Boolean(snapshot?.editor.projectCatalogRead || (!this.options.snapshot && live?.editor.projectCatalogRead)),
113
+ projectCatalogRead: Boolean(snapshot?.editor.projectCatalogRead
114
+ || (!this.options.snapshot && live?.editor.projectCatalogRead)
115
+ || this.options.backgroundCatalog),
88
116
  projectSelection: Boolean(snapshot?.editor.projectSelection || (!this.options.snapshot && live?.editor.projectSelection)),
89
117
  compositeTransactions,
90
118
  },
@@ -96,9 +124,20 @@ export class FinalCutSessionAdapter {
96
124
  },
97
125
  }, {
98
126
  backend: "final-cut-session",
127
+ observation: {
128
+ library: backgroundLibrary,
129
+ ...(backgroundMediaDiscovery ? {
130
+ media: { available: true, backend: "filesystem-media", guarantee: "observed" },
131
+ } : {}),
132
+ ...(this.options.assets ? {
133
+ assets: { available: true, backend: "filesystem-motion-template", guarantee: "observed" },
134
+ } : {}),
135
+ },
99
136
  canonicalDocument: {
100
137
  read: readFamilies?.canonicalDocument.read ?? Boolean(readCapabilities?.editor.timelineSnapshotRead),
101
- write: operationFamilies?.canonicalDocument.write ?? Boolean(operationCapabilities?.timelineWrite),
138
+ write: operationFamilies?.canonicalDocument.write
139
+ ?? readFamilies?.canonicalDocument.write
140
+ ?? Boolean(operationCapabilities?.timelineWrite),
102
141
  artifactWrite: operationFamilies?.canonicalDocument.artifactWrite ?? Boolean(operationCapabilities?.timelineArtifactWrite),
103
142
  },
104
143
  editing: {
@@ -182,14 +221,95 @@ export class FinalCutSessionAdapter {
182
221
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut assets");
183
222
  return provider.listAssets(query);
184
223
  }
224
+ async listMedia(query) {
225
+ if (this.options.media?.listMedia)
226
+ return this.options.media.listMedia(query);
227
+ if (this.options.snapshot?.readProject) {
228
+ const project = await this.options.snapshot.readProject();
229
+ const normalized = query?.query?.trim().toLowerCase();
230
+ return project.media
231
+ .filter((media) => !query?.mediaKind || media.mediaKind === query.mediaKind)
232
+ .filter((media) => !normalized
233
+ || media.mediaId.toLowerCase().includes(normalized)
234
+ || media.source.toLowerCase().includes(normalized));
235
+ }
236
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut media discovery");
237
+ }
185
238
  async listProjects() {
186
239
  if (this.options.snapshot?.listProjects)
187
240
  return this.options.snapshot.listProjects();
188
- if (!this.options.snapshot && this.options.live?.listProjects && (await optionalProjectCatalogCapability(this.options.live))) {
189
- return this.options.live.listProjects();
241
+ if (this.options.backgroundCatalog)
242
+ return this.readBackgroundCatalog(this.options.backgroundCatalog);
243
+ const live = this.options.live;
244
+ const capabilities = await optionalCapabilities(live, { probeCanonicalSnapshot: false });
245
+ if (!this.options.snapshot && live?.listProjects && capabilities?.editor.projectCatalogRead) {
246
+ const before = await optionalLiveState(live);
247
+ const catalog = await live.listProjects();
248
+ validateProjectCatalog(catalog);
249
+ if (catalog.provenance || capabilities.editor.canonicalTimelineMode !== "metadata-only")
250
+ return catalog;
251
+ const after = await optionalLiveState(live);
252
+ const identity = await optionalIdentity(live);
253
+ const selectionMode = projectSelectionMode(capabilities.editor);
254
+ const selectionAvailable = Boolean(live.selectProject
255
+ && capabilities.editor.projectSelection
256
+ && selectionMode !== "unavailable");
257
+ return reconcileProjectCatalog(catalog, {
258
+ ...(before && after ? { before, after } : {}),
259
+ provenance: {
260
+ catalog: {
261
+ source: "live-socket-catalog",
262
+ backend: identity?.backend ?? "final-cut-live",
263
+ guarantee: "observed",
264
+ },
265
+ ...(before && after ? {
266
+ live: {
267
+ source: "live-socket",
268
+ backend: identity?.backend ?? "final-cut-live",
269
+ guarantee: "observed",
270
+ },
271
+ } : {}),
272
+ selection: {
273
+ available: selectionAvailable,
274
+ mode: selectionAvailable ? selectionMode : "unavailable",
275
+ ...(!selectionAvailable ? {
276
+ unavailableReason: "project selection is not exposed by the live provider",
277
+ } : {}),
278
+ },
279
+ },
280
+ });
190
281
  }
191
282
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project catalog");
192
283
  }
284
+ async readBackgroundCatalog(provider) {
285
+ const before = await optionalLiveState(this.options.live);
286
+ const catalog = await provider.listProjects();
287
+ validateProjectCatalog(catalog);
288
+ const after = await optionalLiveState(this.options.live);
289
+ const identity = before && after ? await optionalIdentity(this.options.live) : undefined;
290
+ return reconcileProjectCatalog(catalog, {
291
+ ...(before && after ? { before, after } : {}),
292
+ provenance: {
293
+ catalog: {
294
+ source: "background-library",
295
+ backend: provider.backend ?? "final-cut-background-library",
296
+ guarantee: "observed",
297
+ },
298
+ ...(identity ? {
299
+ live: {
300
+ source: "live-socket",
301
+ backend: identity.backend,
302
+ guarantee: "observed",
303
+ },
304
+ } : {}),
305
+ selection: {
306
+ available: false,
307
+ mode: "unavailable",
308
+ unavailableReason: "project selection is not exposed by the background provider",
309
+ },
310
+ },
311
+ });
312
+ }
193
313
  async selectProject(selection) {
194
314
  if (this.options.snapshot?.selectProject)
195
315
  return this.options.snapshot.selectProject(selection);
@@ -220,22 +340,30 @@ export class FinalCutSessionAdapter {
220
340
  return this.options.snapshot;
221
341
  }
222
342
  }
223
- async function optionalCapabilities(live) {
343
+ async function optionalCapabilities(live, options = {}) {
224
344
  if (!live)
225
345
  return undefined;
226
346
  try {
227
- return withCanonicalTimelineMode(await live.getCapabilities());
347
+ return withCanonicalTimelineMode(await live.getCapabilities(options));
228
348
  }
229
349
  catch {
230
350
  return undefined;
231
351
  }
232
352
  }
233
- async function optionalProjectCatalogCapability(live) {
353
+ async function optionalLiveState(live) {
234
354
  try {
235
- return Boolean((await live?.getCapabilities())?.editor.projectCatalogRead);
355
+ return live ? await live.readLiveState() : undefined;
236
356
  }
237
357
  catch {
238
- return false;
358
+ return undefined;
359
+ }
360
+ }
361
+ async function optionalIdentity(live) {
362
+ try {
363
+ return live ? await live.getIdentity() : undefined;
364
+ }
365
+ catch {
366
+ return undefined;
239
367
  }
240
368
  }
241
369
  async function optionalProjectSelectionCapability(live) {