@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
@@ -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,18 @@ 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
+ const liveOnly = this.pureLiveProvider();
21
+ if (liveOnly) {
22
+ return liveOnly.getIdentity();
23
+ }
24
+ if (this.options.live) {
25
+ try {
26
+ return await this.options.live.getIdentity();
27
+ }
28
+ catch {
29
+ return { name: "Final Cut Pro", version: "unknown", backend: "final-cut-session" };
30
+ }
31
+ }
22
32
  return { name: "Final Cut Pro", version: "unknown", backend: "final-cut-session" };
23
33
  }
24
34
  async getManagedArtifact() {
@@ -29,10 +39,13 @@ export class FinalCutSessionAdapter {
29
39
  async getManagedArtifactDigest() {
30
40
  return this.options.snapshot?.getManagedArtifactDigest?.();
31
41
  }
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);
42
+ async getCapabilities(options = {}) {
43
+ const snapshot = await this.options.snapshot?.getCapabilities(options);
44
+ const mutation = await this.options.mutation?.getCapabilities(options);
45
+ const liveOnly = this.pureLiveProvider();
46
+ const live = liveOnly
47
+ ? withCanonicalTimelineMode(await liveOnly.getCapabilities(options))
48
+ : await optionalCapabilities(this.options.live, options);
36
49
  const hasExplicitDocumentPair = Boolean(this.options.snapshot && this.options.mutation);
37
50
  const useLiveCanonical = !this.options.snapshot && !this.options.mutation;
38
51
  const liveSnapshot = Boolean(useLiveCanonical
@@ -68,7 +81,24 @@ export class FinalCutSessionAdapter {
68
81
  && hasTransactionMethods
69
82
  && canReadAfterWrite);
70
83
  const operationFamilies = operationRuntimeCapabilities?.families;
71
- const readFamilies = readCapabilities?.families;
84
+ const readFamilies = readCapabilities?.families
85
+ ?? (!this.options.snapshot && !this.options.mutation ? live?.families : undefined);
86
+ const backgroundMediaDiscovery = Boolean(this.options.media?.listMedia);
87
+ const backgroundLibraryInspection = Boolean(operationCapabilities?.backgroundLibraryInspection
88
+ || this.options.backgroundCatalog
89
+ || (!this.options.snapshot
90
+ && this.options.live?.listProjects
91
+ && live?.editor.projectCatalogRead
92
+ && live.editor.canonicalTimelineMode === "metadata-only"));
93
+ const backgroundLibrary = backgroundLibraryInspection
94
+ ? readFamilies?.observation.library.available
95
+ ? readFamilies.observation.library
96
+ : {
97
+ available: true,
98
+ backend: "final-cut-background-library",
99
+ guarantee: "observed",
100
+ }
101
+ : false;
72
102
  return withCapabilityFamilies({
73
103
  editor: {
74
104
  ...operationCapabilities,
@@ -80,11 +110,16 @@ export class FinalCutSessionAdapter {
80
110
  incrementalChanges: Boolean(live?.editor.incrementalChanges),
81
111
  rollback: Boolean(operationCapabilities?.rollback && operationAdapter?.restore),
82
112
  assetDiscovery: Boolean(snapshot?.editor.assetDiscovery || this.options.assets?.listAssets),
113
+ backgroundMediaDiscovery,
114
+ backgroundTemplateDiscovery: Boolean(this.options.assets),
115
+ backgroundLibraryInspection,
83
116
  liveStateRead: Boolean(live?.editor.liveStateRead),
84
117
  playheadWrite: Boolean(live?.editor.playheadWrite),
85
118
  frameCapture: false,
86
119
  playbackControl: Boolean(live?.editor.playbackControl),
87
- projectCatalogRead: Boolean(snapshot?.editor.projectCatalogRead || (!this.options.snapshot && live?.editor.projectCatalogRead)),
120
+ projectCatalogRead: Boolean(snapshot?.editor.projectCatalogRead
121
+ || (!this.options.snapshot && live?.editor.projectCatalogRead)
122
+ || this.options.backgroundCatalog),
88
123
  projectSelection: Boolean(snapshot?.editor.projectSelection || (!this.options.snapshot && live?.editor.projectSelection)),
89
124
  compositeTransactions,
90
125
  },
@@ -96,9 +131,20 @@ export class FinalCutSessionAdapter {
96
131
  },
97
132
  }, {
98
133
  backend: "final-cut-session",
134
+ observation: {
135
+ library: backgroundLibrary,
136
+ ...(backgroundMediaDiscovery ? {
137
+ media: { available: true, backend: "filesystem-media", guarantee: "observed" },
138
+ } : {}),
139
+ ...(this.options.assets ? {
140
+ assets: { available: true, backend: "filesystem-motion-template", guarantee: "observed" },
141
+ } : {}),
142
+ },
99
143
  canonicalDocument: {
100
144
  read: readFamilies?.canonicalDocument.read ?? Boolean(readCapabilities?.editor.timelineSnapshotRead),
101
- write: operationFamilies?.canonicalDocument.write ?? Boolean(operationCapabilities?.timelineWrite),
145
+ write: operationFamilies?.canonicalDocument.write
146
+ ?? readFamilies?.canonicalDocument.write
147
+ ?? Boolean(operationCapabilities?.timelineWrite),
102
148
  artifactWrite: operationFamilies?.canonicalDocument.artifactWrite ?? Boolean(operationCapabilities?.timelineArtifactWrite),
103
149
  },
104
150
  editing: {
@@ -182,14 +228,95 @@ export class FinalCutSessionAdapter {
182
228
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut assets");
183
229
  return provider.listAssets(query);
184
230
  }
231
+ async listMedia(query) {
232
+ if (this.options.media?.listMedia)
233
+ return this.options.media.listMedia(query);
234
+ if (this.options.snapshot?.readProject) {
235
+ const project = await this.options.snapshot.readProject();
236
+ const normalized = query?.query?.trim().toLowerCase();
237
+ return project.media
238
+ .filter((media) => !query?.mediaKind || media.mediaKind === query.mediaKind)
239
+ .filter((media) => !normalized
240
+ || media.mediaId.toLowerCase().includes(normalized)
241
+ || media.source.toLowerCase().includes(normalized));
242
+ }
243
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut media discovery");
244
+ }
185
245
  async listProjects() {
186
246
  if (this.options.snapshot?.listProjects)
187
247
  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();
248
+ if (this.options.backgroundCatalog)
249
+ return this.readBackgroundCatalog(this.options.backgroundCatalog);
250
+ const live = this.options.live;
251
+ const capabilities = await optionalCapabilities(live, { probeCanonicalSnapshot: false });
252
+ if (!this.options.snapshot && live?.listProjects && capabilities?.editor.projectCatalogRead) {
253
+ const before = await optionalLiveState(live);
254
+ const catalog = await live.listProjects();
255
+ validateProjectCatalog(catalog);
256
+ if (catalog.provenance || capabilities.editor.canonicalTimelineMode !== "metadata-only")
257
+ return catalog;
258
+ const after = await optionalLiveState(live);
259
+ const identity = await optionalIdentity(live);
260
+ const selectionMode = projectSelectionMode(capabilities.editor);
261
+ const selectionAvailable = Boolean(live.selectProject
262
+ && capabilities.editor.projectSelection
263
+ && selectionMode !== "unavailable");
264
+ return reconcileProjectCatalog(catalog, {
265
+ ...(before && after ? { before, after } : {}),
266
+ provenance: {
267
+ catalog: {
268
+ source: "live-socket-catalog",
269
+ backend: identity?.backend ?? "final-cut-live",
270
+ guarantee: "observed",
271
+ },
272
+ ...(before && after ? {
273
+ live: {
274
+ source: "live-socket",
275
+ backend: identity?.backend ?? "final-cut-live",
276
+ guarantee: "observed",
277
+ },
278
+ } : {}),
279
+ selection: {
280
+ available: selectionAvailable,
281
+ mode: selectionAvailable ? selectionMode : "unavailable",
282
+ ...(!selectionAvailable ? {
283
+ unavailableReason: "project selection is not exposed by the live provider",
284
+ } : {}),
285
+ },
286
+ },
287
+ });
190
288
  }
191
289
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project catalog");
192
290
  }
291
+ async readBackgroundCatalog(provider) {
292
+ const before = await optionalLiveState(this.options.live);
293
+ const catalog = await provider.listProjects();
294
+ validateProjectCatalog(catalog);
295
+ const after = await optionalLiveState(this.options.live);
296
+ const identity = before && after ? await optionalIdentity(this.options.live) : undefined;
297
+ return reconcileProjectCatalog(catalog, {
298
+ ...(before && after ? { before, after } : {}),
299
+ provenance: {
300
+ catalog: {
301
+ source: "background-library",
302
+ backend: provider.backend ?? "final-cut-background-library",
303
+ guarantee: "observed",
304
+ },
305
+ ...(identity ? {
306
+ live: {
307
+ source: "live-socket",
308
+ backend: identity.backend,
309
+ guarantee: "observed",
310
+ },
311
+ } : {}),
312
+ selection: {
313
+ available: false,
314
+ mode: "unavailable",
315
+ unavailableReason: "project selection is not exposed by the background provider",
316
+ },
317
+ },
318
+ });
319
+ }
193
320
  async selectProject(selection) {
194
321
  if (this.options.snapshot?.selectProject)
195
322
  return this.options.snapshot.selectProject(selection);
@@ -208,6 +335,17 @@ export class FinalCutSessionAdapter {
208
335
  throw new Error("CAPABILITY_UNAVAILABLE: live Final Cut editor state");
209
336
  return this.options.live.liveChangesSince(revision, waitMs);
210
337
  }
338
+ pureLiveProvider() {
339
+ if (!this.options.live
340
+ || this.options.snapshot
341
+ || this.options.mutation
342
+ || this.options.assets
343
+ || this.options.media
344
+ || this.options.backgroundCatalog) {
345
+ return undefined;
346
+ }
347
+ return this.options.live;
348
+ }
211
349
  async routedTransactionProvider() {
212
350
  if (this.options.snapshot && this.options.mutation)
213
351
  return this.options.mutation;
@@ -220,22 +358,30 @@ export class FinalCutSessionAdapter {
220
358
  return this.options.snapshot;
221
359
  }
222
360
  }
223
- async function optionalCapabilities(live) {
361
+ async function optionalCapabilities(live, options = {}) {
224
362
  if (!live)
225
363
  return undefined;
226
364
  try {
227
- return withCanonicalTimelineMode(await live.getCapabilities());
365
+ return withCanonicalTimelineMode(await live.getCapabilities(options));
228
366
  }
229
367
  catch {
230
368
  return undefined;
231
369
  }
232
370
  }
233
- async function optionalProjectCatalogCapability(live) {
371
+ async function optionalLiveState(live) {
234
372
  try {
235
- return Boolean((await live?.getCapabilities())?.editor.projectCatalogRead);
373
+ return live ? await live.readLiveState() : undefined;
236
374
  }
237
375
  catch {
238
- return false;
376
+ return undefined;
377
+ }
378
+ }
379
+ async function optionalIdentity(live) {
380
+ try {
381
+ return live ? await live.getIdentity() : undefined;
382
+ }
383
+ catch {
384
+ return undefined;
239
385
  }
240
386
  }
241
387
  async function optionalProjectSelectionCapability(live) {