@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,103 @@
1
+ import type { EditorIdentity, RuntimeCapabilities } from "../../../../packages/runtime/src/index.js";
2
+ export type FinalCutConnectionState = "disconnected" | "detecting" | "installing" | "launching" | "restarting" | "activating" | "waiting-for-socket" | "ready" | "needs-user-action" | "unavailable";
3
+ export interface FinalCutConnectionStatus {
4
+ state: FinalCutConnectionState;
5
+ editorDetected: boolean;
6
+ extensionInstalled: boolean;
7
+ extensionPath: string;
8
+ socketPath: string;
9
+ identity?: EditorIdentity;
10
+ capabilities?: RuntimeCapabilities;
11
+ lastError?: {
12
+ code: string;
13
+ message: string;
14
+ };
15
+ updatedAt: string;
16
+ }
17
+ export interface FinalCutConnectionOptions {
18
+ /** Probe an existing Workflow Extension socket without launching or activating Final Cut. */
19
+ headless?: boolean;
20
+ /** Probe only the existing socket; do not install, launch, activate, or retry. */
21
+ existingSocketOnly?: boolean;
22
+ /** Require an external provider that advertises verified canonical writes. */
23
+ canonicalProviderRequired?: boolean;
24
+ socketPath?: string;
25
+ extensionSourcePath?: string;
26
+ extensionInstallPath?: string;
27
+ finalCutApp?: string;
28
+ pollIntervalMs?: number;
29
+ startupTimeoutMs?: number;
30
+ detectFinalCut?: () => Promise<boolean>;
31
+ launchFinalCut?: () => Promise<void>;
32
+ installExtension?: () => Promise<void>;
33
+ launchExtension?: () => Promise<void>;
34
+ registerExtension?: () => Promise<void>;
35
+ activateExtension?: (options?: FinalCutActivationOptions) => Promise<void>;
36
+ restartFinalCut?: () => Promise<void>;
37
+ restartAfterInstall?: boolean;
38
+ /** Install the configured extension source before accepting an existing bridge. */
39
+ installBeforeProbe?: boolean;
40
+ probe?: () => Promise<{
41
+ identity: EditorIdentity;
42
+ capabilities: RuntimeCapabilities;
43
+ }>;
44
+ sleep?: (milliseconds: number) => Promise<void>;
45
+ }
46
+ export interface FinalCutEnsureConnectedOptions {
47
+ /** Background lifecycle probes must never reopen an editor the user quit. */
48
+ allowEditorLaunch?: boolean;
49
+ }
50
+ export interface CanonicalProviderConfiguration {
51
+ required: boolean;
52
+ fcpxmlPath?: string;
53
+ }
54
+ export declare function assertCanonicalProviderConfiguration(options: CanonicalProviderConfiguration): void;
55
+ export interface FinalCutActivationOptions {
56
+ signal?: AbortSignal;
57
+ timeoutMs?: number;
58
+ }
59
+ /**
60
+ * Owns the user-facing lifecycle around the native Workflow Extension.
61
+ * The live adapter remains the source of truth for Final Cut state; this class
62
+ * only installs, activates, probes, and reconnects the bridge.
63
+ */
64
+ export declare class FinalCutConnectionManager {
65
+ private readonly socketPath;
66
+ private readonly headless;
67
+ private readonly existingSocketOnly;
68
+ private readonly canonicalProviderRequired;
69
+ private readonly extensionSourcePath?;
70
+ private readonly extensionInstallPath;
71
+ private readonly finalCutApp;
72
+ private readonly pollIntervalMs;
73
+ private readonly startupTimeoutMs;
74
+ private readonly activationRetryIntervalMs;
75
+ private readonly detectFinalCut;
76
+ private readonly launchFinalCut;
77
+ private readonly installExtensionAction;
78
+ private readonly launchExtension;
79
+ private readonly registerExtension;
80
+ private readonly activateExtension;
81
+ private readonly restartFinalCut;
82
+ private readonly restartAfterInstall;
83
+ private readonly installBeforeProbe;
84
+ private readonly probe;
85
+ private readonly sleep;
86
+ private status;
87
+ private attempt?;
88
+ private interval?;
89
+ constructor(options?: FinalCutConnectionOptions);
90
+ getStatus(): FinalCutConnectionStatus;
91
+ startAutoConnect(): void;
92
+ stopAutoConnect(): void;
93
+ ensureConnected(options?: FinalCutEnsureConnectedOptions): Promise<FinalCutConnectionStatus>;
94
+ private connect;
95
+ private tryProbe;
96
+ private waitForHeadlessBridge;
97
+ private ready;
98
+ private fail;
99
+ private update;
100
+ private activateUntil;
101
+ private activateWithDeadline;
102
+ private installExtensionIfAvailable;
103
+ }
@@ -0,0 +1,90 @@
1
+ import { type ContextRevision, type ProjectSnapshot, type RuntimeCapabilities, type TimelineDiff, type VerificationReport } from "../../../../packages/runtime/src/index.js";
2
+ import type { NativeFinalCutEditor, NativeFinalCutEditResult, NativeFinalCutUndoResult } from "./native.js";
3
+ type DisposableNativeTargetPreparer = (target: ProjectSnapshot["timeline"]["clips"][number], snapshot: ProjectSnapshot) => Promise<void>;
4
+ export interface NativeFinalCutDisposableRequest {
5
+ /** Canonical timeline occurrence ID selected in Final Cut before preview. */
6
+ clipId: string;
7
+ /** New name used by the first disposable native operation. */
8
+ name: string;
9
+ baseRevision?: ContextRevision;
10
+ }
11
+ export interface NativeFinalCutDisposablePreview {
12
+ previewToken: string;
13
+ operation: {
14
+ type: "rename-selected-clip";
15
+ name: string;
16
+ };
17
+ target: {
18
+ clipId: string;
19
+ name: string;
20
+ identity?: string;
21
+ occurrenceIndex?: number;
22
+ };
23
+ projectId: string;
24
+ sequenceId: string;
25
+ targetIdentity: string;
26
+ baseRevision: ContextRevision;
27
+ expiresAt: string;
28
+ }
29
+ export interface NativeFinalCutDisposableExecutionOptions {
30
+ signal?: AbortSignal;
31
+ onMutationStart?: () => void;
32
+ }
33
+ export interface NativeFinalCutDisposableResult {
34
+ operationId: string;
35
+ previewToken: string;
36
+ operation: NativeFinalCutDisposableRequest;
37
+ native: NativeFinalCutEditResult;
38
+ before: ProjectSnapshot;
39
+ after: ProjectSnapshot;
40
+ diff: TimelineDiff;
41
+ beforeDigest: string;
42
+ afterDigest: string;
43
+ verification: VerificationReport;
44
+ status: "VERIFIED" | "ROLLED_BACK";
45
+ undoAvailable: boolean;
46
+ restored?: ProjectSnapshot;
47
+ restoredDigest?: string;
48
+ }
49
+ export interface NativeFinalCutDisposableUndoResult {
50
+ operationId: string;
51
+ undone: boolean;
52
+ native: NativeFinalCutUndoResult;
53
+ restored: ProjectSnapshot;
54
+ beforeDigest: string;
55
+ restoredDigest: string;
56
+ verification: VerificationReport;
57
+ }
58
+ export interface DisposableNativeEditWorkflowOptions {
59
+ native: Pick<NativeFinalCutEditor, "capabilities" | "inspect" | "edit" | "undo" | "trackNativeDispatch">;
60
+ readCanonicalSnapshot: () => Promise<ProjectSnapshot>;
61
+ readCanonicalCapabilities: () => Promise<RuntimeCapabilities>;
62
+ prepareTarget?: DisposableNativeTargetPreparer;
63
+ now?: () => number;
64
+ previewTtlMs?: number;
65
+ maxOperations?: number;
66
+ }
67
+ /**
68
+ * Composes one guarded native UI edit with a canonical snapshot provider.
69
+ * Native UI is the mutation surface; canonical snapshots are the proof surface.
70
+ */
71
+ export declare class DisposableNativeEditWorkflow {
72
+ private readonly options;
73
+ private readonly previews;
74
+ private readonly operations;
75
+ private readonly now;
76
+ private readonly previewTtlMs;
77
+ private readonly maxOperations;
78
+ constructor(options: DisposableNativeEditWorkflowOptions);
79
+ trackNativeDispatch<T>(operation: () => Promise<T>, onDispatch: () => void): Promise<T>;
80
+ preview(request: NativeFinalCutDisposableRequest): Promise<NativeFinalCutDisposablePreview>;
81
+ getPreview(previewToken: string): NativeFinalCutDisposablePreview | undefined;
82
+ execute(previewToken: string, options?: NativeFinalCutDisposableExecutionOptions): Promise<NativeFinalCutDisposableResult>;
83
+ undo(operationId: string): Promise<NativeFinalCutDisposableUndoResult>;
84
+ private readCanonical;
85
+ private assertNativeTarget;
86
+ private compensate;
87
+ private prunePreviews;
88
+ private pruneOperations;
89
+ }
90
+ export {};
@@ -0,0 +1,3 @@
1
+ /** FCPXML document processing. Importing this entrypoint never connects to an editor. */
2
+ export * from "./fcpxml.js";
3
+ export * from "./timeline-ir-fcpxml.js";
@@ -0,0 +1,3 @@
1
+ /** FCPXML document processing. Importing this entrypoint never connects to an editor. */
2
+ export * from "./fcpxml.js";
3
+ export * from "./timeline-ir-fcpxml.js";
@@ -0,0 +1,8 @@
1
+ export * from "./sqlite-inspection.js";
2
+ export * from "./sqlite-wal-observation.js";
3
+ export * from "./sqlite-experiment.js";
4
+ export * from "./sqlite-materialization.js";
5
+ export * from "./shadow-mutation.js";
6
+ export * from "./fcpxml-console-experiment.js";
7
+ export * from "./unattended-editing.js";
8
+ export * from "./pasteboard-snapshot.js";
@@ -0,0 +1,125 @@
1
+ import type { AudioAnalysis, VerificationReport, VisualAnalysis } from "../../../../packages/runtime/src/index.js";
2
+ import type { NativeFinalCutContext } from "./native.js";
3
+ import type { NativeOperationLease } from "./native-operation.js";
4
+ export declare const FINAL_CUT_EXPORT_PRESETS: {
5
+ readonly master: {
6
+ readonly menuItem: "Export File";
7
+ };
8
+ readonly web: {
9
+ readonly menuItem: "Web Hosting";
10
+ };
11
+ };
12
+ export type FinalCutExportPreset = keyof typeof FINAL_CUT_EXPORT_PRESETS;
13
+ export type FinalCutVideoExportAssertion = {
14
+ type: "audio-audibility";
15
+ minAudibleSamples?: number;
16
+ maxSilenceMs?: number;
17
+ } | {
18
+ type: "audio-coverage";
19
+ expectedSeconds: number;
20
+ toleranceSeconds?: number;
21
+ } | {
22
+ type: "audio-loudness";
23
+ targetLufs: number;
24
+ toleranceDb?: number;
25
+ } | {
26
+ type: "audio-source";
27
+ sourceDigest?: string;
28
+ source?: string;
29
+ } | {
30
+ type: "visual-content";
31
+ label: string;
32
+ labelKind?: "scene" | "subject";
33
+ minConfidence?: number;
34
+ } | {
35
+ type: "stream";
36
+ target: "audio" | "video";
37
+ expected: boolean;
38
+ };
39
+ export interface FinalCutExportSemanticAnalysis {
40
+ audio?: AudioAnalysis;
41
+ visual?: VisualAnalysis;
42
+ sourceDigest?: string;
43
+ source?: string;
44
+ }
45
+ export interface FinalCutVideoExportExpectation {
46
+ durationSeconds?: number;
47
+ durationToleranceSeconds?: number;
48
+ width?: number;
49
+ height?: number;
50
+ frameRate?: number;
51
+ frameRateTolerance?: number;
52
+ hasAudio?: boolean;
53
+ assertions?: FinalCutVideoExportAssertion[];
54
+ }
55
+ export interface FinalCutVideoExportRequest {
56
+ outputPath: string;
57
+ preset: FinalCutExportPreset;
58
+ overwrite?: boolean;
59
+ expected?: FinalCutVideoExportExpectation;
60
+ }
61
+ export interface FinalCutVideoProbeResult {
62
+ durationSeconds: number;
63
+ width: number;
64
+ height: number;
65
+ frameRate: number;
66
+ hasAudio: boolean;
67
+ videoCodec?: string;
68
+ audioCodec?: string;
69
+ semantic?: FinalCutExportSemanticAnalysis;
70
+ }
71
+ export interface FinalCutVideoMetadata extends FinalCutVideoProbeResult {
72
+ outputPath: string;
73
+ sizeBytes: number;
74
+ format: string;
75
+ outputDigest: string;
76
+ }
77
+ export interface FinalCutVideoExportResult {
78
+ outputPath: string;
79
+ preset: FinalCutExportPreset;
80
+ completed: true;
81
+ verified: true;
82
+ metadata: FinalCutVideoMetadata;
83
+ verification: VerificationReport;
84
+ }
85
+ export interface FinalCutVideoExporterOptions {
86
+ enabled?: boolean;
87
+ executor?: (script: string) => Promise<string>;
88
+ preflight?: () => Promise<NativeFinalCutContext>;
89
+ probe?: (outputPath: string) => Promise<FinalCutVideoProbeResult>;
90
+ probeAvailability?: () => Promise<boolean>;
91
+ probeAvailable?: boolean;
92
+ waitMs?: number;
93
+ pollMs?: number;
94
+ stablePolls?: number;
95
+ now?: () => number;
96
+ sleep?: (milliseconds: number) => Promise<void>;
97
+ nativeOperationLease?: NativeOperationLease;
98
+ suspendLiveConnection?: () => void;
99
+ resumeLiveConnection?: () => void;
100
+ }
101
+ export declare function isFinalCutVideoProbeAvailable(): Promise<boolean>;
102
+ /** Exports the active Final Cut timeline and verifies the resulting media file. */
103
+ export declare class FinalCutVideoExporter {
104
+ private readonly enabled;
105
+ private readonly executor;
106
+ private readonly preflight?;
107
+ private readonly probe;
108
+ private readonly probeAvailability?;
109
+ private readonly probeAvailable;
110
+ private readonly waitMs;
111
+ private readonly pollMs;
112
+ private readonly stablePolls;
113
+ private readonly now;
114
+ private readonly sleep;
115
+ private readonly nativeOperationLease?;
116
+ private readonly suspendLiveConnection?;
117
+ private readonly resumeLiveConnection?;
118
+ constructor(options?: FinalCutVideoExporterOptions);
119
+ isAvailable(): boolean;
120
+ exportVideo(request: FinalCutVideoExportRequest): Promise<FinalCutVideoExportResult>;
121
+ private assertPreflight;
122
+ private waitForOutput;
123
+ private probeUntilReady;
124
+ private withNativeUi;
125
+ }
@@ -0,0 +1,54 @@
1
+ export type FinalCutFcpxmlConsoleState = "unlocked" | "locked" | "unknown";
2
+ export type FinalCutFcpxmlProcessState = "running" | "not-running";
3
+ export type FinalCutFcpxmlFrontmostState = "final-cut" | "other" | "unknown";
4
+ export type FinalCutFcpxmlLibraryEvidence = "filesystem" | "native" | "none";
5
+ export interface FinalCutFcpxmlExperimentObservation {
6
+ artifact: {
7
+ format: "fcpxml";
8
+ version: string;
9
+ digest: string;
10
+ valid: boolean;
11
+ };
12
+ process: FinalCutFcpxmlProcessState;
13
+ frontmost: FinalCutFcpxmlFrontmostState;
14
+ console: {
15
+ state: FinalCutFcpxmlConsoleState;
16
+ source: string;
17
+ retryable: boolean;
18
+ };
19
+ library: {
20
+ state: "observed" | "not-inspected" | "unavailable";
21
+ evidence: FinalCutFcpxmlLibraryEvidence;
22
+ };
23
+ log: {
24
+ state: "observed" | "not-collected" | "unavailable";
25
+ lineCount: number;
26
+ };
27
+ }
28
+ export type FinalCutFcpxmlExperimentStatus = "artifact-only" | "headed-preflight-ready" | "blocked";
29
+ export type FinalCutFcpxmlCapability = "verified" | "preflight-only" | "blocked" | "unavailable";
30
+ export interface FinalCutFcpxmlExperimentResult {
31
+ schemaVersion: 1;
32
+ status: FinalCutFcpxmlExperimentStatus;
33
+ observation: FinalCutFcpxmlExperimentObservation;
34
+ capabilities: {
35
+ artifactRead: FinalCutFcpxmlCapability;
36
+ headedImport: FinalCutFcpxmlCapability;
37
+ targetBoundReadback: FinalCutFcpxmlCapability;
38
+ };
39
+ blockers: Array<{
40
+ code: string;
41
+ retryable: boolean;
42
+ message: string;
43
+ }>;
44
+ mutationAttempted: false;
45
+ nativeImportVerified: false;
46
+ safeToOverwrite: false;
47
+ }
48
+ /**
49
+ * Classifies evidence collected around the FCPXML programmatic/artifact path.
50
+ * This function never authorizes a write: a headed result is preflight only,
51
+ * and target-bound import readback remains unavailable until independently
52
+ * proven by a native provider.
53
+ */
54
+ export declare function classifyFinalCutFcpxmlExperiment(observation: FinalCutFcpxmlExperimentObservation): FinalCutFcpxmlExperimentResult;
@@ -0,0 +1,75 @@
1
+ import type { ContextRevision, EditOperation, EditorAsset, EditorIdentity, EditorPort, ManagedArtifact, ProjectSnapshot, ProjectCatalog, ProjectSelection, ProjectSelectionResult, RuntimeCapabilities } from "../../../../packages/runtime/src/index.js";
2
+ export interface FcpxmlTargetBinding {
3
+ projectId: string;
4
+ projectUid: string;
5
+ sequenceId: string;
6
+ }
7
+ export interface FcpxmlDocumentAdapterOptions {
8
+ /** Allows deterministic path-bound IDs when reading artifacts without immutable UIDs. */
9
+ allowMissingImmutableIdsForReadback?: boolean;
10
+ }
11
+ /**
12
+ * FCPXML document interchange adapter. It edits the artifact on disk; it does
13
+ * not claim that the currently open Final Cut session changed.
14
+ */
15
+ export declare class FcpxmlDocumentAdapter implements EditorPort {
16
+ private readonly filePath;
17
+ private readonly target?;
18
+ private readonly parser;
19
+ private readonly builder;
20
+ private xml?;
21
+ private sequence;
22
+ private fileSignature?;
23
+ private readonly history;
24
+ private readonly allowMissingImmutableIdsForReadback;
25
+ constructor(filePath: string, target?: FcpxmlTargetBinding | undefined, options?: FcpxmlDocumentAdapterOptions);
26
+ getIdentity(): Promise<EditorIdentity>;
27
+ getManagedArtifact(): Promise<ManagedArtifact>;
28
+ getManagedArtifactDigest(): Promise<string>;
29
+ getCapabilities(): Promise<RuntimeCapabilities>;
30
+ listAssets(): Promise<EditorAsset[]>;
31
+ read(): Promise<ProjectSnapshot>;
32
+ readProject(): Promise<ProjectSnapshot>;
33
+ listProjects(): Promise<ProjectCatalog>;
34
+ selectProject(selection: ProjectSelection): Promise<ProjectSelectionResult>;
35
+ apply(operation: EditOperation, expectedRevision: ContextRevision): Promise<ContextRevision>;
36
+ previewTransaction(operations: import("../../../../packages/runtime/src/index.js").WorkflowOperation[], expectedRevision: ContextRevision): Promise<ProjectSnapshot>;
37
+ applyTransaction(operations: import("../../../../packages/runtime/src/index.js").WorkflowOperation[], expectedRevision: ContextRevision): Promise<void>;
38
+ private assertArtifactOperationSupported;
39
+ private identity;
40
+ private applyOperation;
41
+ private applyMarker;
42
+ private findClipEntry;
43
+ private mediaResource;
44
+ private effectResource;
45
+ private applyMediaAdd;
46
+ private applyAudioFades;
47
+ private applyTitleAdd;
48
+ private applyMediaMove;
49
+ private applyMediaReplace;
50
+ private applyMediaRemove;
51
+ private applyTransitionAdd;
52
+ private applyAudioAttach;
53
+ private applyAudioMix;
54
+ private setAudioFades;
55
+ private assertNewOccurrence;
56
+ private assertSourceRange;
57
+ private applyRippleDelete;
58
+ private applyPictureInPicture;
59
+ restore(snapshot: ProjectSnapshot, expectedRevision: ContextRevision): Promise<void>;
60
+ private ensureLoaded;
61
+ private persist;
62
+ private projectNode;
63
+ private storyElementFromXml;
64
+ private clipFromXml;
65
+ private instanceId;
66
+ private findClipNode;
67
+ private effectAssetId;
68
+ private setAdjustVolume;
69
+ private markersFromXml;
70
+ private captionsFromXml;
71
+ private updateSequenceDuration;
72
+ private mediaFromResources;
73
+ private revision;
74
+ }
75
+ export declare function resolveMediaSource(source: string, documentPath: string): string;
@@ -164,6 +164,7 @@ export class FcpxmlDocumentAdapter {
164
164
  name: sequenceName,
165
165
  duration: rationalSeconds(durationTime),
166
166
  durationTime,
167
+ ...(attribute(sequence, "tcStart") !== undefined ? { timecodeStart: parseRational(attribute(sequence, "tcStart")) } : {}),
167
168
  ...(frameDuration ? { frameDuration } : {}),
168
169
  clips,
169
170
  storyElements,
@@ -979,8 +980,9 @@ export class FcpxmlDocumentAdapter {
979
980
  const resources = findElement(this.xml ?? [], "resources");
980
981
  return storyEntries(resources ?? {})
981
982
  .filter(({ kind }) => kind === "asset" || kind === "media")
982
- .map(({ node }) => {
983
+ .map(({ kind, node }) => {
983
984
  const durationValue = attribute(node, "duration");
985
+ const startValue = attribute(node, "start");
984
986
  const mediaKind = mediaKindFromResource(node);
985
987
  const originalMedia = storyEntries(node).find(({ kind, node: representation }) => kind === "media-rep" && attribute(representation, "kind") === "original-media")?.node;
986
988
  const rawSource = attribute(node, "src") ?? (originalMedia && attribute(originalMedia, "src"));
@@ -990,6 +992,9 @@ export class FcpxmlDocumentAdapter {
990
992
  source: source.trim() ? resolveMediaSource(source, this.filePath) : "",
991
993
  ...(mediaKind ? { mediaKind } : {}),
992
994
  ...(durationValue !== undefined ? { duration: parseSeconds(durationValue) } : {}),
995
+ ...(kind === "asset" && startValue !== undefined && durationValue !== undefined
996
+ ? { sourceRange: { start: parseRational(startValue), duration: parseRational(durationValue) } }
997
+ : {}),
993
998
  };
994
999
  })
995
1000
  .filter((media) => media.mediaId.length > 0);
@@ -0,0 +1,22 @@
1
+ export * from "./fcpxml.js";
2
+ export * from "./live.js";
3
+ export * from "./connection.js";
4
+ export * from "./canonical.js";
5
+ export * from "./canonical-recovery.js";
6
+ export * from "./canonical-verification.js";
7
+ export * from "./session.js";
8
+ export * from "./analyzers.js";
9
+ export * from "./assets.js";
10
+ export * from "./media.js";
11
+ export * from "./native.js";
12
+ export * from "./disposable-native.js";
13
+ export * from "./publisher.js";
14
+ export * from "./publish-readback.js";
15
+ export * from "./export.js";
16
+ export * from "./background-export.js";
17
+ export * from "./background-materialization.js";
18
+ export * from "./library-inspection.js";
19
+ export * from "./native-operation.js";
20
+ export * from "./native-session.js";
21
+ export * from "./timeline-ir-fcpxml.js";
22
+ export * from "./canonical-recovery-guard.js";
@@ -0,0 +1,101 @@
1
+ import type { ProjectCatalog, RationalTime } from "../../../../packages/runtime/src/index.js";
2
+ export declare const FINAL_CUT_LIBRARY_INSPECTION_BACKEND: "final-cut-background-library";
3
+ export declare const FINAL_CUT_LIBRARY_INSPECTION_TIMEOUT_MS = 30000;
4
+ export type FinalCutLibraryInspectionIssueCode = "FINAL_CUT_LIBRARY_FIELD_UNAVAILABLE" | "FINAL_CUT_LIBRARY_INSPECTION_UNAVAILABLE" | "FINAL_CUT_LIBRARY_RESPONSE_INVALID" | "FINAL_CUT_LIBRARY_TIME_INVALID";
5
+ export interface FinalCutLibraryInspectionIssue {
6
+ code: FinalCutLibraryInspectionIssueCode;
7
+ message: string;
8
+ path?: string;
9
+ retryable: boolean;
10
+ }
11
+ export type FinalCutLibraryInspectionField<T> = {
12
+ status: "available";
13
+ value: T;
14
+ } | {
15
+ status: "unavailable";
16
+ issue: FinalCutLibraryInspectionIssue;
17
+ };
18
+ export interface FinalCutLibraryInspectionSequence {
19
+ id: string;
20
+ name: string;
21
+ startTime: FinalCutLibraryInspectionField<RationalTime>;
22
+ duration: FinalCutLibraryInspectionField<RationalTime>;
23
+ frameDuration: FinalCutLibraryInspectionField<RationalTime>;
24
+ }
25
+ export interface FinalCutLibraryInspectionProject {
26
+ id: string;
27
+ name: string;
28
+ sequences: FinalCutLibraryInspectionSequence[];
29
+ }
30
+ export interface FinalCutLibraryInspectionEvent {
31
+ id: string;
32
+ name: string;
33
+ projects: FinalCutLibraryInspectionProject[];
34
+ }
35
+ export interface FinalCutLibraryInspectionLibrary {
36
+ id: string;
37
+ name: string;
38
+ path?: string;
39
+ events: FinalCutLibraryInspectionEvent[];
40
+ }
41
+ export interface FinalCutLibraryInspectionCatalog {
42
+ libraries: FinalCutLibraryInspectionLibrary[];
43
+ }
44
+ export interface FinalCutLibraryInspectionError {
45
+ code: FinalCutLibraryInspectionIssueCode;
46
+ message: string;
47
+ retryable: boolean;
48
+ }
49
+ export type FinalCutLibraryInspectionResult = {
50
+ status: "available";
51
+ catalog: FinalCutLibraryInspectionCatalog;
52
+ } | {
53
+ status: "partial";
54
+ catalog: FinalCutLibraryInspectionCatalog;
55
+ issues: FinalCutLibraryInspectionIssue[];
56
+ } | {
57
+ status: "unavailable";
58
+ error: FinalCutLibraryInspectionError;
59
+ } | {
60
+ status: "error";
61
+ error: FinalCutLibraryInspectionError;
62
+ };
63
+ export interface FinalCutLibraryInspectionProviderOptions {
64
+ executor?: (script: string, timeoutMs: number) => Promise<string>;
65
+ applicationIdentifier?: string;
66
+ }
67
+ /** Structured failure raised when project.list cannot use the background provider. */
68
+ export declare class FinalCutLibraryInspectionProviderError extends Error {
69
+ readonly failure: FinalCutLibraryInspectionError;
70
+ readonly code: FinalCutLibraryInspectionIssueCode;
71
+ readonly retryable: boolean;
72
+ constructor(failure: FinalCutLibraryInspectionError);
73
+ toJSON(): FinalCutLibraryInspectionError;
74
+ }
75
+ export declare function serializeFinalCutLibraryInspectionError(error: unknown): FinalCutLibraryInspectionError | undefined;
76
+ /** Read-only Final Cut library inspection through direct Apple Events. */
77
+ export declare class FinalCutLibraryInspectionProvider {
78
+ readonly backend: "final-cut-background-library";
79
+ private readonly executor;
80
+ private readonly applicationIdentifier;
81
+ constructor(options?: FinalCutLibraryInspectionProviderOptions);
82
+ inspect(): Promise<FinalCutLibraryInspectionResult>;
83
+ listProjects(): Promise<ProjectCatalog>;
84
+ /** Bind a newly imported project to the exact library location requested by its FCPXML. */
85
+ resolveProjectBinding(libraryPath: string, identity: {
86
+ projectName: string;
87
+ sequenceName: string;
88
+ }): Promise<{
89
+ projectId: string;
90
+ sequenceId: string;
91
+ libraryId: string;
92
+ eventId: string;
93
+ libraryPath: string;
94
+ }>;
95
+ }
96
+ /** Build the JXA program used for direct, read-only Final Cut Apple Events. */
97
+ export declare function buildFinalCutLibraryInspectionScript(applicationIdentifier?: string): string;
98
+ /** Parse the JSON envelope returned by the direct Final Cut Apple Event query. */
99
+ export declare function parseFinalCutLibraryInspectionResponse(input: string | unknown): FinalCutLibraryInspectionResult;
100
+ /** Flatten safely discoverable project identities for the existing project.list contract. */
101
+ export declare function toFinalCutProjectCatalog(catalog: FinalCutLibraryInspectionCatalog): ProjectCatalog;