@morshoto/framekit 0.2.2 → 0.2.4

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 (160) hide show
  1. package/dist-package/adapters/final-cut/typescript/src/analyzers.d.ts +58 -0
  2. package/dist-package/adapters/final-cut/typescript/src/analyzers.js +52 -13
  3. package/dist-package/adapters/final-cut/typescript/src/assets.d.ts +24 -0
  4. package/dist-package/adapters/final-cut/typescript/src/background-export.d.ts +98 -0
  5. package/dist-package/adapters/final-cut/typescript/src/background-materialization.d.ts +47 -0
  6. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery-guard.d.ts +32 -0
  7. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery.d.ts +22 -0
  8. package/dist-package/adapters/final-cut/typescript/src/canonical-verification.d.ts +11 -0
  9. package/dist-package/adapters/final-cut/typescript/src/canonical.d.ts +184 -0
  10. package/dist-package/adapters/final-cut/typescript/src/canonical.js +33 -1
  11. package/dist-package/adapters/final-cut/typescript/src/connection.d.ts +103 -0
  12. package/dist-package/adapters/final-cut/typescript/src/disposable-native.d.ts +90 -0
  13. package/dist-package/adapters/final-cut/typescript/src/documents.d.ts +3 -0
  14. package/dist-package/adapters/final-cut/typescript/src/documents.js +3 -0
  15. package/dist-package/adapters/final-cut/typescript/src/experimental.d.ts +8 -0
  16. package/dist-package/adapters/final-cut/typescript/src/export.d.ts +125 -0
  17. package/dist-package/adapters/final-cut/typescript/src/fcpxml-console-experiment.d.ts +54 -0
  18. package/dist-package/adapters/final-cut/typescript/src/fcpxml.d.ts +75 -0
  19. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +6 -1
  20. package/dist-package/adapters/final-cut/typescript/src/index.d.ts +22 -0
  21. package/dist-package/adapters/final-cut/typescript/src/library-inspection.d.ts +101 -0
  22. package/dist-package/adapters/final-cut/typescript/src/live.d.ts +101 -0
  23. package/dist-package/adapters/final-cut/typescript/src/live.js +8 -0
  24. package/dist-package/adapters/final-cut/typescript/src/media.d.ts +12 -0
  25. package/dist-package/adapters/final-cut/typescript/src/native-operation.d.ts +6 -0
  26. package/dist-package/adapters/final-cut/typescript/src/native-recovery-inspection.d.ts +77 -0
  27. package/dist-package/adapters/final-cut/typescript/src/native-session.d.ts +130 -0
  28. package/dist-package/adapters/final-cut/typescript/src/native.d.ts +828 -0
  29. package/dist-package/adapters/final-cut/typescript/src/native.js +274 -107
  30. package/dist-package/adapters/final-cut/typescript/src/pasteboard-snapshot.d.ts +114 -0
  31. package/dist-package/adapters/final-cut/typescript/src/publish-readback.d.ts +26 -0
  32. package/dist-package/adapters/final-cut/typescript/src/publish-readback.js +18 -2
  33. package/dist-package/adapters/final-cut/typescript/src/publisher.d.ts +215 -0
  34. package/dist-package/adapters/final-cut/typescript/src/session.d.ts +43 -0
  35. package/dist-package/adapters/final-cut/typescript/src/shadow-mutation.d.ts +51 -0
  36. package/dist-package/adapters/final-cut/typescript/src/sqlite-experiment.d.ts +156 -0
  37. package/dist-package/adapters/final-cut/typescript/src/sqlite-inspection.d.ts +134 -0
  38. package/dist-package/adapters/final-cut/typescript/src/sqlite-materialization.d.ts +110 -0
  39. package/dist-package/adapters/final-cut/typescript/src/sqlite-wal-observation.d.ts +132 -0
  40. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.d.ts +61 -0
  41. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +28 -4
  42. package/dist-package/adapters/final-cut/typescript/src/unattended-editing.d.ts +54 -0
  43. package/dist-package/adapters/headless/typescript/src/audio-output.d.ts +3 -0
  44. package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.d.ts +11 -0
  45. package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.js +26 -2
  46. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.d.ts +27 -0
  47. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +7 -2
  48. package/dist-package/adapters/headless/typescript/src/ffmpeg-storyboard.d.ts +28 -0
  49. package/dist-package/adapters/headless/typescript/src/ffmpeg-storyboard.js +120 -0
  50. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.d.ts +15 -0
  51. package/dist-package/adapters/headless/typescript/src/index.d.ts +4 -0
  52. package/dist-package/adapters/headless/typescript/src/index.js +1 -0
  53. package/dist-package/apps/cli/src/dev-doctor.d.ts +25 -0
  54. package/dist-package/apps/cli/src/headless-projects.d.ts +3 -0
  55. package/dist-package/apps/cli/src/main.d.ts +10 -0
  56. package/dist-package/apps/mcp-server/runtime/ffmpeg-audio-backend.py +129 -0
  57. package/dist-package/apps/mcp-server/runtime/whisper-speech-backend.py +92 -2
  58. package/dist-package/apps/mcp-server/src/build-alignment.d.ts +10 -0
  59. package/dist-package/apps/mcp-server/src/build-identity.d.ts +7 -0
  60. package/dist-package/apps/mcp-server/src/build-identity.json +2 -2
  61. package/dist-package/apps/mcp-server/src/canonical-native-snapshot.d.ts +8 -0
  62. package/dist-package/apps/mcp-server/src/final-cut-runtime-config.d.ts +5 -0
  63. package/dist-package/apps/mcp-server/src/headless-project-snapshot.d.ts +3 -0
  64. package/dist-package/apps/mcp-server/src/headless-sessions.d.ts +89 -0
  65. package/dist-package/apps/mcp-server/src/main.d.ts +1 -0
  66. package/dist-package/apps/mcp-server/src/main.js +2 -1
  67. package/dist-package/apps/mcp-server/src/materialization-jobs.d.ts +204 -0
  68. package/dist-package/apps/mcp-server/src/readback-policy.d.ts +18 -0
  69. package/dist-package/apps/mcp-server/src/routing.d.ts +90 -0
  70. package/dist-package/apps/mcp-server/src/server.d.ts +75 -0
  71. package/dist-package/apps/mcp-server/src/server.js +93 -9
  72. package/dist-package/apps/mcp-server/src/tools/skills/catalog.d.ts +19 -0
  73. package/dist-package/apps/mcp-server/src/tools/skills/metadata.d.ts +37 -0
  74. package/dist-package/apps/mcp-server/src/tools/skills/register.d.ts +11 -0
  75. package/dist-package/apps/mcp-server/src/version.d.ts +4 -0
  76. package/dist-package/packages/headless-application/src/external-edit.d.ts +30 -0
  77. package/dist-package/packages/headless-application/src/external-edit.js +72 -0
  78. package/dist-package/packages/headless-application/src/headless-projects.d.ts +259 -0
  79. package/dist-package/packages/headless-application/src/headless-projects.js +15 -2
  80. package/dist-package/packages/headless-application/src/index.d.ts +2 -0
  81. package/dist-package/packages/headless-application/src/index.js +1 -0
  82. package/dist-package/packages/runtime/src/application/duration-policy-service.d.ts +4 -0
  83. package/dist-package/packages/runtime/src/application/local-media.d.ts +46 -0
  84. package/dist-package/packages/runtime/src/application/media-analysis-service.d.ts +40 -0
  85. package/dist-package/packages/runtime/src/application/media-analysis-service.js +105 -15
  86. package/dist-package/packages/runtime/src/application/project-service.d.ts +35 -0
  87. package/dist-package/packages/runtime/src/application/project-store.d.ts +56 -0
  88. package/dist-package/packages/runtime/src/application/project-transactions.d.ts +51 -0
  89. package/dist-package/packages/runtime/src/application/runtime-options.d.ts +15 -0
  90. package/dist-package/packages/runtime/src/application/semantic-media-index-store.d.ts +28 -0
  91. package/dist-package/packages/runtime/src/application/transaction-store.d.ts +10 -0
  92. package/dist-package/packages/runtime/src/audio/analysis.d.ts +3 -0
  93. package/dist-package/packages/runtime/src/audio/analysis.js +95 -0
  94. package/dist-package/packages/runtime/src/audio/dialogue-normalization.d.ts +47 -0
  95. package/dist-package/packages/runtime/src/audio/noise-reduction.d.ts +34 -0
  96. package/dist-package/packages/runtime/src/capabilities.d.ts +45 -0
  97. package/dist-package/packages/runtime/src/color-correction.d.ts +33 -0
  98. package/dist-package/packages/runtime/src/context/context-engine.d.ts +28 -0
  99. package/dist-package/packages/runtime/src/context/context-service.d.ts +20 -0
  100. package/dist-package/packages/runtime/src/context/project-catalog.d.ts +12 -0
  101. package/dist-package/packages/runtime/src/context/revision.d.ts +2 -0
  102. package/dist-package/packages/runtime/src/domain/capabilities.d.ts +170 -0
  103. package/dist-package/packages/runtime/src/domain/context.d.ts +179 -0
  104. package/dist-package/packages/runtime/src/domain/diff.d.ts +104 -0
  105. package/dist-package/packages/runtime/src/domain/duration.d.ts +63 -0
  106. package/dist-package/packages/runtime/src/domain/editing.d.ts +227 -0
  107. package/dist-package/packages/runtime/src/domain/incremental-sync.d.ts +67 -0
  108. package/dist-package/packages/runtime/src/domain/index.d.ts +14 -0
  109. package/dist-package/packages/runtime/src/domain/media.d.ts +406 -0
  110. package/dist-package/packages/runtime/src/domain/ports.d.ts +62 -0
  111. package/dist-package/packages/runtime/src/domain/primitives.d.ts +21 -0
  112. package/dist-package/packages/runtime/src/domain/project.d.ts +119 -0
  113. package/dist-package/packages/runtime/src/domain/rough-cut.d.ts +27 -0
  114. package/dist-package/packages/runtime/src/domain/skills.d.ts +145 -0
  115. package/dist-package/packages/runtime/src/domain/timeline-target.d.ts +57 -0
  116. package/dist-package/packages/runtime/src/domain/timeline-target.js +19 -1
  117. package/dist-package/packages/runtime/src/domain/types.d.ts +5 -0
  118. package/dist-package/packages/runtime/src/domain/verification.d.ts +92 -0
  119. package/dist-package/packages/runtime/src/editing/dialogue-normalization-service.d.ts +18 -0
  120. package/dist-package/packages/runtime/src/editing/duration-policy.d.ts +3 -0
  121. package/dist-package/packages/runtime/src/editing/edit-service.d.ts +44 -0
  122. package/dist-package/packages/runtime/src/editing/filler-removal-service.d.ts +23 -0
  123. package/dist-package/packages/runtime/src/editing/intent.d.ts +97 -0
  124. package/dist-package/packages/runtime/src/editing/music-service.d.ts +9 -0
  125. package/dist-package/packages/runtime/src/index.d.ts +32 -0
  126. package/dist-package/packages/runtime/src/index.js +1 -0
  127. package/dist-package/packages/runtime/src/planning/rough-cut.d.ts +3 -0
  128. package/dist-package/packages/runtime/src/render/render-and-verify.d.ts +71 -0
  129. package/dist-package/packages/runtime/src/render/render-contract.d.ts +96 -0
  130. package/dist-package/packages/runtime/src/runtime.d.ts +85 -0
  131. package/dist-package/packages/runtime/src/skills/builtin.d.ts +2 -0
  132. package/dist-package/packages/runtime/src/skills/index.d.ts +3 -0
  133. package/dist-package/packages/runtime/src/skills/registry.d.ts +10 -0
  134. package/dist-package/packages/runtime/src/skills/requirements.d.ts +38 -0
  135. package/dist-package/packages/runtime/src/skills/runtime.d.ts +38 -0
  136. package/dist-package/packages/runtime/src/speech/analysis.d.ts +18 -0
  137. package/dist-package/packages/runtime/src/speech/analysis.js +67 -0
  138. package/dist-package/packages/runtime/src/speech/filler-detector.d.ts +49 -0
  139. package/dist-package/packages/runtime/src/speech/filler-removal.d.ts +37 -0
  140. package/dist-package/packages/runtime/src/speech/mapping.d.ts +56 -0
  141. package/dist-package/packages/runtime/src/speech/mapping.js +27 -4
  142. package/dist-package/packages/runtime/src/speech/safe-cut-resolver.d.ts +52 -0
  143. package/dist-package/packages/runtime/src/timeline/drift-reconciliation.d.ts +42 -0
  144. package/dist-package/packages/runtime/src/timeline/editing-session.d.ts +271 -0
  145. package/dist-package/packages/runtime/src/timeline/editing-session.js +32 -2
  146. package/dist-package/packages/runtime/src/timeline/fast-observation.d.ts +77 -0
  147. package/dist-package/packages/runtime/src/timeline/rational-time.d.ts +11 -0
  148. package/dist-package/packages/runtime/src/timeline/reorder-preview.d.ts +32 -0
  149. package/dist-package/packages/runtime/src/timeline/reorder-preview.js +202 -0
  150. package/dist-package/packages/runtime/src/timeline/snapshot-diff.d.ts +3 -0
  151. package/dist-package/packages/runtime/src/timeline/snapshot-diff.js +1 -0
  152. package/dist-package/packages/runtime/src/timeline/snapshot-digest.d.ts +3 -0
  153. package/dist-package/packages/runtime/src/timeline/snapshot-digest.js +1 -1
  154. package/dist-package/packages/runtime/src/verification/verification.d.ts +6 -0
  155. package/dist-package/packages/testkit/src/fixture-analyzers.d.ts +37 -0
  156. package/dist-package/packages/testkit/src/in-memory-editor.d.ts +55 -0
  157. package/dist-package/packages/testkit/src/index.d.ts +4 -0
  158. package/dist-package/packages/testkit/src/sender-lifecycle-fixture.d.ts +47 -0
  159. package/dist-package/packages/testkit/src/skill-fixtures.d.ts +3 -0
  160. package/package.json +17 -12
@@ -0,0 +1,58 @@
1
+ import type { AnalysisInput, AudioAnalysis, AudioAnalyzer, AnalyzerDescriptor, MetadataAnalysis, MetadataAnalyzer, SpeechAnalysis, SpeechAnalyzer, TimeRange, VisualAnalysis, VisualAnalyzer } from "../../../../packages/runtime/src/index.js";
2
+ export interface CommandAnalyzerOptions {
3
+ command: string;
4
+ timeoutMs?: number;
5
+ providerVersion?: string;
6
+ requireVad?: boolean;
7
+ }
8
+ export declare function createCommandAnalyzers(options: {
9
+ speechCommand?: string;
10
+ speechProviderVersion?: string;
11
+ speechRequireVad?: boolean;
12
+ audioCommand?: string;
13
+ visualCommand?: string;
14
+ metadataCommand?: string;
15
+ timeoutMs?: number;
16
+ }): {
17
+ speechAnalyzer?: SpeechAnalyzer;
18
+ audioAnalyzer?: AudioAnalyzer;
19
+ visualAnalyzer?: VisualAnalyzer;
20
+ metadataAnalyzer?: MetadataAnalyzer;
21
+ };
22
+ export declare class CommandSpeechAnalyzer implements SpeechAnalyzer {
23
+ private readonly options;
24
+ readonly descriptor: AnalyzerDescriptor;
25
+ readonly capabilities: {
26
+ transcription: true;
27
+ vad: boolean;
28
+ };
29
+ constructor(options: CommandAnalyzerOptions);
30
+ analyze(input: AnalysisInput, range?: TimeRange): Promise<SpeechAnalysis>;
31
+ }
32
+ export declare class CommandAudioAnalyzer implements AudioAnalyzer {
33
+ private readonly options;
34
+ readonly descriptor: {
35
+ id: string;
36
+ provider: string;
37
+ };
38
+ constructor(options: CommandAnalyzerOptions);
39
+ analyze(input: AnalysisInput, range?: TimeRange): Promise<AudioAnalysis>;
40
+ }
41
+ export declare class CommandVisualAnalyzer implements VisualAnalyzer {
42
+ private readonly options;
43
+ readonly descriptor: {
44
+ id: string;
45
+ provider: string;
46
+ };
47
+ constructor(options: CommandAnalyzerOptions);
48
+ analyze(input: AnalysisInput, range?: TimeRange): Promise<VisualAnalysis>;
49
+ }
50
+ export declare class CommandMetadataAnalyzer implements MetadataAnalyzer {
51
+ private readonly options;
52
+ readonly descriptor: {
53
+ id: string;
54
+ provider: string;
55
+ };
56
+ constructor(options: CommandAnalyzerOptions);
57
+ analyze(input: AnalysisInput, range?: TimeRange): Promise<MetadataAnalysis>;
58
+ }
@@ -1,6 +1,7 @@
1
1
  import { spawn } from "node:child_process";
2
- import { access } from "node:fs/promises";
3
- import { bindSpeechAnalysis, sameMediaSourceIdentity } from "../../../../packages/runtime/src/index.js";
2
+ import { createHash } from "node:crypto";
3
+ import { createReadStream } from "node:fs";
4
+ import { bindSpeechAnalysis, sameMediaSourceIdentity, validateAudioAnalysisPayload } from "../../../../packages/runtime/src/index.js";
4
5
  export function createCommandAnalyzers(options) {
5
6
  return {
6
7
  ...(options.speechCommand ? {
@@ -81,18 +82,17 @@ export class CommandMetadataAnalyzer {
81
82
  }
82
83
  async function runCommand(options, request, kind) {
83
84
  const source = request.media.source;
84
- try {
85
- await access(source);
86
- }
87
- catch {
88
- throw new Error(`ANALYZER_MEDIA_UNAVAILABLE: ${kind} source is not readable: ${source}`);
89
- }
90
85
  const timeoutMs = options.timeoutMs ?? 120_000;
86
+ const initialDigest = await digestAnalyzerSource(source, kind, timeoutMs);
87
+ const expectedDigest = request.media.sourceDigest?.replace(/^sha256:/, "");
88
+ if (expectedDigest !== undefined && expectedDigest !== initialDigest) {
89
+ throw new Error(`ANALYZER_SOURCE_CHANGED: ${kind} source bytes do not match the requested source digest`);
90
+ }
91
91
  const child = spawn(options.command, [], { stdio: ["pipe", "pipe", "pipe"] });
92
92
  const stdout = [];
93
93
  const stderr = [];
94
94
  let settled = false;
95
- return new Promise((resolve, reject) => {
95
+ const result = await new Promise((resolve, reject) => {
96
96
  const timer = setTimeout(() => {
97
97
  if (settled)
98
98
  return;
@@ -121,7 +121,7 @@ async function runCommand(options, request, kind) {
121
121
  }
122
122
  try {
123
123
  const value = JSON.parse(Buffer.concat(stdout).toString("utf8"));
124
- validateResult(value, kind);
124
+ validateResult(value, kind, request);
125
125
  resolve(value);
126
126
  }
127
127
  catch (error) {
@@ -130,6 +130,42 @@ async function runCommand(options, request, kind) {
130
130
  });
131
131
  child.stdin.end(JSON.stringify(commandRequest(request, kind)));
132
132
  });
133
+ if (await digestAnalyzerSource(source, kind, timeoutMs) !== initialDigest) {
134
+ throw new Error(`ANALYZER_SOURCE_CHANGED: ${kind} source bytes changed while analysis was running`);
135
+ }
136
+ return result;
137
+ }
138
+ async function digestAnalyzerSource(source, kind, timeoutMs) {
139
+ const stream = createReadStream(source);
140
+ let timedOut = false;
141
+ let timer;
142
+ try {
143
+ return await Promise.race([
144
+ (async () => {
145
+ const digest = createHash("sha256");
146
+ for await (const chunk of stream)
147
+ digest.update(chunk);
148
+ return digest.digest("hex");
149
+ })(),
150
+ new Promise((_resolve, reject) => {
151
+ timer = setTimeout(() => {
152
+ timedOut = true;
153
+ stream.destroy();
154
+ reject(new Error(`ANALYZER_TIMEOUT: ${kind} source verification exceeded ${timeoutMs}ms`));
155
+ }, timeoutMs);
156
+ }),
157
+ ]);
158
+ }
159
+ catch {
160
+ if (timedOut)
161
+ throw new Error(`ANALYZER_TIMEOUT: ${kind} source verification exceeded ${timeoutMs}ms`);
162
+ throw new Error(`ANALYZER_MEDIA_UNAVAILABLE: ${kind} source cannot be read for content verification: ${source}`);
163
+ }
164
+ finally {
165
+ if (timer)
166
+ clearTimeout(timer);
167
+ stream.destroy();
168
+ }
133
169
  }
134
170
  function commandRequest(request, kind) {
135
171
  if (kind !== "speech")
@@ -190,7 +226,7 @@ function sameRange(value, expected) {
190
226
  const range = value;
191
227
  return range.start === expected.start && range.end === expected.end;
192
228
  }
193
- function validateResult(value, kind) {
229
+ function validateResult(value, kind, request) {
194
230
  if (!value || typeof value !== "object")
195
231
  throw new Error("result must be an object");
196
232
  const record = value;
@@ -200,8 +236,11 @@ function validateResult(value, kind) {
200
236
  return;
201
237
  }
202
238
  if (kind === "audio") {
203
- if (!["integratedLufs", "truePeakDb", "silenceMs"].every((key) => typeof record[key] === "number"))
204
- throw new Error("audio result requires loudness fields");
239
+ validateAudioAnalysisPayload(value);
240
+ if (record.signalScope === "occurrence"
241
+ && (!request.occurrenceId || record.occurrenceId !== request.occurrenceId)) {
242
+ throw new Error("audio occurrence identity does not match the requested occurrence");
243
+ }
205
244
  return;
206
245
  }
207
246
  if (kind === "metadata") {
@@ -0,0 +1,24 @@
1
+ import type { AssetSearchQuery, EditorAsset } from "../../../../packages/runtime/src/index.js";
2
+ import type { NativeFinalCutTitleMatch, NativeFinalCutTransitionMatch } from "./native.js";
3
+ export interface FinalCutAssetRegistryOptions {
4
+ roots?: string[];
5
+ nativeTitleProvider?: Pick<NativeTitleProvider, "searchTitles">;
6
+ nativeTransitionProvider?: Pick<NativeTransitionProvider, "searchTransitions">;
7
+ }
8
+ export interface NativeTitleProvider {
9
+ searchTitles(query: string): Promise<NativeFinalCutTitleMatch[]>;
10
+ }
11
+ export interface NativeTransitionProvider {
12
+ searchTransitions(query: string): Promise<NativeFinalCutTransitionMatch[]>;
13
+ }
14
+ export declare function defaultFinalCutAssetRoots(): string[];
15
+ export declare class FinalCutAssetRegistry {
16
+ private readonly roots;
17
+ private readonly nativeTitleProvider?;
18
+ private readonly nativeTransitionProvider?;
19
+ private cached?;
20
+ constructor(options?: FinalCutAssetRegistryOptions);
21
+ listAssets(query?: AssetSearchQuery): Promise<EditorAsset[]>;
22
+ refresh(): void;
23
+ private scan;
24
+ }
@@ -0,0 +1,98 @@
1
+ import type { ContextRevision } from "../../../../packages/runtime/src/index.js";
2
+ export type BackgroundRenderSourceKind = "final-cut-timeline" | "fcpxml-artifact";
3
+ export interface BackgroundRenderTarget {
4
+ projectId: string;
5
+ sequenceId: string;
6
+ revision?: ContextRevision;
7
+ digest?: string;
8
+ }
9
+ export interface BackgroundRenderSource {
10
+ kind: BackgroundRenderSourceKind;
11
+ target: BackgroundRenderTarget;
12
+ artifactPath?: string;
13
+ }
14
+ export interface BackgroundRenderRequest {
15
+ source: BackgroundRenderSource;
16
+ outputPath: string;
17
+ preset: string;
18
+ overwrite?: boolean;
19
+ timeoutMs?: number;
20
+ }
21
+ export interface BackgroundRenderProbeResult {
22
+ durationSeconds: number;
23
+ width: number;
24
+ height: number;
25
+ frameRate: number;
26
+ hasAudio: boolean;
27
+ videoCodec?: string;
28
+ audioCodec?: string;
29
+ }
30
+ export interface BackgroundRenderMetadata extends BackgroundRenderProbeResult {
31
+ outputPath: string;
32
+ sizeBytes: number;
33
+ format: string;
34
+ outputDigest: string;
35
+ }
36
+ export type BackgroundRenderEvidenceTier = "background-native" | "artifact-rendered" | "external-rendered";
37
+ export interface BackgroundRenderProvenance {
38
+ renderer: "external-renderer";
39
+ evidenceTier: Exclude<BackgroundRenderEvidenceTier, "background-native">;
40
+ source: BackgroundRenderSource;
41
+ }
42
+ export interface BackgroundRenderResult {
43
+ jobId: string;
44
+ outputPath: string;
45
+ preset: string;
46
+ completed: true;
47
+ verified: true;
48
+ metadata: BackgroundRenderMetadata;
49
+ provenance: BackgroundRenderProvenance;
50
+ }
51
+ export type BackgroundRenderJobState = "queued" | "rendering" | "verifying" | "completed" | "cancelled" | "failed";
52
+ export interface BackgroundRenderJobStatus {
53
+ jobId: string;
54
+ state: BackgroundRenderJobState;
55
+ progress: number;
56
+ message: string;
57
+ error?: {
58
+ code: string;
59
+ message: string;
60
+ };
61
+ }
62
+ export interface BackgroundRenderExecutionContext {
63
+ request: BackgroundRenderRequest;
64
+ stagingPath: string;
65
+ signal: AbortSignal;
66
+ reportProgress(progress: number, message?: string): void;
67
+ }
68
+ export type BackgroundRenderExecutor = (context: BackgroundRenderExecutionContext) => Promise<void>;
69
+ export type BackgroundRenderProbe = (stagingPath: string) => Promise<BackgroundRenderProbeResult>;
70
+ export type BackgroundRenderProgressListener = (status: BackgroundRenderJobStatus) => void;
71
+ export interface BackgroundRenderJob {
72
+ readonly id: string;
73
+ status(): BackgroundRenderJobStatus;
74
+ onProgress(listener: BackgroundRenderProgressListener): () => void;
75
+ result(): Promise<BackgroundRenderResult>;
76
+ cancel(): Promise<void>;
77
+ }
78
+ export interface BackgroundRenderExportProviderOptions {
79
+ enabled?: boolean;
80
+ renderer?: BackgroundRenderExecutor;
81
+ probe?: BackgroundRenderProbe;
82
+ defaultTimeoutMs?: number;
83
+ }
84
+ /**
85
+ * Runs an injected background renderer against a staged output.
86
+ *
87
+ * This provider is intentionally external/artifact-derived. It does not invoke
88
+ * Final Cut UI and never labels its result as native Final Cut rendering.
89
+ */
90
+ export declare class BackgroundRenderExportProvider {
91
+ private readonly enabled;
92
+ private readonly renderer?;
93
+ private readonly probe?;
94
+ private readonly defaultTimeoutMs;
95
+ constructor(options?: BackgroundRenderExportProviderOptions);
96
+ isAvailable(): boolean;
97
+ start(request: BackgroundRenderRequest): BackgroundRenderJob;
98
+ }
@@ -0,0 +1,47 @@
1
+ import type { TimelineIr } from "../../../../packages/runtime/src/index.js";
2
+ import type { FinalCutTargetIdentity, TimelineIrMaterializationCoverage, TimelineIrMaterializationProvenance, TimelineIrToFcpxmlResult, TimelineIrToFcpxmlTarget } from "./timeline-ir-fcpxml.js";
3
+ export interface FinalCutBackgroundMaterializationRequest {
4
+ jobId: string;
5
+ artifactPath: string;
6
+ artifactDigest: string;
7
+ target: TimelineIrToFcpxmlTarget;
8
+ destination: TimelineIrToFcpxmlResult["destination"];
9
+ collisionPolicy: "create-only";
10
+ desired: TimelineIr;
11
+ desiredDigest: string;
12
+ baseDigest: string;
13
+ baseRevision: TimelineIr["revision"];
14
+ coverage: TimelineIrMaterializationCoverage;
15
+ provenance: TimelineIrMaterializationProvenance;
16
+ }
17
+ export type FinalCutBackgroundMaterializationResult = {
18
+ state: "completed";
19
+ canonicalReadback: TimelineIr;
20
+ canonicalTarget: FinalCutTargetIdentity;
21
+ headedNativeVerified: boolean;
22
+ } | {
23
+ state: "blocked";
24
+ code: string;
25
+ message: string;
26
+ retryable: boolean;
27
+ };
28
+ export interface FinalCutBackgroundMaterializationPublisherOptions {
29
+ executor?: (request: FinalCutBackgroundMaterializationRequest) => Promise<FinalCutBackgroundMaterializationResult>;
30
+ command?: string;
31
+ commandTimeoutMs?: number;
32
+ }
33
+ /**
34
+ * Publishes an immutable FCPXML artifact through an explicit non-UI Final Cut
35
+ * capability. The command owns Final Cut import and target-bound canonical
36
+ * readback; this adapter never activates Final Cut or falls back to UI calls.
37
+ */
38
+ export declare class FinalCutBackgroundMaterializationPublisher {
39
+ private readonly options;
40
+ private readonly dispatchContext;
41
+ private readonly commandTimeoutMs;
42
+ constructor(options?: FinalCutBackgroundMaterializationPublisherOptions);
43
+ isAvailable(): boolean;
44
+ trackNativeDispatch<T>(operation: () => Promise<T>, onDispatch: () => void): Promise<T>;
45
+ publish(request: FinalCutBackgroundMaterializationRequest): Promise<FinalCutBackgroundMaterializationResult>;
46
+ }
47
+ export declare function validateFinalCutBackgroundMaterializationRequest(request: FinalCutBackgroundMaterializationRequest): void;
@@ -0,0 +1,32 @@
1
+ import type { CanonicalRecoveryCheckpoint, CanonicalRecoveryGuard } from "./canonical.js";
2
+ import { type NativeMaterializationRecoveryContext, type NativePublishRecoveryContext } from "./native-recovery-inspection.js";
3
+ /** A durable, exclusive checkpoint; unresolved checkpoints are never cleared automatically. */
4
+ export declare class FileCanonicalRecoveryGuard implements CanonicalRecoveryGuard {
5
+ private readonly path;
6
+ private owner?;
7
+ constructor(path: string);
8
+ assertClear(): Promise<void>;
9
+ /** Read native reservation and sender evidence without acquiring or modifying locks. */
10
+ inspectNativeRecoveryEvidence(): Promise<import("./native-recovery-inspection.js").NativeRecoveryInspection>;
11
+ /** Return evidence only; inspection never clears or claims recovery. */
12
+ inspect(): Promise<CanonicalRecoveryCheckpoint | undefined>;
13
+ /** Inspect a direct native reservation without fabricating a canonical target. */
14
+ inspectNativeReservation(): Promise<{
15
+ reservationId: string;
16
+ operation: string;
17
+ } | undefined>;
18
+ /** Atomically reserve the same path used by canonical checkpoints. */
19
+ beginNative(operation: string, context?: NativeMaterializationRecoveryContext | NativePublishRecoveryContext): Promise<{
20
+ readonly reservationId: string;
21
+ markDispatchPossible(): Promise<void>;
22
+ bindRecoveryContext(context: NativeMaterializationRecoveryContext | NativePublishRecoveryContext): Promise<void>;
23
+ release(): Promise<void>;
24
+ }>;
25
+ inspectVersioned(): Promise<{
26
+ checkpointId: string;
27
+ checkpoint: CanonicalRecoveryCheckpoint;
28
+ } | undefined>;
29
+ begin(checkpoint: CanonicalRecoveryCheckpoint): Promise<void>;
30
+ complete(): Promise<void>;
31
+ private completeOwned;
32
+ }
@@ -0,0 +1,22 @@
1
+ import { type ProjectSnapshot, type TimelineTarget } from "../../../../packages/runtime/src/index.js";
2
+ export interface CanonicalRecoveryResult {
3
+ attempted: true;
4
+ succeeded: true;
5
+ operationId: string;
6
+ beforeDigest: string;
7
+ restoredDigest: string;
8
+ }
9
+ export interface CanonicalRecoveryRequest {
10
+ operationId: string;
11
+ before: ProjectSnapshot;
12
+ target: TimelineTarget;
13
+ undo: (operationId: string) => Promise<{
14
+ undone: boolean;
15
+ verification?: {
16
+ verified: boolean;
17
+ };
18
+ }>;
19
+ readSnapshot: () => Promise<ProjectSnapshot>;
20
+ }
21
+ /** Recover one verified native mutation and prove the original target digest. */
22
+ export declare function recoverCanonicalNativeMutation(request: CanonicalRecoveryRequest): Promise<CanonicalRecoveryResult>;
@@ -0,0 +1,11 @@
1
+ import { type ProjectSnapshot, type TimelineDiff, type TimelineTarget } from "../../../../packages/runtime/src/index.js";
2
+ export interface CanonicalReadbackEvidence {
3
+ beforeDigest: string;
4
+ afterDigest: string;
5
+ diff: TimelineDiff;
6
+ }
7
+ export interface CanonicalReadbackOptions {
8
+ validateDiff?: (diff: TimelineDiff) => void;
9
+ }
10
+ /** Validate one canonical before/after pair and return its durable evidence. */
11
+ export declare function verifyCanonicalReadback(before: ProjectSnapshot, after: ProjectSnapshot, target: TimelineTarget, options?: CanonicalReadbackOptions): CanonicalReadbackEvidence;
@@ -0,0 +1,184 @@
1
+ import { canonicalTimelineMode } from "../../../../packages/runtime/src/index.js";
2
+ import { type ContextRevision, type EditorChange, type EditorIdentity, type EditorLiveState, type EditOperation, type EditorPort, type LiveEditorStatePort, type ProjectCatalog, type ProjectSelection, type ProjectSelectionResult, type ProjectSnapshot, type RationalTime, type RuntimeCapabilities, type CapabilityInspectionOptions, type WorkflowOperation } from "../../../../packages/runtime/src/index.js";
3
+ import type { NativeFinalCutEditor } from "./native.js";
4
+ import { type FcpxmlTargetBinding } from "./fcpxml.js";
5
+ export interface CanonicalNativeMutationPort {
6
+ renameSelectedClip(name: string): Promise<{
7
+ operationId: string;
8
+ undoAvailable: boolean;
9
+ }>;
10
+ trimSelectedClipToRange?(range: {
11
+ start: RationalTime;
12
+ end: RationalTime;
13
+ }): Promise<{
14
+ operationId: string;
15
+ undoAvailable: boolean;
16
+ }>;
17
+ addMarkerAtTime?(marker: {
18
+ start: RationalTime;
19
+ duration: RationalTime;
20
+ name: string;
21
+ }): Promise<{
22
+ operationId: string;
23
+ undoAvailable: boolean;
24
+ }>;
25
+ rippleDeleteRange?(range: {
26
+ start: RationalTime;
27
+ end: RationalTime;
28
+ }): Promise<{
29
+ operationId: string;
30
+ undoAvailable: boolean;
31
+ }>;
32
+ setSelectedClipGain?(gainDb: number): Promise<{
33
+ operationId: string;
34
+ undoAvailable: boolean;
35
+ }>;
36
+ undo(operationId: string): Promise<{
37
+ undone: boolean;
38
+ verification?: {
39
+ verified: boolean;
40
+ };
41
+ }>;
42
+ }
43
+ export type CanonicalNativeTargetResolver = ((clip: ProjectSnapshot["timeline"]["clips"][number], snapshot: ProjectSnapshot) => Promise<void>) & {
44
+ trackNativeDispatch?<T>(operation: () => Promise<T>, onDispatch: () => void): Promise<T>;
45
+ sourceBindingAvailable?: boolean;
46
+ };
47
+ export interface FinalCutBackgroundCatalogProvider {
48
+ listProjects(): Promise<ProjectCatalog>;
49
+ backend?: string;
50
+ }
51
+ export interface CanonicalRecoveryCheckpoint {
52
+ projectId: string;
53
+ sequenceId: string;
54
+ baseRevision: string;
55
+ beforeDigest: string;
56
+ operation: string;
57
+ expectedRestoreDigest?: string;
58
+ }
59
+ export interface CanonicalRecoveryGuard {
60
+ assertClear(): Promise<void>;
61
+ begin(checkpoint: CanonicalRecoveryCheckpoint): Promise<void>;
62
+ complete(): Promise<void>;
63
+ }
64
+ export interface FinalCutCanonicalNativeProviderOptions {
65
+ live: LiveEditorStatePort & {
66
+ getIdentity(): Promise<EditorIdentity>;
67
+ getCapabilities?(options?: CapabilityInspectionOptions): Promise<RuntimeCapabilities>;
68
+ listProjects?(): Promise<ProjectCatalog>;
69
+ selectProject?(selection: ProjectSelection): Promise<ProjectSelectionResult>;
70
+ };
71
+ native: CanonicalNativeMutationPort;
72
+ readSnapshot: () => Promise<ProjectSnapshot>;
73
+ resolveTarget: CanonicalNativeTargetResolver;
74
+ backgroundCatalog?: FinalCutBackgroundCatalogProvider;
75
+ recoveryGuard?: CanonicalRecoveryGuard;
76
+ }
77
+ export interface FinalCutCanonicalSnapshotSourceOptions {
78
+ executor?: (script: string) => Promise<string>;
79
+ exportTimeoutMs?: number;
80
+ pollIntervalMs?: number;
81
+ target?: FcpxmlTargetBinding;
82
+ /** Catalog-bound publish readback. Catalog IDs are not FCPXML UIDs. */
83
+ readbackTarget?: {
84
+ projectId: string;
85
+ sequenceId: string;
86
+ projectName: string;
87
+ sequenceName: string;
88
+ };
89
+ }
90
+ export type FinalCutCanonicalExportCleanup = "complete" | "incomplete";
91
+ export type FinalCutCanonicalExportResult = {
92
+ status: "export-requested";
93
+ } | {
94
+ status: "retryable" | "failed";
95
+ code: string;
96
+ message: string;
97
+ cleanup: FinalCutCanonicalExportCleanup;
98
+ };
99
+ /** Structured failure returned when headed Export XML recovery can be retried. */
100
+ export declare class FinalCutCanonicalExportError extends Error {
101
+ readonly code: string;
102
+ readonly retryable: boolean;
103
+ readonly cleanup: FinalCutCanonicalExportCleanup;
104
+ constructor(result: Extract<FinalCutCanonicalExportResult, {
105
+ status: "retryable" | "failed";
106
+ }>);
107
+ toJSON(): {
108
+ code: string;
109
+ message: string;
110
+ retryable: boolean;
111
+ cleanup: FinalCutCanonicalExportCleanup;
112
+ };
113
+ }
114
+ /** Parse the JSON envelope returned by the headed canonical export workflow. */
115
+ export declare function parseFinalCutCanonicalExportResult(input: string | unknown): FinalCutCanonicalExportResult;
116
+ export interface CanonicalLiveReadiness {
117
+ ready: boolean;
118
+ mode: ReturnType<typeof canonicalTimelineMode>;
119
+ missing: string[];
120
+ }
121
+ /** Report the complete guarantees required before claiming canonical live support. */
122
+ export declare function assessCanonicalLiveReadiness(capabilities: RuntimeCapabilities): CanonicalLiveReadiness;
123
+ /** Reads the active Final Cut project through its headed Export XML command. */
124
+ export declare class FinalCutCanonicalSnapshotSource {
125
+ private readonly executor;
126
+ private readonly exportTimeoutMs;
127
+ private readonly pollIntervalMs;
128
+ private readonly target?;
129
+ private readonly readbackTarget?;
130
+ private readonly stageOnDesktop;
131
+ constructor(options?: FinalCutCanonicalSnapshotSourceOptions);
132
+ readSnapshot(): Promise<ProjectSnapshot>;
133
+ }
134
+ export declare function buildFinalCutCanonicalExportScript(exportPath: string): string;
135
+ export declare function createFinalCutNativeTargetResolver(native: Pick<NativeFinalCutEditor, "searchMedia" | "locateOccurrence"> & Partial<Pick<NativeFinalCutEditor, "capabilities" | "selectOccurrence" | "locateOccurrenceForCanonicalTarget" | "searchMediaForCanonicalTarget" | "trackNativeDispatch" | "inspectSelectedOccurrenceSource">>): CanonicalNativeTargetResolver;
136
+ /**
137
+ * Canonical provider for the headed Final Cut UI path.
138
+ *
139
+ * `readSnapshot` must export the currently active Final Cut project through
140
+ * Final Cut itself. It is deliberately injected so the provider cannot fall
141
+ * back to an arbitrary FCPXML artifact. Native mutation is separately bound
142
+ * to one exported occurrence before Accessibility is allowed to edit it.
143
+ */
144
+ export declare class FinalCutCanonicalNativeProvider implements EditorPort, LiveEditorStatePort {
145
+ private readonly live;
146
+ private readonly native;
147
+ private readonly readSnapshotSource;
148
+ private readonly resolveTarget;
149
+ private readonly backgroundCatalog?;
150
+ private lastDigest?;
151
+ private lastLiveRevision?;
152
+ private readonly revisionEpoch;
153
+ private lastSnapshot?;
154
+ private readonly readScope;
155
+ private selectedTarget?;
156
+ private revisionSequence;
157
+ private revision?;
158
+ private pending?;
159
+ private recoveryRequired;
160
+ private readonly recoveryGuard?;
161
+ constructor(options: FinalCutCanonicalNativeProviderOptions);
162
+ getIdentity(): Promise<EditorIdentity>;
163
+ withCanonicalReadScope<T>(operation: () => Promise<T>): Promise<T>;
164
+ getCapabilities(options?: CapabilityInspectionOptions): Promise<RuntimeCapabilities>;
165
+ private cachedCanonicalSnapshotAvailability;
166
+ private probeCanonicalSnapshot;
167
+ read(): Promise<ProjectSnapshot>;
168
+ readProject(): Promise<ProjectSnapshot>;
169
+ previewTransaction(operations: WorkflowOperation[], expectedRevision: ContextRevision): Promise<ProjectSnapshot>;
170
+ applyTransaction(operations: WorkflowOperation[], expectedRevision: ContextRevision): Promise<void>;
171
+ apply(operation: EditOperation, expectedRevision: ContextRevision): Promise<ContextRevision>;
172
+ private assertRecoveryNotRequired;
173
+ restore(snapshot: ProjectSnapshot, expectedRevision: ContextRevision): Promise<void>;
174
+ listProjects(): Promise<ProjectCatalog>;
175
+ selectProject(selection: ProjectSelection): Promise<ProjectSelectionResult>;
176
+ readLiveState(): Promise<EditorLiveState>;
177
+ liveChangesSince(revision: ContextRevision, waitMs?: number): Promise<EditorChange[]>;
178
+ private assertActiveTarget;
179
+ private resolveBackgroundCatalog;
180
+ private projectSelectionCapability;
181
+ private assertSelectedTarget;
182
+ private readBackgroundCatalog;
183
+ private readLiveStateSafely;
184
+ }
@@ -585,6 +585,9 @@ export function createFinalCutNativeTargetResolver(native) {
585
585
  catch {
586
586
  throw new Error(`TARGET_MISMATCH: invalid timeline coordinates for ${clip.id}`);
587
587
  }
588
+ if (compareRational(clip.durationTime, zeroRational()) <= 0) {
589
+ throw new Error(`TARGET_MISMATCH: nonpositive timeline duration for ${clip.id}`);
590
+ }
588
591
  if (!clip.mediaId)
589
592
  throw new Error(`TARGET_MISMATCH: occurrence ${clip.id} has no media binding`);
590
593
  const media = snapshot.media.find(({ mediaId }) => mediaId === clip.mediaId);
@@ -597,6 +600,7 @@ export function createFinalCutNativeTargetResolver(native) {
597
600
  if (!expectedSource) {
598
601
  throw new Error(`TARGET_MISMATCH: independently observed Browser source does not match the canonical source for ${clip.id}`);
599
602
  }
603
+ const relatedClips = [clip];
600
604
  for (const other of snapshot.timeline.clips) {
601
605
  if (other.id === clip.id)
602
606
  continue;
@@ -606,6 +610,9 @@ export function createFinalCutNativeTargetResolver(native) {
606
610
  // Unknown source identity cannot prove that another occurrence is unrelated.
607
611
  if (other.mediaId !== clip.mediaId && otherSource && otherSource !== expectedSource)
608
612
  continue;
613
+ if (!otherSource)
614
+ throw new Error("AMBIGUOUS_PROJECT_TARGET: timeline occurrence source is incomplete");
615
+ relatedClips.push(other);
609
616
  if (!other.startTime || !other.durationTime) {
610
617
  throw new Error("AMBIGUOUS_PROJECT_TARGET: timeline occurrence coordinates are incomplete");
611
618
  }
@@ -619,6 +626,13 @@ export function createFinalCutNativeTargetResolver(native) {
619
626
  if (sameRational(other.startTime, clip.startTime) && sameRational(other.durationTime, clip.durationTime)) {
620
627
  throw new Error(`AMBIGUOUS_PROJECT_TARGET: timeline occurrence coordinates are not unique for ${clip.id}`);
621
628
  }
629
+ if (compareRational(other.durationTime, zeroRational()) <= 0) {
630
+ throw new Error("AMBIGUOUS_PROJECT_TARGET: timeline occurrence coordinates have nonpositive duration");
631
+ }
632
+ if (compareRational(clip.startTime, addRational(other.startTime, other.durationTime)) < 0
633
+ && compareRational(other.startTime, addRational(clip.startTime, clip.durationTime)) < 0) {
634
+ throw new Error(`AMBIGUOUS_PROJECT_TARGET: same-source timeline occurrences overlap for ${clip.id}`);
635
+ }
622
636
  }
623
637
  const searchMedia = native.searchMediaForCanonicalTarget ?? native.searchMedia;
624
638
  const matches = (await searchMedia.call(native, query))
@@ -655,6 +669,24 @@ export function createFinalCutNativeTargetResolver(native) {
655
669
  throw new Error(`AMBIGUOUS_PROJECT_TARGET: Final Cut timeline occurrence coordinates are not unique for ${clip.id}`);
656
670
  }
657
671
  const occurrence = matchingOccurrences[0];
672
+ for (const candidate of located.occurrences) {
673
+ if (candidate === occurrence)
674
+ continue;
675
+ const [startValue, startScale] = candidate.start.trim().split("/");
676
+ const [durationValue, durationScale] = candidate.duration.trim().split("/");
677
+ const start = { value: startValue, timescale: startScale };
678
+ const duration = { value: durationValue, timescale: durationScale };
679
+ if (compareRational(duration, zeroRational()) <= 0) {
680
+ throw new Error("AMBIGUOUS_PROJECT_TARGET: discovered occurrence duration is invalid");
681
+ }
682
+ if (compareRational(clip.startTime, addRational(start, duration)) < 0
683
+ && compareRational(start, addRational(clip.startTime, clip.durationTime)) < 0) {
684
+ throw new Error(`AMBIGUOUS_PROJECT_TARGET: discovered timeline occurrences overlap for ${clip.id}`);
685
+ }
686
+ }
687
+ if (located.occurrences.length !== relatedClips.length || relatedClips.some((related) => located.occurrences.filter((candidate) => sameRationalText(candidate.start, related.startTime) && sameRationalText(candidate.duration, related.durationTime)).length !== 1)) {
688
+ throw new Error("AMBIGUOUS_PROJECT_TARGET: native occurrence discovery is incomplete or inconsistent with the snapshot");
689
+ }
658
690
  const occurrenceIdentity = occurrence.identity ?? occurrence.nativeIdentity;
659
691
  if (!occurrenceIdentity) {
660
692
  throw new Error(`TARGET_MISMATCH: native occurrence has no stable identity for ${clip.id}`);
@@ -985,7 +1017,7 @@ export class FinalCutCanonicalNativeProvider {
985
1017
  : undefined;
986
1018
  const clip = clipTarget?.clip;
987
1019
  const rippleTarget = supported.type === "ripple-delete" ? canonicalTargetForOperation(before, supported) : undefined;
988
- const targetClip = clip;
1020
+ const targetClip = clip ?? rippleTarget?.clip;
989
1021
  const trimDuration = supported.type === "trim-clip"
990
1022
  ? validateCanonicalTrim(supported, clip, before)
991
1023
  : undefined;