@morshoto/framekit 0.1.0

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 (31) hide show
  1. package/README.md +67 -0
  2. package/bin/framekit.mjs +26 -0
  3. package/dist-package/adapters/final-cut/typescript/src/analyzers.js +116 -0
  4. package/dist-package/adapters/final-cut/typescript/src/assets.js +112 -0
  5. package/dist-package/adapters/final-cut/typescript/src/connection.js +379 -0
  6. package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +282 -0
  7. package/dist-package/adapters/final-cut/typescript/src/export.js +382 -0
  8. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +503 -0
  9. package/dist-package/adapters/final-cut/typescript/src/index.js +11 -0
  10. package/dist-package/adapters/final-cut/typescript/src/live.js +415 -0
  11. package/dist-package/adapters/final-cut/typescript/src/native-operation.js +18 -0
  12. package/dist-package/adapters/final-cut/typescript/src/native.js +3134 -0
  13. package/dist-package/adapters/final-cut/typescript/src/publisher.js +102 -0
  14. package/dist-package/adapters/final-cut/typescript/src/session.js +171 -0
  15. package/dist-package/apps/cli/src/main.js +130 -0
  16. package/dist-package/apps/mcp-server/src/main.js +146 -0
  17. package/dist-package/apps/mcp-server/src/server.js +617 -0
  18. package/dist-package/packages/runtime/src/capabilities.js +24 -0
  19. package/dist-package/packages/runtime/src/context/context-engine.js +142 -0
  20. package/dist-package/packages/runtime/src/diff/diff.js +145 -0
  21. package/dist-package/packages/runtime/src/domain/types.js +1 -0
  22. package/dist-package/packages/runtime/src/editing/intent.js +83 -0
  23. package/dist-package/packages/runtime/src/index.js +8 -0
  24. package/dist-package/packages/runtime/src/runtime.js +890 -0
  25. package/dist-package/packages/runtime/src/snapshot-digest.js +24 -0
  26. package/dist-package/packages/runtime/src/speech/filler-removal.js +87 -0
  27. package/dist-package/packages/runtime/src/verification/verification.js +113 -0
  28. package/dist-package/packages/testkit/src/fixture-analyzers.js +39 -0
  29. package/dist-package/packages/testkit/src/in-memory-editor.js +520 -0
  30. package/dist-package/packages/testkit/src/index.js +2 -0
  31. package/package.json +64 -0
@@ -0,0 +1,890 @@
1
+ import { randomUUID } from "node:crypto";
2
+ import { ContextEngine } from "./context/context-engine.js";
3
+ import { diffSnapshots } from "./diff/diff.js";
4
+ import { DefaultVerificationEngine } from "./verification/verification.js";
5
+ import { withCanonicalTimelineMode } from "./capabilities.js";
6
+ import { canonicalSnapshotDigest } from "./snapshot-digest.js";
7
+ import { planFillerRemoval, } from "./speech/filler-removal.js";
8
+ export class AgentVideoRuntime {
9
+ adapter;
10
+ options;
11
+ transactions = new Map();
12
+ editPreviews = new Map();
13
+ fillerPreviews = new Map();
14
+ verificationEngine;
15
+ context;
16
+ constructor(adapter, options = {}) {
17
+ this.adapter = adapter;
18
+ this.options = options;
19
+ this.context = new ContextEngine(adapter);
20
+ this.verificationEngine = options.verificationEngine ?? new DefaultVerificationEngine();
21
+ }
22
+ async inspectProject() {
23
+ return this.context.inspectProject();
24
+ }
25
+ async inspectTimeline() {
26
+ const project = await this.inspectProject();
27
+ return project.timeline;
28
+ }
29
+ async captureFrame(position, options = {}) {
30
+ const exactPosition = parseRational(position, "INVALID_TIMELINE_POSITION");
31
+ const capabilities = await this.adapter.getCapabilities();
32
+ if (!capabilities.editor.frameCapture || !this.adapter.captureFrame) {
33
+ throw new Error("CAPABILITY_UNAVAILABLE: timeline frame capture");
34
+ }
35
+ if (options.analyze && !this.options.visualAnalyzer) {
36
+ throw new Error("CAPABILITY_UNAVAILABLE: visual analysis");
37
+ }
38
+ const project = await this.inspectProject();
39
+ const source = await this.adapter.captureFrame(position, project.revision);
40
+ const clip = project.timeline.clips
41
+ .filter((candidate) => isWithinClip(exactPosition, candidate.startTime, candidate.durationTime))
42
+ .sort((left, right) => right.track - left.track)[0];
43
+ let analysis;
44
+ if (options.analyze) {
45
+ const media = clip?.mediaId
46
+ ? project.media.find((candidate) => candidate.mediaId === clip.mediaId)
47
+ : undefined;
48
+ if (!clip || !media) {
49
+ throw new Error("CAPABILITY_UNAVAILABLE: visual analysis requires media at the captured position");
50
+ }
51
+ const mediaTime = rationalDifferenceSeconds(exactPosition, parseRational(clip.startTime, "INVALID_PROJECT_STATE"));
52
+ analysis = await this.options.visualAnalyzer.analyze({ project, media }, { start: mediaTime, end: mediaTime });
53
+ }
54
+ return {
55
+ image: structuredClone(source.image),
56
+ position: { ...position },
57
+ timecode: source.timecode,
58
+ project: { id: project.projectId, name: project.projectName },
59
+ sequence: { id: project.timeline.id, name: project.timeline.name },
60
+ ...(clip ? {
61
+ clip: {
62
+ id: clip.id,
63
+ ...(clip.mediaId ? { mediaId: clip.mediaId } : {}),
64
+ name: clip.name,
65
+ startTime: { ...clip.startTime },
66
+ durationTime: { ...clip.durationTime },
67
+ track: clip.track,
68
+ },
69
+ } : {}),
70
+ ...(analysis ? { analysis } : {}),
71
+ };
72
+ }
73
+ async listProjects() {
74
+ const capabilities = await this.adapter.getCapabilities();
75
+ if (!capabilities.editor.projectCatalogRead || !this.adapter.listProjects) {
76
+ throw new Error("CAPABILITY_UNAVAILABLE: editor project catalog");
77
+ }
78
+ return this.adapter.listProjects();
79
+ }
80
+ async selectProject(selection) {
81
+ const capabilities = await this.adapter.getCapabilities();
82
+ if (!capabilities.editor.projectSelection || !this.adapter.selectProject) {
83
+ throw new Error("CAPABILITY_UNAVAILABLE: editor project selection");
84
+ }
85
+ if (!selection.projectId.trim())
86
+ throw new Error("INVALID_PROJECT_SELECTION: projectId is required");
87
+ if (selection.sequenceId !== undefined && !selection.sequenceId.trim()) {
88
+ throw new Error("INVALID_PROJECT_SELECTION: sequenceId cannot be empty");
89
+ }
90
+ return this.adapter.selectProject(selection);
91
+ }
92
+ async inspectEditor() {
93
+ const capabilities = withCanonicalTimelineMode(await this.adapter.getCapabilities());
94
+ return {
95
+ identity: await this.adapter.getIdentity(),
96
+ capabilities: {
97
+ ...capabilities,
98
+ analyzers: {
99
+ ...capabilities.analyzers,
100
+ speechTranscribe: capabilities.analyzers.speechTranscribe || Boolean(this.options.speechAnalyzer),
101
+ audioLoudness: capabilities.analyzers.audioLoudness || Boolean(this.options.audioAnalyzer),
102
+ visualTrack: capabilities.analyzers.visualTrack || Boolean(this.options.visualAnalyzer),
103
+ },
104
+ },
105
+ };
106
+ }
107
+ async inspectContext() {
108
+ const editor = await this.inspectEditor();
109
+ return this.context.inspectContext(editor.capabilities);
110
+ }
111
+ async inspectLiveEditor() {
112
+ const liveAdapter = this.liveAdapter();
113
+ return liveAdapter.readLiveState();
114
+ }
115
+ async liveChangesSince(revision, waitMs = 0) {
116
+ const liveAdapter = this.liveAdapter();
117
+ return liveAdapter.liveChangesSince(revision, waitMs);
118
+ }
119
+ async edit(operation, policy = {}) {
120
+ const before = await this.inspectProject();
121
+ if (operation.baseRevision && !sameRevision(operation.baseRevision, before.revision)) {
122
+ throw new Error("STALE_CONTEXT: operation base revision does not match current editor state");
123
+ }
124
+ const capabilities = await this.adapter.getCapabilities();
125
+ if (!capabilities.editor.timelineWrite && !capabilities.editor.timelineArtifactWrite) {
126
+ throw new Error("CAPABILITY_UNAVAILABLE: editor timeline mutation");
127
+ }
128
+ if (!capabilities.editor.timelineSnapshotRead
129
+ || !capabilities.editor.readAfterWrite
130
+ || !capabilities.editor.rollback) {
131
+ throw new Error("CAPABILITY_UNAVAILABLE: editor timeline mutation requires snapshot, read-after-write, and rollback");
132
+ }
133
+ const appliedRevision = await this.adapter.apply(operation, before.revision);
134
+ let attemptedAfter;
135
+ try {
136
+ attemptedAfter = await this.inspectProject();
137
+ }
138
+ catch (readError) {
139
+ try {
140
+ await this.adapter.restore(before, appliedRevision);
141
+ this.assertRestored(before, await this.inspectProject());
142
+ }
143
+ catch (rollbackError) {
144
+ throw new Error(`READ_AFTER_WRITE_FAILED: compensating rollback failed (${String(readError)}; ${String(rollbackError)})`);
145
+ }
146
+ throw new Error(`READ_AFTER_WRITE_FAILED: canonical state was restored (${String(readError)})`);
147
+ }
148
+ const diff = diffSnapshots(before, attemptedAfter);
149
+ const transaction = {
150
+ id: `txn-${randomUUID()}`,
151
+ operation,
152
+ intent: operation.type,
153
+ planned: [operation],
154
+ applied: [operation],
155
+ baseRevision: before.revision,
156
+ before,
157
+ after: attemptedAfter,
158
+ attemptedAfter,
159
+ diff,
160
+ status: "APPLIED",
161
+ };
162
+ try {
163
+ transaction.attemptedAfter = await this.reanalyzeAffectedRanges(transaction);
164
+ transaction.after = transaction.attemptedAfter;
165
+ }
166
+ catch (error) {
167
+ await this.adapter.restore(before, attemptedAfter.revision);
168
+ this.assertRestored(before, await this.inspectProject());
169
+ throw new Error(`ANALYSIS_FAILED: post-write verification analysis failed (${String(error)})`);
170
+ }
171
+ try {
172
+ transaction.verification = await this.verificationEngine.verify(transaction, policy);
173
+ }
174
+ catch (verificationError) {
175
+ try {
176
+ await this.adapter.restore(before, attemptedAfter.revision);
177
+ this.assertRestored(before, await this.inspectProject());
178
+ }
179
+ catch (rollbackError) {
180
+ throw new Error(`VERIFICATION_FAILED: compensating rollback failed (${String(verificationError)}; ${String(rollbackError)})`);
181
+ }
182
+ throw new Error(`VERIFICATION_FAILED: canonical state was restored (${String(verificationError)})`);
183
+ }
184
+ if (transaction.verification.passed) {
185
+ transaction.status = "VERIFIED";
186
+ }
187
+ else {
188
+ await this.adapter.restore(before, attemptedAfter.revision);
189
+ transaction.after = await this.inspectProject();
190
+ this.assertRestored(before, transaction.after);
191
+ transaction.status = "ROLLED_BACK";
192
+ }
193
+ this.transactions.set(transaction.id, transaction);
194
+ return transaction;
195
+ }
196
+ async previewEdit(request) {
197
+ const before = await this.inspectProject();
198
+ if (!sameRevision(request.baseRevision, before.revision)) {
199
+ throw new Error("STALE_CONTEXT: preview base revision does not match current editor state");
200
+ }
201
+ if (request.operations.length === 0)
202
+ throw new Error("INVALID_OPERATION: composite edit requires operations");
203
+ await this.assertCompositeCapabilities(request.operations);
204
+ if (!this.adapter.previewTransaction) {
205
+ throw new Error("CAPABILITY_UNAVAILABLE: editor composite transaction preview");
206
+ }
207
+ const expectedAfter = await this.adapter.previewTransaction(request.operations, before.revision);
208
+ const previewToken = `preview-${randomUUID()}`;
209
+ const preview = {
210
+ previewToken,
211
+ baseRevision: structuredClone(before.revision),
212
+ operations: structuredClone(request.operations),
213
+ expectedDiff: diffSnapshots(before, expectedAfter),
214
+ warnings: [],
215
+ expiresAt: new Date(this.now() + (this.options.previewTtlMs ?? 30_000)).toISOString(),
216
+ };
217
+ this.pruneEditPreviews();
218
+ const maxActivePreviews = Number.isInteger(this.options.maxActivePreviews)
219
+ && this.options.maxActivePreviews > 0
220
+ ? this.options.maxActivePreviews
221
+ : 128;
222
+ while (this.editPreviews.size >= maxActivePreviews) {
223
+ const oldestToken = this.editPreviews.keys().next().value;
224
+ if (oldestToken === undefined)
225
+ break;
226
+ this.editPreviews.delete(oldestToken);
227
+ }
228
+ this.editPreviews.set(previewToken, preview);
229
+ return structuredClone(preview);
230
+ }
231
+ async executeEdit(previewToken, policy = {}) {
232
+ const preview = this.editPreviews.get(previewToken);
233
+ if (!preview)
234
+ throw new Error(`PREVIEW_TOKEN_INVALID: unknown or already used preview ${previewToken}`);
235
+ this.editPreviews.delete(previewToken);
236
+ if (this.now() > Date.parse(preview.expiresAt)) {
237
+ throw new Error("PREVIEW_TOKEN_EXPIRED: composite edit preview has expired");
238
+ }
239
+ const before = await this.inspectProject();
240
+ if (!sameRevision(preview.baseRevision, before.revision)) {
241
+ throw new Error("STALE_CONTEXT: preview base revision does not match current editor state");
242
+ }
243
+ await this.assertCompositeCapabilities(preview.operations);
244
+ if (!this.adapter.applyTransaction) {
245
+ throw new Error("CAPABILITY_UNAVAILABLE: editor composite transaction execution");
246
+ }
247
+ try {
248
+ await this.adapter.applyTransaction(preview.operations, before.revision);
249
+ }
250
+ catch (error) {
251
+ const partiallyApplied = await this.inspectProject();
252
+ if (!sameRevision(partiallyApplied.revision, before.revision)) {
253
+ try {
254
+ await this.adapter.restore(before, partiallyApplied.revision);
255
+ }
256
+ catch (rollbackError) {
257
+ throw new Error(`TRANSACTION_FAILED: ${String(error)}; rollback failed: ${String(rollbackError)}`);
258
+ }
259
+ }
260
+ throw new Error(`TRANSACTION_FAILED: ${String(error)}; transaction was rolled back`);
261
+ }
262
+ const attemptedAfter = await this.inspectProject();
263
+ const transaction = {
264
+ id: `txn-${randomUUID()}`,
265
+ intent: "composite-edit",
266
+ planned: structuredClone(preview.operations),
267
+ applied: structuredClone(preview.operations),
268
+ baseRevision: before.revision,
269
+ before,
270
+ after: attemptedAfter,
271
+ attemptedAfter,
272
+ diff: diffSnapshots(before, attemptedAfter),
273
+ status: "APPLIED",
274
+ };
275
+ try {
276
+ transaction.attemptedAfter = await this.reanalyzeAffectedRanges(transaction);
277
+ transaction.after = transaction.attemptedAfter;
278
+ }
279
+ catch (error) {
280
+ await this.adapter.restore(before, attemptedAfter.revision);
281
+ throw new Error(`ANALYSIS_FAILED: post-write verification analysis failed (${String(error)})`);
282
+ }
283
+ transaction.verification = await this.verificationEngine.verify(transaction, policy);
284
+ if (transaction.verification.passed) {
285
+ transaction.status = "VERIFIED";
286
+ }
287
+ else {
288
+ await this.adapter.restore(before, attemptedAfter.revision);
289
+ transaction.after = await this.inspectProject();
290
+ transaction.status = "ROLLED_BACK";
291
+ }
292
+ this.transactions.set(transaction.id, transaction);
293
+ return transaction;
294
+ }
295
+ async previewMusic(request) {
296
+ if (request.ducking?.enabled) {
297
+ throw new Error("CAPABILITY_UNAVAILABLE: dialogue ducking");
298
+ }
299
+ const before = await this.inspectProject();
300
+ const operations = [];
301
+ const hasMediaId = request.mediaId !== undefined;
302
+ const hasImport = request.import !== undefined;
303
+ if (hasMediaId === hasImport) {
304
+ throw new Error("INVALID_OPERATION: music requires exactly one mediaId or import source");
305
+ }
306
+ if (!Number.isInteger(request.targetLane) || request.targetLane === 0) {
307
+ throw new Error("INVALID_OPERATION: music requires a non-primary target lane");
308
+ }
309
+ if (request.placement === "append" && request.start !== undefined) {
310
+ throw new Error("INVALID_OPERATION: appended music cannot specify a start position");
311
+ }
312
+ const mediaId = request.import?.mediaId ?? request.mediaId;
313
+ if (request.import) {
314
+ operations.push({
315
+ type: "media.import",
316
+ mediaId: request.import.mediaId,
317
+ source: request.import.source,
318
+ mediaKind: "audio",
319
+ duration: request.import.duration,
320
+ sourceDigest: request.import.sourceDigest,
321
+ });
322
+ }
323
+ const media = before.media.find((candidate) => candidate.mediaId === mediaId);
324
+ const duration = request.duration ?? request.import?.duration ?? media?.duration;
325
+ const sourceDuration = request.import?.duration ?? media?.duration;
326
+ if (duration === undefined) {
327
+ throw new Error("INVALID_OPERATION: music duration is required when media duration is unavailable");
328
+ }
329
+ if (!Number.isFinite(duration) || duration <= 0) {
330
+ throw new Error("INVALID_OPERATION: music duration must be positive");
331
+ }
332
+ if (sourceDuration !== undefined && duration > sourceDuration) {
333
+ throw new Error("INVALID_OPERATION: music duration exceeds the source duration");
334
+ }
335
+ const start = request.placement === "append" ? before.timeline.duration : request.start;
336
+ if (start === undefined || !Number.isFinite(start) || start < 0) {
337
+ throw new Error("INVALID_OPERATION: inserted music requires a non-negative start position");
338
+ }
339
+ operations.push({
340
+ type: "timeline.media.add",
341
+ occurrenceId: request.occurrenceId,
342
+ mediaId,
343
+ role: "music",
344
+ start,
345
+ duration,
346
+ targetLane: request.targetLane,
347
+ });
348
+ if (request.gainDb !== undefined) {
349
+ if (!Number.isFinite(request.gainDb))
350
+ throw new Error("INVALID_OPERATION: music gain must be finite");
351
+ operations.push({ type: "set-gain", clipId: request.occurrenceId, gainDb: request.gainDb });
352
+ }
353
+ if (request.fadeIn !== undefined || request.fadeOut !== undefined) {
354
+ const fadeIn = request.fadeIn ?? 0;
355
+ const fadeOut = request.fadeOut ?? 0;
356
+ if (!Number.isFinite(fadeIn) || !Number.isFinite(fadeOut) || fadeIn < 0 || fadeOut < 0 || fadeIn + fadeOut > duration) {
357
+ throw new Error("INVALID_OPERATION: music fades must be non-negative and fit within the music duration");
358
+ }
359
+ operations.push({
360
+ type: "timeline.audio.fades",
361
+ clipId: request.occurrenceId,
362
+ fadeIn,
363
+ fadeOut,
364
+ });
365
+ }
366
+ return this.previewEdit({ baseRevision: request.baseRevision, operations });
367
+ }
368
+ async previewFillerRemoval(request) {
369
+ const before = await this.inspectProject();
370
+ if (!sameRevision(request.baseRevision, before.revision)) {
371
+ throw new Error("STALE_CONTEXT: filler preview base revision does not match current editor state");
372
+ }
373
+ await this.assertFillerCapabilities();
374
+ const selectedRange = validateFillerSelection(request.range);
375
+ const candidates = [];
376
+ const expectedWordsByClip = new Map();
377
+ const selectedClips = before.timeline.clips.filter((clip) => clip.mediaId && rangesOverlap(clip.start, clip.start + clip.duration, selectedRange.start, selectedRange.end));
378
+ const selectedMediaIds = new Set();
379
+ for (const clip of selectedClips) {
380
+ if (clip.mediaId && selectedMediaIds.has(clip.mediaId)) {
381
+ throw new Error("CAPABILITY_UNAVAILABLE: filler removal cannot verify repeated timeline occurrences of the same media item");
382
+ }
383
+ if (clip.mediaId)
384
+ selectedMediaIds.add(clip.mediaId);
385
+ }
386
+ for (const clip of selectedClips) {
387
+ if (!clip.mediaId)
388
+ continue;
389
+ const media = before.media.find((candidate) => candidate.mediaId === clip.mediaId);
390
+ if (!media)
391
+ throw new Error(`MEDIA_NOT_FOUND: ${clip.mediaId}`);
392
+ const localRange = {
393
+ start: Math.max(0, selectedRange.start - clip.start),
394
+ end: Math.min(clip.duration, selectedRange.end - clip.start),
395
+ };
396
+ if (localRange.end <= localRange.start)
397
+ continue;
398
+ const speech = await this.options.speechAnalyzer.analyze({ project: before, media }, localRange);
399
+ expectedWordsByClip.set(clip.id, structuredClone(speech.words));
400
+ for (const candidate of planFillerRemoval(speech.words, localRange, request)) {
401
+ candidates.push({
402
+ ...candidate,
403
+ clipId: clip.id,
404
+ mediaId: clip.mediaId,
405
+ sourceRange: structuredClone(candidate.range),
406
+ range: translateClipRange(clip.startTime, clip.start, candidate.range),
407
+ });
408
+ }
409
+ }
410
+ if (candidates.length === 0) {
411
+ throw new Error("NO_FILLERS_FOUND: no high-confidence filler words in selected range");
412
+ }
413
+ candidates.sort((left, right) => right.range.start - left.range.start);
414
+ const operations = candidates.map((candidate) => ({
415
+ type: "ripple-delete",
416
+ timelineId: before.timeline.id,
417
+ range: structuredClone(candidate.range),
418
+ reason: `remove high-confidence filler word: ${candidate.word.text}`,
419
+ }));
420
+ const previewToken = `filler-preview-${randomUUID()}`;
421
+ const expiresAt = new Date(this.now() + (this.options.previewTtlMs ?? 30_000)).toISOString();
422
+ const expectedDiff = this.adapter.previewTransaction
423
+ ? diffSnapshots(before, await this.adapter.previewTransaction(operations, before.revision))
424
+ : undefined;
425
+ const preview = {
426
+ previewToken,
427
+ baseRevision: structuredClone(before.revision),
428
+ range: structuredClone(selectedRange),
429
+ candidates: structuredClone(candidates),
430
+ operations: structuredClone(operations),
431
+ ...(expectedDiff ? { expectedDiff } : {}),
432
+ warnings: expectedDiff ? [] : ["The selected canonical editor has no non-mutating preview provider; the diff will be observed after execution."],
433
+ expiresAt,
434
+ };
435
+ this.pruneFillerPreviews();
436
+ const maxActivePreviews = Number.isInteger(this.options.maxActivePreviews)
437
+ && this.options.maxActivePreviews > 0
438
+ ? this.options.maxActivePreviews
439
+ : 128;
440
+ while (this.fillerPreviews.size >= maxActivePreviews) {
441
+ const oldestToken = this.fillerPreviews.keys().next().value;
442
+ if (oldestToken === undefined)
443
+ break;
444
+ this.fillerPreviews.delete(oldestToken);
445
+ }
446
+ this.fillerPreviews.set(previewToken, {
447
+ preview,
448
+ expectedWordsByClip,
449
+ });
450
+ return structuredClone(preview);
451
+ }
452
+ async executeFillerRemoval(previewToken) {
453
+ const record = this.fillerPreviews.get(previewToken);
454
+ if (!record)
455
+ throw new Error(`PREVIEW_TOKEN_INVALID: unknown or already used filler preview ${previewToken}`);
456
+ this.fillerPreviews.delete(previewToken);
457
+ if (this.now() > Date.parse(record.preview.expiresAt)) {
458
+ throw new Error("PREVIEW_TOKEN_EXPIRED: filler removal preview has expired");
459
+ }
460
+ const before = await this.inspectProject();
461
+ if (!sameRevision(record.preview.baseRevision, before.revision)) {
462
+ throw new Error("STALE_CONTEXT: filler preview base revision does not match current editor state");
463
+ }
464
+ await this.assertFillerCapabilities();
465
+ let current = before;
466
+ let currentRevision = before.revision;
467
+ try {
468
+ for (const operation of record.preview.operations) {
469
+ currentRevision = await this.adapter.apply(operation, currentRevision);
470
+ current = await this.inspectProject();
471
+ if (!sameRevision(current.revision, currentRevision)) {
472
+ throw new Error("READ_AFTER_WRITE_FAILED: editor returned an unexpected filler-removal revision");
473
+ }
474
+ }
475
+ const transaction = {
476
+ id: `txn-${randomUUID()}`,
477
+ intent: "remove-filler-words",
478
+ planned: structuredClone(record.preview.operations),
479
+ applied: structuredClone(record.preview.operations),
480
+ baseRevision: before.revision,
481
+ before,
482
+ after: current,
483
+ attemptedAfter: current,
484
+ diff: diffSnapshots(before, current),
485
+ status: "APPLIED",
486
+ };
487
+ transaction.attemptedAfter = await this.reanalyzeFillerTargets(transaction, record);
488
+ transaction.after = transaction.attemptedAfter;
489
+ const structuralVerification = await this.verificationEngine.verify(transaction, { requireExpectedChange: true });
490
+ const continuity = verifyFillerSpeechContinuity(transaction, record);
491
+ transaction.verification = {
492
+ passed: structuralVerification.passed && continuity.passed,
493
+ checks: [...structuralVerification.checks, continuity],
494
+ };
495
+ if (transaction.verification.passed) {
496
+ transaction.status = "VERIFIED";
497
+ }
498
+ else {
499
+ await this.adapter.restore(before, current.revision);
500
+ transaction.after = await this.inspectProject();
501
+ this.assertRestored(before, transaction.after);
502
+ transaction.status = "ROLLED_BACK";
503
+ }
504
+ this.transactions.set(transaction.id, transaction);
505
+ return transaction;
506
+ }
507
+ catch (error) {
508
+ let partiallyApplied;
509
+ try {
510
+ partiallyApplied = await this.inspectProject();
511
+ }
512
+ catch (readError) {
513
+ throw new Error(`FILLER_REMOVAL_FAILED: ${String(error)}; rollback failed: ${String(readError)}`);
514
+ }
515
+ if (!sameRevision(partiallyApplied.revision, before.revision)) {
516
+ try {
517
+ await this.adapter.restore(before, partiallyApplied.revision);
518
+ this.assertRestored(before, await this.inspectProject());
519
+ }
520
+ catch (rollbackError) {
521
+ throw new Error(`FILLER_REMOVAL_FAILED: ${String(error)}; rollback failed: ${String(rollbackError)}`);
522
+ }
523
+ }
524
+ throw new Error(`FILLER_REMOVAL_FAILED: ${String(error)}`);
525
+ }
526
+ }
527
+ async changesSince(revision) {
528
+ return this.context.changesSince(revision);
529
+ }
530
+ async contextChangesSince(revision, waitMs = 0) {
531
+ return this.context.contextChangesSince(revision, waitMs);
532
+ }
533
+ async analyzeSpeech(mediaId) {
534
+ if (!this.options.speechAnalyzer)
535
+ throw new Error("CAPABILITY_UNAVAILABLE: speech analysis");
536
+ const project = await this.inspectProject();
537
+ const media = project.media.find((candidate) => candidate.mediaId === mediaId);
538
+ if (!media)
539
+ throw new Error(`MEDIA_NOT_FOUND: ${mediaId}`);
540
+ return this.options.speechAnalyzer.analyze({ project, media });
541
+ }
542
+ async analyzeAudio(mediaId) {
543
+ if (!this.options.audioAnalyzer)
544
+ throw new Error("CAPABILITY_UNAVAILABLE: audio analysis");
545
+ const project = await this.inspectProject();
546
+ const media = project.media.find((candidate) => candidate.mediaId === mediaId);
547
+ if (!media)
548
+ throw new Error(`MEDIA_NOT_FOUND: ${mediaId}`);
549
+ return this.options.audioAnalyzer.analyze({ project, media });
550
+ }
551
+ async analyzeVisual(mediaId, range) {
552
+ if (!this.options.visualAnalyzer)
553
+ throw new Error("CAPABILITY_UNAVAILABLE: visual analysis");
554
+ const project = await this.inspectProject();
555
+ const media = project.media.find((candidate) => candidate.mediaId === mediaId);
556
+ if (!media)
557
+ throw new Error(`MEDIA_NOT_FOUND: ${mediaId}`);
558
+ return this.options.visualAnalyzer.analyze({ project, media }, range);
559
+ }
560
+ async understandMedia(mediaId) {
561
+ const project = await this.inspectProject();
562
+ const media = project.media.find((candidate) => candidate.mediaId === mediaId);
563
+ if (!media)
564
+ throw new Error(`MEDIA_NOT_FOUND: ${mediaId}`);
565
+ const input = { project, media };
566
+ const [speech, audio, visual] = await Promise.all([
567
+ this.options.speechAnalyzer?.analyze(input),
568
+ this.options.audioAnalyzer?.analyze(input),
569
+ this.options.visualAnalyzer?.analyze(input),
570
+ ]);
571
+ if (!speech && !audio && !visual) {
572
+ throw new Error("CAPABILITY_UNAVAILABLE: media understanding");
573
+ }
574
+ const understanding = {
575
+ mediaId: media.mediaId,
576
+ source: media.source,
577
+ ...(speech ? { speech } : {}),
578
+ ...(audio ? { audio } : {}),
579
+ ...(visual ? { visual } : {}),
580
+ analysisRevision: project.revision,
581
+ };
582
+ this.context.attachMediaUnderstanding(understanding);
583
+ return structuredClone(understanding);
584
+ }
585
+ async inspectMedia(mediaId) {
586
+ const project = await this.inspectProject();
587
+ const media = project.media.find((candidate) => candidate.mediaId === mediaId);
588
+ if (!media)
589
+ throw new Error(`MEDIA_NOT_FOUND: ${mediaId}`);
590
+ return media;
591
+ }
592
+ async searchMedia(query) {
593
+ const project = await this.inspectProject();
594
+ const normalized = query.trim().toLowerCase();
595
+ return project.media.filter((media) => media.mediaId.toLowerCase().includes(normalized) || media.source.toLowerCase().includes(normalized));
596
+ }
597
+ async listAssets(query) {
598
+ const capabilities = await this.adapter.getCapabilities();
599
+ if (!capabilities.editor.assetDiscovery || !this.adapter.listAssets) {
600
+ throw new Error("CAPABILITY_UNAVAILABLE: editor assets");
601
+ }
602
+ const assets = await this.context.listAssets(query);
603
+ return assets.filter((asset) => matchesAssetQuery(asset, query));
604
+ }
605
+ getDiff(transactionId) {
606
+ const transaction = this.getTransaction(transactionId);
607
+ return transaction.diff;
608
+ }
609
+ getTransaction(transactionId) {
610
+ const transaction = this.transactions.get(transactionId);
611
+ if (!transaction) {
612
+ throw new Error(`TRANSACTION_NOT_FOUND: ${transactionId}`);
613
+ }
614
+ return transaction;
615
+ }
616
+ async verifyTransaction(transactionId) {
617
+ return this.getTransaction(transactionId).verification;
618
+ }
619
+ async undo(transactionId) {
620
+ const transaction = this.getTransaction(transactionId);
621
+ const current = await this.inspectProject();
622
+ if (current.projectId !== transaction.before.projectId
623
+ || current.timeline.id !== transaction.before.timeline.id) {
624
+ throw new Error(`TARGET_MISMATCH: cannot undo ${transaction.before.projectId}/${transaction.before.timeline.id} while ${current.projectId}/${current.timeline.id} is active`);
625
+ }
626
+ await this.adapter.restore(transaction.before, current.revision);
627
+ const restored = await this.inspectProject();
628
+ this.assertRestored(transaction.before, restored);
629
+ return restored;
630
+ }
631
+ assertRestored(expected, actual) {
632
+ if (canonicalSnapshotDigest(expected) !== canonicalSnapshotDigest(actual)) {
633
+ throw new Error("ROLLBACK_FAILED: restored canonical digest does not match pre-edit state");
634
+ }
635
+ }
636
+ liveAdapter() {
637
+ const candidate = this.adapter;
638
+ if (typeof candidate.readLiveState !== "function" || typeof candidate.liveChangesSince !== "function") {
639
+ throw new Error("CAPABILITY_UNAVAILABLE: live Final Cut editor state");
640
+ }
641
+ return candidate;
642
+ }
643
+ async assertCompositeCapabilities(operations) {
644
+ const capabilities = (await this.adapter.getCapabilities()).editor;
645
+ if (!capabilities.compositeTransactions || !capabilities.readAfterWrite || !capabilities.rollback) {
646
+ throw new Error("CAPABILITY_UNAVAILABLE: editor composite transactions");
647
+ }
648
+ if (operations.some((operation) => operation.type === "media.import") && !capabilities.mediaImport) {
649
+ throw new Error("CAPABILITY_UNAVAILABLE: media import");
650
+ }
651
+ if (operations.some((operation) => operation.type === "timeline.media.add") && !capabilities.mediaPlacement) {
652
+ throw new Error("CAPABILITY_UNAVAILABLE: timeline media placement");
653
+ }
654
+ if (operations.some((operation) => operation.type === "timeline.title.add")
655
+ && (!capabilities.titlePlacement || !capabilities.assetDiscovery)) {
656
+ throw new Error("CAPABILITY_UNAVAILABLE: timeline title placement");
657
+ }
658
+ if (operations.some((operation) => operation.type !== "media.import")
659
+ && !capabilities.timelineWrite && !capabilities.timelineArtifactWrite) {
660
+ throw new Error("CAPABILITY_UNAVAILABLE: editor timeline mutation");
661
+ }
662
+ }
663
+ async assertFillerCapabilities() {
664
+ if (!this.options.speechAnalyzer)
665
+ throw new Error("CAPABILITY_UNAVAILABLE: speech analysis");
666
+ const capabilities = (await this.adapter.getCapabilities()).editor;
667
+ if (!capabilities.timelineSnapshotRead || !capabilities.timelineWrite
668
+ || !capabilities.readAfterWrite || !capabilities.rollback) {
669
+ throw new Error("CAPABILITY_UNAVAILABLE: filler removal requires canonical timeline write, read-after-write, and rollback");
670
+ }
671
+ }
672
+ now() {
673
+ return this.options.now?.() ?? Date.now();
674
+ }
675
+ pruneEditPreviews() {
676
+ const now = this.now();
677
+ for (const [previewToken, preview] of this.editPreviews) {
678
+ if (now > Date.parse(preview.expiresAt))
679
+ this.editPreviews.delete(previewToken);
680
+ }
681
+ }
682
+ pruneFillerPreviews() {
683
+ const now = this.now();
684
+ for (const [previewToken, record] of this.fillerPreviews) {
685
+ if (now > Date.parse(record.preview.expiresAt))
686
+ this.fillerPreviews.delete(previewToken);
687
+ }
688
+ }
689
+ async reanalyzeAffectedRanges(transaction) {
690
+ const mediaIds = new Set(transaction.diff.affectedRanges.flatMap((range) => transaction.attemptedAfter.timeline.clips
691
+ .filter((clip) => clip.start < range.end && clip.start + clip.duration > range.start)
692
+ .flatMap((clip) => clip.mediaId ? [clip.mediaId] : [])));
693
+ if (mediaIds.size === 0)
694
+ return transaction.attemptedAfter;
695
+ const next = structuredClone(transaction.attemptedAfter);
696
+ for (const mediaId of mediaIds) {
697
+ const media = next.media.find((candidate) => candidate.mediaId === mediaId);
698
+ if (!media)
699
+ continue;
700
+ const ranges = transaction.diff.affectedRanges.filter((range) => next.timeline.clips.some((clip) => clip.mediaId === mediaId && clip.start < range.end && clip.start + clip.duration > range.start));
701
+ const input = { project: next, media };
702
+ if (this.options.speechAnalyzer) {
703
+ const analyses = await Promise.all(ranges.map((range) => this.options.speechAnalyzer.analyze(input, range)));
704
+ media.speech = { words: analyses.flatMap((analysis) => analysis.words) };
705
+ }
706
+ if (this.options.audioAnalyzer) {
707
+ const analyses = await Promise.all(ranges.map((range) => this.options.audioAnalyzer.analyze(input, range)));
708
+ if (analyses[analyses.length - 1])
709
+ media.audio = analyses[analyses.length - 1];
710
+ }
711
+ if (this.options.visualAnalyzer) {
712
+ const analyses = await Promise.all(ranges.map((range) => this.options.visualAnalyzer.analyze(input, range)));
713
+ media.visual = {
714
+ scenes: analyses.flatMap((analysis) => analysis.scenes),
715
+ subjects: analyses.flatMap((analysis) => analysis.subjects),
716
+ keyframes: analyses.flatMap((analysis) => analysis.keyframes),
717
+ motion: analyses[analyses.length - 1]?.motion,
718
+ };
719
+ }
720
+ if (this.options.speechAnalyzer || this.options.audioAnalyzer || this.options.visualAnalyzer) {
721
+ for (const candidate of next.media) {
722
+ if (candidate.mediaId === mediaId)
723
+ candidate.analysisRevision = next.revision.id;
724
+ }
725
+ }
726
+ }
727
+ return next;
728
+ }
729
+ async reanalyzeFillerTargets(transaction, record) {
730
+ const next = structuredClone(transaction.attemptedAfter);
731
+ const targets = new Map(record.preview.candidates.map((candidate) => [candidate.clipId, candidate]));
732
+ for (const clipId of targets.keys()) {
733
+ const beforeClip = transaction.before.timeline.clips.find((clip) => clip.id === clipId);
734
+ const afterClip = next.timeline.clips.find((clip) => clip.id === clipId);
735
+ if (!beforeClip || !afterClip || !beforeClip.mediaId) {
736
+ throw new Error(`ANALYSIS_FAILED: filler target clip ${clipId} disappeared after the edit`);
737
+ }
738
+ const media = next.media.find((candidate) => candidate.mediaId === beforeClip.mediaId);
739
+ if (!media)
740
+ throw new Error(`MEDIA_NOT_FOUND: ${beforeClip.mediaId}`);
741
+ const speech = await this.options.speechAnalyzer.analyze({ project: next, media }, { start: 0, end: afterClip.duration });
742
+ media.speech = speech;
743
+ media.analysisRevision = next.revision.id;
744
+ }
745
+ return next;
746
+ }
747
+ }
748
+ function validateFillerSelection(range) {
749
+ if (!Number.isFinite(range.start) || !Number.isFinite(range.end)
750
+ || range.start < 0 || range.end <= range.start) {
751
+ throw new Error("INVALID_OPERATION: filler selection range must be positive");
752
+ }
753
+ return {
754
+ start: range.start,
755
+ end: range.end,
756
+ ...(range.startTime ? { startTime: { ...range.startTime } } : {}),
757
+ ...(range.durationTime ? { durationTime: { ...range.durationTime } } : {}),
758
+ };
759
+ }
760
+ function rangesOverlap(leftStart, leftEnd, rightStart, rightEnd) {
761
+ return leftStart < rightEnd && leftEnd > rightStart;
762
+ }
763
+ function translateClipRange(clipStartTime, clipStart, sourceRange) {
764
+ if (!sourceRange.startTime || !sourceRange.durationTime) {
765
+ throw new Error("ANALYSIS_INVALID: filler range is missing rational timing");
766
+ }
767
+ return {
768
+ start: clipStart + sourceRange.start,
769
+ end: clipStart + sourceRange.end,
770
+ startTime: addRationalTimes(clipStartTime, sourceRange.startTime),
771
+ durationTime: { ...sourceRange.durationTime },
772
+ };
773
+ }
774
+ function addRationalTimes(left, right) {
775
+ const leftParts = parseRational(left, "ANALYSIS_INVALID");
776
+ const rightParts = parseRational(right, "ANALYSIS_INVALID");
777
+ return normalizeRational(leftParts.value * rightParts.timescale + rightParts.value * leftParts.timescale, leftParts.timescale * rightParts.timescale);
778
+ }
779
+ function normalizeRational(value, timescale) {
780
+ const divisor = greatestCommonDivisor(value < 0n ? -value : value, timescale);
781
+ return { value: String(value / divisor), timescale: String(timescale / divisor) };
782
+ }
783
+ function greatestCommonDivisor(left, right) {
784
+ while (right !== 0n) {
785
+ const remainder = left % right;
786
+ left = right;
787
+ right = remainder;
788
+ }
789
+ return left || 1n;
790
+ }
791
+ function verifyFillerSpeechContinuity(transaction, record) {
792
+ for (const [clipId, beforeWords] of record.expectedWordsByClip) {
793
+ const beforeClip = transaction.before.timeline.clips.find((clip) => clip.id === clipId);
794
+ const afterClip = transaction.attemptedAfter.timeline.clips.find((clip) => clip.id === clipId);
795
+ const mediaId = beforeClip?.mediaId;
796
+ const actualWords = mediaId
797
+ ? transaction.attemptedAfter.media.find((media) => media.mediaId === mediaId)?.speech?.words
798
+ : undefined;
799
+ if (!beforeClip || !afterClip || !actualWords) {
800
+ return {
801
+ name: "filler-speech-continuity",
802
+ passed: false,
803
+ detail: `post-edit speech analysis is unavailable for filler target clip ${clipId}`,
804
+ };
805
+ }
806
+ const candidates = record.preview.candidates.filter((candidate) => candidate.clipId === clipId);
807
+ const expectedWords = beforeWords
808
+ .filter((word) => !candidates.some((candidate) => sameSpeechWord(candidate.word, word)))
809
+ .map((word) => {
810
+ const removedBefore = candidates
811
+ .filter((candidate) => candidate.sourceRange.end <= word.start)
812
+ .reduce((total, candidate) => total + (candidate.sourceRange.end - candidate.sourceRange.start), 0);
813
+ return { ...word, start: word.start - removedBefore, end: word.end - removedBefore };
814
+ });
815
+ if (expectedWords.length !== actualWords.length) {
816
+ return {
817
+ name: "filler-speech-continuity",
818
+ passed: false,
819
+ detail: `post-edit transcript has ${actualWords.length} words; expected ${expectedWords.length} adjacent words after filler removal`,
820
+ };
821
+ }
822
+ for (let index = 0; index < expectedWords.length; index += 1) {
823
+ const expected = expectedWords[index];
824
+ const actual = actualWords[index];
825
+ if (expected.text.trim().toLowerCase() !== actual.text.trim().toLowerCase()
826
+ || Math.abs(expected.start - actual.start) > 0.02
827
+ || Math.abs(expected.end - actual.end) > 0.02
828
+ || actual.end > afterClip.duration + 0.02) {
829
+ return {
830
+ name: "filler-speech-continuity",
831
+ passed: false,
832
+ detail: `post-edit transcript boundary ${index + 1} does not preserve adjacent speech around the removed fillers`,
833
+ };
834
+ }
835
+ }
836
+ }
837
+ return {
838
+ name: "filler-speech-continuity",
839
+ passed: true,
840
+ detail: "post-edit speech re-analysis preserves adjacent words and clip bounds",
841
+ };
842
+ }
843
+ function sameSpeechWord(left, right) {
844
+ return left.text === right.text && left.start === right.start && left.end === right.end;
845
+ }
846
+ function matchesAssetQuery(asset, query) {
847
+ if (!query)
848
+ return true;
849
+ const normalized = query.query?.trim().toLowerCase();
850
+ if (normalized && ![asset.id, asset.name, asset.vendor].some((value) => value.toLowerCase().includes(normalized)))
851
+ return false;
852
+ if (query.kind && asset.kind !== query.kind)
853
+ return false;
854
+ if (query.vendor && asset.vendor.toLowerCase() !== query.vendor.trim().toLowerCase())
855
+ return false;
856
+ return true;
857
+ }
858
+ function sameRevision(left, right) {
859
+ return left.id === right.id && left.sequence === right.sequence;
860
+ }
861
+ function parseRational(time, errorCode) {
862
+ if (!/^-?\d+$/.test(time.value) || !/^\d+$/.test(time.timescale)) {
863
+ throw new Error(`${errorCode}: rational time requires integer value and timescale`);
864
+ }
865
+ const value = BigInt(time.value);
866
+ const timescale = BigInt(time.timescale);
867
+ if (timescale <= 0n)
868
+ throw new Error(`${errorCode}: rational timescale must be positive`);
869
+ return { value, timescale };
870
+ }
871
+ function isWithinClip(position, startTime, durationTime) {
872
+ const start = parseRational(startTime, "INVALID_PROJECT_STATE");
873
+ const duration = parseRational(durationTime, "INVALID_PROJECT_STATE");
874
+ if (duration.value < 0n)
875
+ throw new Error("INVALID_PROJECT_STATE: clip duration cannot be negative");
876
+ const startsBeforeOrAtPosition = start.value * position.timescale <= position.value * start.timescale;
877
+ const endValue = start.value * duration.timescale + duration.value * start.timescale;
878
+ const endTimescale = start.timescale * duration.timescale;
879
+ const positionBeforeEnd = position.value * endTimescale < endValue * position.timescale;
880
+ return startsBeforeOrAtPosition && positionBeforeEnd;
881
+ }
882
+ function rationalDifferenceSeconds(left, right) {
883
+ const numerator = left.value * right.timescale - right.value * left.timescale;
884
+ const denominator = left.timescale * right.timescale;
885
+ const seconds = Number(numerator) / Number(denominator);
886
+ if (!Number.isFinite(seconds)) {
887
+ throw new Error("INVALID_TIMELINE_POSITION: relative media time is outside the supported analysis range");
888
+ }
889
+ return seconds;
890
+ }