@morshoto/framekit 0.1.18 → 0.2.3

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 (192) hide show
  1. package/README.md +17 -12
  2. package/dist-package/adapters/final-cut/typescript/src/analyzers.d.ts +58 -0
  3. package/dist-package/adapters/final-cut/typescript/src/analyzers.js +52 -13
  4. package/dist-package/adapters/final-cut/typescript/src/assets.d.ts +24 -0
  5. package/dist-package/adapters/final-cut/typescript/src/background-export.d.ts +98 -0
  6. package/dist-package/adapters/final-cut/typescript/src/background-materialization.d.ts +47 -0
  7. package/dist-package/adapters/final-cut/typescript/src/background-materialization.js +8 -2
  8. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery-guard.d.ts +32 -0
  9. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery-guard.js +275 -0
  10. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery.d.ts +22 -0
  11. package/dist-package/adapters/final-cut/typescript/src/canonical-verification.d.ts +11 -0
  12. package/dist-package/adapters/final-cut/typescript/src/canonical.d.ts +184 -0
  13. package/dist-package/adapters/final-cut/typescript/src/canonical.js +571 -78
  14. package/dist-package/adapters/final-cut/typescript/src/connection.d.ts +103 -0
  15. package/dist-package/adapters/final-cut/typescript/src/connection.js +6 -1
  16. package/dist-package/adapters/final-cut/typescript/src/disposable-native.d.ts +90 -0
  17. package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +6 -0
  18. package/dist-package/adapters/final-cut/typescript/src/documents.d.ts +3 -0
  19. package/dist-package/adapters/final-cut/typescript/src/documents.js +3 -0
  20. package/dist-package/adapters/final-cut/typescript/src/experimental.d.ts +8 -0
  21. package/dist-package/adapters/final-cut/typescript/src/experimental.js +8 -0
  22. package/dist-package/adapters/final-cut/typescript/src/export.d.ts +125 -0
  23. package/dist-package/adapters/final-cut/typescript/src/fcpxml-console-experiment.d.ts +54 -0
  24. package/dist-package/adapters/final-cut/typescript/src/fcpxml.d.ts +75 -0
  25. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +28 -9
  26. package/dist-package/adapters/final-cut/typescript/src/index.d.ts +22 -0
  27. package/dist-package/adapters/final-cut/typescript/src/index.js +1 -7
  28. package/dist-package/adapters/final-cut/typescript/src/library-inspection.d.ts +101 -0
  29. package/dist-package/adapters/final-cut/typescript/src/live.d.ts +101 -0
  30. package/dist-package/adapters/final-cut/typescript/src/live.js +35 -2
  31. package/dist-package/adapters/final-cut/typescript/src/media.d.ts +12 -0
  32. package/dist-package/adapters/final-cut/typescript/src/native-operation.d.ts +6 -0
  33. package/dist-package/adapters/final-cut/typescript/src/native-recovery-inspection.d.ts +77 -0
  34. package/dist-package/adapters/final-cut/typescript/src/native-recovery-inspection.js +175 -0
  35. package/dist-package/adapters/final-cut/typescript/src/native-session.d.ts +130 -0
  36. package/dist-package/adapters/final-cut/typescript/src/native-session.js +11 -6
  37. package/dist-package/adapters/final-cut/typescript/src/native.d.ts +828 -0
  38. package/dist-package/adapters/final-cut/typescript/src/native.js +475 -189
  39. package/dist-package/adapters/final-cut/typescript/src/pasteboard-snapshot.d.ts +114 -0
  40. package/dist-package/adapters/final-cut/typescript/src/publish-readback.d.ts +26 -0
  41. package/dist-package/adapters/final-cut/typescript/src/publish-readback.js +19 -2
  42. package/dist-package/adapters/final-cut/typescript/src/publisher.d.ts +215 -0
  43. package/dist-package/adapters/final-cut/typescript/src/publisher.js +255 -14
  44. package/dist-package/adapters/final-cut/typescript/src/session.d.ts +43 -0
  45. package/dist-package/adapters/final-cut/typescript/src/session.js +43 -13
  46. package/dist-package/adapters/final-cut/typescript/src/shadow-mutation.d.ts +51 -0
  47. package/dist-package/adapters/final-cut/typescript/src/sqlite-experiment.d.ts +156 -0
  48. package/dist-package/adapters/final-cut/typescript/src/sqlite-inspection.d.ts +134 -0
  49. package/dist-package/adapters/final-cut/typescript/src/sqlite-materialization.d.ts +110 -0
  50. package/dist-package/adapters/final-cut/typescript/src/sqlite-wal-observation.d.ts +132 -0
  51. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.d.ts +61 -0
  52. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +31 -5
  53. package/dist-package/adapters/final-cut/typescript/src/unattended-editing.d.ts +54 -0
  54. package/dist-package/adapters/headless/typescript/src/audio-output.d.ts +3 -0
  55. package/dist-package/adapters/headless/typescript/src/audio-output.js +3 -0
  56. package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.d.ts +11 -0
  57. package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.js +26 -2
  58. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.d.ts +25 -0
  59. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +37 -14
  60. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.d.ts +15 -0
  61. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +9 -4
  62. package/dist-package/adapters/headless/typescript/src/index.d.ts +3 -0
  63. package/dist-package/apps/cli/src/dev-doctor.d.ts +25 -0
  64. package/dist-package/apps/cli/src/dev-doctor.js +198 -0
  65. package/dist-package/apps/cli/src/headless-projects.d.ts +3 -0
  66. package/dist-package/apps/cli/src/headless-projects.js +5 -0
  67. package/dist-package/apps/cli/src/main.d.ts +10 -0
  68. package/dist-package/apps/cli/src/main.js +42 -0
  69. package/dist-package/apps/mcp-server/runtime/ffmpeg-audio-backend.py +129 -0
  70. package/dist-package/apps/mcp-server/runtime/speech-analyzer-wrapper.mjs +54 -0
  71. package/dist-package/apps/mcp-server/runtime/whisper-speech-backend.py +271 -0
  72. package/dist-package/apps/mcp-server/src/build-alignment.d.ts +10 -0
  73. package/dist-package/apps/mcp-server/src/build-identity.d.ts +7 -0
  74. package/dist-package/apps/mcp-server/src/build-identity.json +2 -2
  75. package/dist-package/apps/mcp-server/src/canonical-native-snapshot.d.ts +8 -0
  76. package/dist-package/apps/mcp-server/src/canonical-native-snapshot.js +18 -0
  77. package/dist-package/apps/mcp-server/src/final-cut-runtime-config.d.ts +5 -0
  78. package/dist-package/apps/mcp-server/src/final-cut-runtime-config.js +3 -0
  79. package/dist-package/apps/mcp-server/src/headless-project-snapshot.d.ts +3 -0
  80. package/dist-package/apps/mcp-server/src/headless-sessions.d.ts +89 -0
  81. package/dist-package/apps/mcp-server/src/main.d.ts +1 -0
  82. package/dist-package/apps/mcp-server/src/main.js +24 -19
  83. package/dist-package/apps/mcp-server/src/materialization-jobs.d.ts +204 -0
  84. package/dist-package/apps/mcp-server/src/materialization-jobs.js +143 -10
  85. package/dist-package/apps/mcp-server/src/readback-policy.d.ts +18 -0
  86. package/dist-package/apps/mcp-server/src/routing.d.ts +90 -0
  87. package/dist-package/apps/mcp-server/src/routing.js +2 -0
  88. package/dist-package/apps/mcp-server/src/server.d.ts +75 -0
  89. package/dist-package/apps/mcp-server/src/server.js +813 -158
  90. package/dist-package/apps/mcp-server/src/tools/skills/catalog.d.ts +19 -0
  91. package/dist-package/apps/mcp-server/src/tools/skills/catalog.js +142 -0
  92. package/dist-package/apps/mcp-server/src/tools/skills/metadata.d.ts +37 -0
  93. package/dist-package/apps/mcp-server/src/tools/skills/metadata.js +71 -0
  94. package/dist-package/apps/mcp-server/src/tools/skills/register.d.ts +11 -0
  95. package/dist-package/apps/mcp-server/src/tools/skills/register.js +101 -0
  96. package/dist-package/apps/mcp-server/src/version.d.ts +4 -0
  97. package/dist-package/packages/headless-application/src/external-edit.d.ts +30 -0
  98. package/dist-package/packages/headless-application/src/external-edit.js +72 -0
  99. package/dist-package/packages/headless-application/src/headless-projects.d.ts +233 -0
  100. package/dist-package/{apps/mcp-server → packages/headless-application}/src/headless-projects.js +392 -59
  101. package/dist-package/packages/headless-application/src/index.d.ts +2 -0
  102. package/dist-package/packages/headless-application/src/index.js +2 -0
  103. package/dist-package/packages/runtime/src/application/duration-policy-service.d.ts +4 -0
  104. package/dist-package/packages/runtime/src/application/local-media.d.ts +46 -0
  105. package/dist-package/packages/runtime/src/application/media-analysis-service.d.ts +40 -0
  106. package/dist-package/packages/runtime/src/application/media-analysis-service.js +105 -15
  107. package/dist-package/packages/runtime/src/application/project-service.d.ts +35 -0
  108. package/dist-package/packages/runtime/src/application/project-service.js +5 -1
  109. package/dist-package/packages/runtime/src/application/project-store.d.ts +56 -0
  110. package/dist-package/packages/runtime/src/application/project-store.js +13 -36
  111. package/dist-package/packages/runtime/src/application/project-transactions.d.ts +51 -0
  112. package/dist-package/packages/runtime/src/application/runtime-options.d.ts +15 -0
  113. package/dist-package/packages/runtime/src/application/semantic-media-index-store.d.ts +28 -0
  114. package/dist-package/packages/runtime/src/application/transaction-store.d.ts +10 -0
  115. package/dist-package/packages/runtime/src/application/transaction-store.js +1 -1
  116. package/dist-package/packages/runtime/src/audio/analysis.d.ts +3 -0
  117. package/dist-package/packages/runtime/src/audio/analysis.js +95 -0
  118. package/dist-package/packages/runtime/src/audio/dialogue-normalization.d.ts +47 -0
  119. package/dist-package/packages/runtime/src/audio/noise-reduction.d.ts +34 -0
  120. package/dist-package/packages/runtime/src/capabilities.d.ts +45 -0
  121. package/dist-package/packages/runtime/src/capabilities.js +1 -1
  122. package/dist-package/packages/runtime/src/color-correction.d.ts +33 -0
  123. package/dist-package/packages/runtime/src/context/context-engine.d.ts +28 -0
  124. package/dist-package/packages/runtime/src/context/context-engine.js +22 -16
  125. package/dist-package/packages/runtime/src/context/context-service.d.ts +20 -0
  126. package/dist-package/packages/runtime/src/context/context-service.js +2 -2
  127. package/dist-package/packages/runtime/src/context/project-catalog.d.ts +12 -0
  128. package/dist-package/packages/runtime/src/context/revision.d.ts +2 -0
  129. package/dist-package/packages/runtime/src/domain/capabilities.d.ts +170 -0
  130. package/dist-package/packages/runtime/src/domain/context.d.ts +179 -0
  131. package/dist-package/packages/runtime/src/domain/diff.d.ts +104 -0
  132. package/dist-package/packages/runtime/src/domain/duration.d.ts +63 -0
  133. package/dist-package/packages/runtime/src/domain/editing.d.ts +227 -0
  134. package/dist-package/packages/runtime/src/domain/incremental-sync.d.ts +67 -0
  135. package/dist-package/packages/runtime/src/domain/index.d.ts +14 -0
  136. package/dist-package/packages/runtime/src/domain/media.d.ts +406 -0
  137. package/dist-package/packages/runtime/src/domain/ports.d.ts +62 -0
  138. package/dist-package/packages/runtime/src/domain/primitives.d.ts +21 -0
  139. package/dist-package/packages/runtime/src/domain/project.d.ts +119 -0
  140. package/dist-package/packages/runtime/src/domain/rough-cut.d.ts +27 -0
  141. package/dist-package/packages/runtime/src/domain/skills.d.ts +145 -0
  142. package/dist-package/packages/runtime/src/domain/timeline-target.d.ts +57 -0
  143. package/dist-package/packages/runtime/src/domain/timeline-target.js +19 -1
  144. package/dist-package/packages/runtime/src/domain/types.d.ts +5 -0
  145. package/dist-package/packages/runtime/src/domain/verification.d.ts +92 -0
  146. package/dist-package/packages/runtime/src/editing/dialogue-normalization-service.d.ts +18 -0
  147. package/dist-package/packages/runtime/src/editing/duration-policy.d.ts +3 -0
  148. package/dist-package/packages/runtime/src/editing/edit-service.d.ts +44 -0
  149. package/dist-package/packages/runtime/src/editing/edit-service.js +76 -10
  150. package/dist-package/packages/runtime/src/editing/filler-removal-service.d.ts +23 -0
  151. package/dist-package/packages/runtime/src/editing/intent.d.ts +97 -0
  152. package/dist-package/packages/runtime/src/editing/music-service.d.ts +9 -0
  153. package/dist-package/packages/runtime/src/index.d.ts +32 -0
  154. package/dist-package/packages/runtime/src/index.js +2 -0
  155. package/dist-package/packages/runtime/src/planning/rough-cut.d.ts +3 -0
  156. package/dist-package/packages/runtime/src/render/render-and-verify.d.ts +71 -0
  157. package/dist-package/packages/runtime/src/render/render-contract.d.ts +96 -0
  158. package/dist-package/packages/runtime/src/runtime.d.ts +85 -0
  159. package/dist-package/packages/runtime/src/runtime.js +16 -7
  160. package/dist-package/packages/runtime/src/skills/builtin.d.ts +2 -0
  161. package/dist-package/packages/runtime/src/skills/index.d.ts +3 -0
  162. package/dist-package/packages/runtime/src/skills/registry.d.ts +10 -0
  163. package/dist-package/packages/runtime/src/skills/requirements.d.ts +38 -0
  164. package/dist-package/packages/runtime/src/skills/runtime.d.ts +38 -0
  165. package/dist-package/packages/runtime/src/speech/analysis.d.ts +18 -0
  166. package/dist-package/packages/runtime/src/speech/analysis.js +67 -0
  167. package/dist-package/packages/runtime/src/speech/filler-detector.d.ts +49 -0
  168. package/dist-package/packages/runtime/src/speech/filler-removal.d.ts +37 -0
  169. package/dist-package/packages/runtime/src/speech/mapping.d.ts +56 -0
  170. package/dist-package/packages/runtime/src/speech/mapping.js +27 -4
  171. package/dist-package/packages/runtime/src/speech/safe-cut-resolver.d.ts +52 -0
  172. package/dist-package/packages/runtime/src/timeline/drift-reconciliation.d.ts +42 -0
  173. package/dist-package/packages/runtime/src/timeline/editing-session.d.ts +271 -0
  174. package/dist-package/packages/runtime/src/timeline/editing-session.js +48 -2
  175. package/dist-package/packages/runtime/src/timeline/fast-observation.d.ts +77 -0
  176. package/dist-package/packages/runtime/src/timeline/rational-time.d.ts +11 -0
  177. package/dist-package/packages/runtime/src/timeline/reorder-preview.d.ts +32 -0
  178. package/dist-package/packages/runtime/src/timeline/reorder-preview.js +202 -0
  179. package/dist-package/packages/runtime/src/timeline/snapshot-diff.d.ts +3 -0
  180. package/dist-package/packages/runtime/src/timeline/snapshot-diff.js +1 -0
  181. package/dist-package/packages/runtime/src/timeline/snapshot-digest.d.ts +3 -0
  182. package/dist-package/packages/runtime/src/timeline/snapshot-digest.js +1 -1
  183. package/dist-package/packages/runtime/src/verification/verification.d.ts +6 -0
  184. package/dist-package/packages/testkit/src/fixture-analyzers.d.ts +37 -0
  185. package/dist-package/packages/testkit/src/in-memory-editor.d.ts +55 -0
  186. package/dist-package/packages/testkit/src/in-memory-editor.js +3 -3
  187. package/dist-package/packages/testkit/src/index.d.ts +4 -0
  188. package/dist-package/packages/testkit/src/index.js +1 -0
  189. package/dist-package/packages/testkit/src/sender-lifecycle-fixture.d.ts +47 -0
  190. package/dist-package/packages/testkit/src/sender-lifecycle-fixture.js +192 -0
  191. package/dist-package/packages/testkit/src/skill-fixtures.d.ts +3 -0
  192. package/package.json +41 -14
@@ -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;
@@ -0,0 +1,101 @@
1
+ import type { ContextRevision, EditOperation, EditorChange, EditorLiveState, EditorIdentity, RuntimeCapabilities, LiveEditorStatePort, ProjectCatalog, ProjectSnapshot, ProjectSelection, ProjectSelectionResult } from "../../../../packages/runtime/src/index.js";
2
+ export declare const FINAL_CUT_LIVE_PROTOCOL_VERSION = 1;
3
+ /** Shared deterministic endpoint used by both the Node client and Swift host. */
4
+ export declare const DEFAULT_FINAL_CUT_LIVE_SOCKET: string;
5
+ export type FinalCutLiveMethod = "capabilities" | "state" | "changes" | "projects" | "select-project" | "snapshot" | "apply" | "restore" | "deliver-fcpxml";
6
+ export interface FinalCutFcpxmlDeliveryRequest {
7
+ artifactPath: string;
8
+ targetLibraryLocation?: string;
9
+ activates: boolean;
10
+ }
11
+ export interface FinalCutFcpxmlDelivery {
12
+ status: "dispatched" | "user-interaction-required" | "failed";
13
+ route: "background-document-open";
14
+ attempted: boolean;
15
+ imported: boolean;
16
+ requestedActivates: boolean;
17
+ activation: "preserved" | "activated" | "unknown";
18
+ ui: "none" | "prompted" | "displayed" | "unknown";
19
+ target: {
20
+ requestedLibraryLocation?: string;
21
+ guarantee: "requested-unverified" | "unavailable";
22
+ };
23
+ error?: {
24
+ code: string;
25
+ message: string;
26
+ };
27
+ }
28
+ export interface FinalCutLiveRequest {
29
+ version: number;
30
+ id: string;
31
+ method: FinalCutLiveMethod;
32
+ afterSequence?: number;
33
+ waitMs?: number;
34
+ projectId?: string;
35
+ sequenceId?: string;
36
+ artifactPath?: string;
37
+ targetLibraryLocation?: string;
38
+ activates?: boolean;
39
+ operation?: EditOperation;
40
+ expectedRevision?: ContextRevision;
41
+ snapshot?: ProjectSnapshot;
42
+ }
43
+ export type FinalCutLiveResponse = {
44
+ version: number;
45
+ id: string;
46
+ ok: true;
47
+ result: {
48
+ identity: EditorIdentity;
49
+ capabilities: RuntimeCapabilities;
50
+ state?: EditorLiveState;
51
+ changes?: EditorChange[];
52
+ catalog?: ProjectCatalog;
53
+ snapshot?: ProjectSnapshot;
54
+ revision?: ContextRevision;
55
+ delivery?: FinalCutFcpxmlDelivery;
56
+ };
57
+ } | {
58
+ version: number;
59
+ id: string;
60
+ ok: false;
61
+ error: {
62
+ code: string;
63
+ message: string;
64
+ };
65
+ };
66
+ export interface FinalCutLiveTransport {
67
+ request(request: FinalCutLiveRequest): Promise<FinalCutLiveResponse>;
68
+ }
69
+ export interface FinalCutLiveInspection {
70
+ identity: EditorIdentity;
71
+ capabilities: RuntimeCapabilities;
72
+ }
73
+ /** Newline-delimited JSON transport for the local Workflow Extension socket. */
74
+ export declare class UnixSocketFinalCutLiveTransport implements FinalCutLiveTransport {
75
+ private readonly socketPath;
76
+ private readonly timeoutMs;
77
+ constructor(socketPath: string, timeoutMs?: number);
78
+ request(request: FinalCutLiveRequest): Promise<FinalCutLiveResponse>;
79
+ private requestOnce;
80
+ }
81
+ export declare class FinalCutLiveAdapter implements LiveEditorStatePort {
82
+ private readonly transport;
83
+ private readonly socketPath;
84
+ private selectedTarget?;
85
+ constructor(transport: FinalCutLiveTransport, socketPath?: string);
86
+ inspect(): Promise<FinalCutLiveInspection>;
87
+ getIdentity(): Promise<EditorIdentity>;
88
+ getCapabilities(): Promise<RuntimeCapabilities>;
89
+ read(): Promise<ProjectSnapshot>;
90
+ readProject(): Promise<ProjectSnapshot>;
91
+ apply(operation: EditOperation, expectedRevision: ContextRevision): Promise<ContextRevision>;
92
+ restore(snapshot: ProjectSnapshot, expectedRevision: ContextRevision): Promise<void>;
93
+ readLiveState(): Promise<EditorLiveState>;
94
+ liveChangesSince(revision: ContextRevision, waitMs?: number): Promise<EditorChange[]>;
95
+ deliverFcpxml(request: FinalCutFcpxmlDeliveryRequest): Promise<FinalCutFcpxmlDelivery>;
96
+ listProjects(): Promise<ProjectCatalog>;
97
+ selectProject(selection: ProjectSelection): Promise<ProjectSelectionResult>;
98
+ private assertSelectedTargetActive;
99
+ private request;
100
+ }
101
+ export declare function createFinalCutLiveAdapter(socketPath?: string): FinalCutLiveAdapter;
@@ -13,6 +13,8 @@ const READ_ONLY_LIVE_METHODS = new Set([
13
13
  "projects",
14
14
  "snapshot",
15
15
  ]);
16
+ // The extension waits up to five seconds for NSWorkspace's completion handler.
17
+ const DOCUMENT_DELIVERY_TIMEOUT_MS = 7_000;
16
18
  /** Newline-delimited JSON transport for the local Workflow Extension socket. */
17
19
  export class UnixSocketFinalCutLiveTransport {
18
20
  socketPath;
@@ -52,7 +54,7 @@ export class UnixSocketFinalCutLiveTransport {
52
54
  };
53
55
  const timer = setTimeout(() => {
54
56
  finish(() => reject(new Error(`FINAL_CUT_LIVE_TIMEOUT: ${this.socketPath}`)));
55
- }, this.timeoutMs);
57
+ }, request.method === "deliver-fcpxml" ? Math.max(this.timeoutMs, DOCUMENT_DELIVERY_TIMEOUT_MS) : this.timeoutMs);
56
58
  socket = createConnection(this.socketPath);
57
59
  socket.setEncoding("utf8");
58
60
  socket.on("connect", () => {
@@ -90,6 +92,7 @@ export class UnixSocketFinalCutLiveTransport {
90
92
  export class FinalCutLiveAdapter {
91
93
  transport;
92
94
  socketPath;
95
+ selectedTarget;
93
96
  constructor(transport, socketPath = "configured-socket") {
94
97
  this.transport = transport;
95
98
  this.socketPath = socketPath;
@@ -125,6 +128,11 @@ export class FinalCutLiveAdapter {
125
128
  throw new Error("FINAL_CUT_LIVE_PROTOCOL: snapshot response was empty");
126
129
  validateCanonicalSnapshot(response.snapshot);
127
130
  validateSnapshotTarget(response.snapshot, await this.listProjects());
131
+ if (this.selectedTarget
132
+ && (response.snapshot.projectId !== this.selectedTarget.projectId
133
+ || response.snapshot.timeline.id !== this.selectedTarget.sequenceId)) {
134
+ throw new Error("TARGET_MISMATCH: live canonical snapshot differs from the explicitly selected project and sequence");
135
+ }
128
136
  return response.snapshot;
129
137
  }
130
138
  async apply(operation, expectedRevision) {
@@ -133,6 +141,7 @@ export class FinalCutLiveAdapter {
133
141
  if (capabilities.editor.canonicalTimelineMode !== "canonical-write") {
134
142
  throw new Error("CAPABILITY_UNAVAILABLE: live Final Cut canonical mutation");
135
143
  }
144
+ await this.assertSelectedTargetActive();
136
145
  const response = await this.request({ method: "apply", operation, expectedRevision });
137
146
  if (!response.revision)
138
147
  throw new Error("FINAL_CUT_LIVE_PROTOCOL: apply response revision was empty");
@@ -148,6 +157,10 @@ export class FinalCutLiveAdapter {
148
157
  if (capabilities.editor.canonicalTimelineMode !== "canonical-write") {
149
158
  throw new Error("CAPABILITY_UNAVAILABLE: live Final Cut canonical rollback");
150
159
  }
160
+ await this.assertSelectedTargetActive();
161
+ if (this.selectedTarget && (snapshot.projectId !== this.selectedTarget.projectId || snapshot.timeline.id !== this.selectedTarget.sequenceId)) {
162
+ throw new Error("TARGET_MISMATCH: rollback snapshot differs from the explicitly selected project and sequence");
163
+ }
151
164
  await this.request({ method: "restore", snapshot, expectedRevision });
152
165
  }
153
166
  async readLiveState() {
@@ -204,7 +217,19 @@ export class FinalCutLiveAdapter {
204
217
  if (!response.revision)
205
218
  throw new Error("FINAL_CUT_LIVE_PROTOCOL: project selection response revision was empty");
206
219
  validateRevision(response.revision, "project selection response revision");
207
- return createProjectSelectionResult(response.catalog, selection, response.revision);
220
+ const result = createProjectSelectionResult(response.catalog, selection, response.revision);
221
+ this.selectedTarget = { ...result.observedActiveTarget };
222
+ return result;
223
+ }
224
+ async assertSelectedTargetActive() {
225
+ const selected = this.selectedTarget;
226
+ if (!selected)
227
+ return;
228
+ const catalog = await this.listProjects();
229
+ if (this.selectedTarget !== selected
230
+ || catalog.activeProjectId !== selected.projectId || catalog.activeSequenceId !== selected.sequenceId) {
231
+ throw new Error("TARGET_MISMATCH: active project and sequence differ from the explicitly selected target");
232
+ }
208
233
  }
209
234
  async request(input) {
210
235
  const response = await this.transport.request({
@@ -262,6 +287,14 @@ function validateCanonicalSnapshot(snapshot) {
262
287
  requireNonEmpty(media.source, `media ${media.mediaId} source`);
263
288
  if (media.duration !== undefined)
264
289
  requireFiniteNonNegative(media.duration, `media ${media.mediaId} duration`);
290
+ if (media.sourceRange !== undefined) {
291
+ requireRecord(media.sourceRange, `media ${media.mediaId} source range`);
292
+ requireRational(media.sourceRange.start, `media ${media.mediaId} source range start`);
293
+ requireRational(media.sourceRange.duration, `media ${media.mediaId} source range duration`);
294
+ if (BigInt(media.sourceRange.duration.value) <= 0n) {
295
+ protocolError(`media ${media.mediaId} source range duration must be positive`);
296
+ }
297
+ }
265
298
  }
266
299
  const mediaIds = uniqueIds(snapshot.media, ({ mediaId }) => mediaId, "media");
267
300
  uniqueIds(snapshot.timeline.markers, ({ id }) => id, "marker");
@@ -0,0 +1,12 @@
1
+ import type { MediaContext, MediaSearchQuery } from "../../../../packages/runtime/src/index.js";
2
+ export interface FinalCutMediaRegistryOptions {
3
+ roots?: string[];
4
+ }
5
+ /** Read-only local media discovery that never contacts or activates Final Cut. */
6
+ export declare class FinalCutMediaRegistry {
7
+ private readonly roots;
8
+ private cached?;
9
+ constructor(options?: FinalCutMediaRegistryOptions);
10
+ listMedia(query?: MediaSearchQuery): Promise<MediaContext[]>;
11
+ refresh(): void;
12
+ }
@@ -0,0 +1,6 @@
1
+ export interface NativeOperationLease {
2
+ acquire(): void;
3
+ release(): void;
4
+ }
5
+ /** Coordinates one shared native-operation suspension across nested adapters. */
6
+ export declare function createNativeOperationLease(suspend?: () => void, resume?: () => void): NativeOperationLease;
@@ -0,0 +1,77 @@
1
+ /** Requested evidence only: none of these fields establishes dispatch or quiescence. */
2
+ export interface NativeMaterializationRecoveryContext {
3
+ kind: "materialization";
4
+ jobId: string;
5
+ dispatchId: string;
6
+ requestedTarget: {
7
+ libraryUid: string;
8
+ eventUid: string;
9
+ projectUid: string;
10
+ sequenceUid: string;
11
+ };
12
+ artifactDigest: string;
13
+ desiredDigest: string;
14
+ destination?: {
15
+ mode: "versioned";
16
+ projectUid: string;
17
+ sequenceUid: string;
18
+ projectName: string;
19
+ sequenceName: string;
20
+ };
21
+ executorIdentity: null;
22
+ nativeQuiescence: "unproven";
23
+ }
24
+ /** Requested library only; it is not a verified native target. */
25
+ export interface NativePublishRecoveryContext {
26
+ kind: "publish";
27
+ jobId: string;
28
+ dispatchId: string;
29
+ requestedTarget: {
30
+ libraryPath: string;
31
+ };
32
+ artifactDigest: string;
33
+ executorIdentity: null;
34
+ nativeQuiescence: "unproven";
35
+ }
36
+ /** A planned receiver identity and target, not proof that dispatch or completion occurred. */
37
+ export type RecoverableNativeContext = (Omit<NativeMaterializationRecoveryContext, "executorIdentity"> | Omit<NativePublishRecoveryContext, "executorIdentity">) & {
38
+ executorIdentity: string;
39
+ dispatchState: "intent";
40
+ canonicalTarget: Record<string, string>;
41
+ expectedCanonicalDigest: string;
42
+ expectedRestoreDigest?: string;
43
+ };
44
+ export type NativeRecoveryContext = NativeMaterializationRecoveryContext | NativePublishRecoveryContext | RecoverableNativeContext;
45
+ export declare function validRecoveryContext(value: unknown, operation: string): value is NativeMaterializationRecoveryContext | NativePublishRecoveryContext;
46
+ /** Observational evidence, never an authorization to recover or dispatch. */
47
+ export interface NativeRecoveryInspection {
48
+ status: "clear" | "recovery-required" | "unknown";
49
+ nativeQuiescence: "unproven";
50
+ recoveryEligibility: "unavailable";
51
+ sender: {
52
+ status: "untracked" | "active-or-interrupted" | "sender-settled" | "unknown";
53
+ };
54
+ reservation?: {
55
+ version: 2 | 3 | 4;
56
+ reservationId: string;
57
+ operation: string;
58
+ jobId?: string;
59
+ dispatchId?: string;
60
+ jobCorrelation?: "unverified";
61
+ };
62
+ dispatchState?: "possibly-dispatched";
63
+ boundaryEvidence?: "dispatch-possible-recorded" | "unknown";
64
+ missingEvidence?: ["receiver-terminal-quiescence", "independent-target-outcome", "legacy-writer-exclusion"];
65
+ safeNextActions?: ["inspect", "retain-reservation"];
66
+ intent?: {
67
+ requestedTarget: NativeRecoveryContext["requestedTarget"];
68
+ artifactDigest: string;
69
+ desiredDigest?: string;
70
+ destination?: NativeMaterializationRecoveryContext["destination"];
71
+ };
72
+ }
73
+ /**
74
+ * Read-only, point-in-time observation; old writers do not share a lock, so even
75
+ * repeated reads cannot exclude concurrent changes or establish quiescence.
76
+ */
77
+ export declare function inspectNativeRecoveryReadOnly(path: string): Promise<NativeRecoveryInspection>;
@@ -0,0 +1,175 @@
1
+ import { createHash } from "node:crypto";
2
+ import { constants } from "node:fs";
3
+ import { lstat, open } from "node:fs/promises";
4
+ import { isAbsolute, join } from "node:path";
5
+ function validPublishContext(value, operation) {
6
+ if (!value || typeof value !== "object" || Array.isArray(value))
7
+ return false;
8
+ const c = value;
9
+ const path = c.requestedTarget?.libraryPath;
10
+ return c.kind === "publish"
11
+ && typeof c.jobId === "string" && /^publish-job-[a-z0-9-]{1,80}$/.test(c.jobId)
12
+ && operation === `native.publish.${createHash("sha256").update(c.jobId).digest("hex")}`
13
+ && typeof c.dispatchId === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(c.dispatchId)
14
+ && typeof path === "string" && path.length <= 4096 && isAbsolute(path) && path.endsWith(".fcpbundle")
15
+ && typeof c.artifactDigest === "string" && /^[a-f0-9]{64}$/.test(c.artifactDigest)
16
+ && c.executorIdentity === null && c.nativeQuiescence === "unproven";
17
+ }
18
+ export function validRecoveryContext(value, operation) {
19
+ return validMaterializationContext(value, operation) || validPublishContext(value, operation);
20
+ }
21
+ function validRecoverableContext(value, operation) {
22
+ if (!value || typeof value !== "object" || Array.isArray(value))
23
+ return false;
24
+ const c = value;
25
+ if (typeof c.executorIdentity !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/.test(c.executorIdentity)
26
+ || c.dispatchState !== "intent" || !/^[a-f0-9]{64}$/.test(c.expectedCanonicalDigest)
27
+ || (c.expectedRestoreDigest !== undefined && !/^[a-f0-9]{64}$/.test(c.expectedRestoreDigest))
28
+ || !validRecoveryContext({ ...c, executorIdentity: null }, operation))
29
+ return false;
30
+ const t = c.canonicalTarget;
31
+ if (!t || typeof t !== "object" || Array.isArray(t))
32
+ return false;
33
+ const keys = c.kind === "publish" ? ["libraryPath", "projectUid", "sequenceUid"] : ["libraryUid", "eventUid", "projectUid", "sequenceUid"];
34
+ if (Object.keys(t).length !== keys.length || !keys.every((key) => typeof t[key] === "string" && t[key].trim().length > 0 && t[key].length <= 1024))
35
+ return false;
36
+ if (c.kind === "publish")
37
+ return t.libraryPath === c.requestedTarget.libraryPath;
38
+ return keys.every((key) => t[key] === c.requestedTarget[key])
39
+ && c.expectedCanonicalDigest === c.desiredDigest;
40
+ }
41
+ function validMaterializationContext(value, operation) {
42
+ if (!value || typeof value !== "object" || Array.isArray(value))
43
+ return false;
44
+ const c = value;
45
+ const t = c.requestedTarget;
46
+ return c.kind === "materialization"
47
+ && typeof c.jobId === "string" && /^materialization-[a-z0-9-]{1,80}$/.test(c.jobId)
48
+ && operation === `native.materialize.${createHash("sha256").update(c.jobId).digest("hex")}`
49
+ && typeof c.dispatchId === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(c.dispatchId)
50
+ && Boolean(t && [t.libraryUid, t.eventUid, t.projectUid, t.sequenceUid].every((x) => typeof x === "string" && x.trim().length > 0 && x.length <= 1024))
51
+ && typeof c.artifactDigest === "string" && /^[a-f0-9]{64}$/.test(c.artifactDigest)
52
+ && typeof c.desiredDigest === "string" && /^[a-f0-9]{64}$/.test(c.desiredDigest)
53
+ && (c.destination === undefined || (c.destination.mode === "versioned" &&
54
+ [c.destination.projectUid, c.destination.sequenceUid, c.destination.projectName, c.destination.sequenceName]
55
+ .every((x) => typeof x === "string" && x.trim().length > 0 && x.length <= 1024)))
56
+ && c.executorIdentity === null && c.nativeQuiescence === "unproven";
57
+ }
58
+ const unknown = () => ({ status: "unknown", nativeQuiescence: "unproven", recoveryEligibility: "unavailable", sender: { status: "unknown" } });
59
+ const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
60
+ /** Read a bounded regular file, refusing symlinks, replacement and in-place changes. */
61
+ async function readStable(path) {
62
+ let handle;
63
+ try {
64
+ handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
65
+ const before = await handle.stat();
66
+ if (!before.isFile() || before.size > 16_384)
67
+ throw new Error("invalid evidence file");
68
+ const data = await handle.readFile();
69
+ const after = await handle.stat();
70
+ const current = await lstat(path);
71
+ if (!current.isFile() || before.dev !== current.dev || before.ino !== current.ino || before.size !== after.size
72
+ || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs || data.length !== after.size)
73
+ throw new Error("evidence changed");
74
+ return data.toString("utf8");
75
+ }
76
+ catch (error) {
77
+ if (error.code === "ENOENT")
78
+ return undefined;
79
+ throw error;
80
+ }
81
+ finally {
82
+ await handle?.close();
83
+ }
84
+ }
85
+ async function exists(path) {
86
+ try {
87
+ await lstat(path);
88
+ return true;
89
+ }
90
+ catch (error) {
91
+ if (error.code === "ENOENT")
92
+ return false;
93
+ throw error;
94
+ }
95
+ }
96
+ async function readSettlement(path, id) {
97
+ const directory = `${path}.sender-settled`;
98
+ try {
99
+ const info = await lstat(directory);
100
+ if (!info.isDirectory() || info.isSymbolicLink())
101
+ throw new Error("invalid sender directory");
102
+ return await readStable(join(directory, id));
103
+ }
104
+ catch (error) {
105
+ if (error.code === "ENOENT")
106
+ return undefined;
107
+ throw error;
108
+ }
109
+ }
110
+ function markerMatches(raw, reservationId) {
111
+ try {
112
+ const value = JSON.parse(raw);
113
+ return value !== null && value.reservationId === reservationId && typeof value.owner === "string" && uuid.test(value.owner);
114
+ }
115
+ catch {
116
+ return false;
117
+ }
118
+ }
119
+ /**
120
+ * Read-only, point-in-time observation; old writers do not share a lock, so even
121
+ * repeated reads cannot exclude concurrent changes or establish quiescence.
122
+ */
123
+ export async function inspectNativeRecoveryReadOnly(path) {
124
+ try {
125
+ if (await exists(`${path}.lock`))
126
+ return unknown();
127
+ const contents = await readStable(path);
128
+ const active = await readStable(`${path}.active`);
129
+ if (contents === undefined) {
130
+ if (active !== undefined || await exists(`${path}.lock`) || await readStable(path) !== undefined || await readStable(`${path}.active`) !== undefined)
131
+ return unknown();
132
+ return { status: "clear", nativeQuiescence: "unproven", recoveryEligibility: "unavailable", sender: { status: "unknown" } };
133
+ }
134
+ const record = JSON.parse(contents);
135
+ if (!record || typeof record !== "object" || Array.isArray(record) || ![2, 3, 4].includes(record.version)
136
+ || record.kind !== "native-operation" || typeof record.owner !== "string" || !uuid.test(record.owner)
137
+ || typeof record.operation !== "string" || !/^[a-z][a-z0-9.-]{0,127}$/.test(record.operation))
138
+ return unknown();
139
+ if (record.version === 3 && !validRecoveryContext(record.recoveryContext, record.operation))
140
+ return unknown();
141
+ if (record.version === 4 && !validRecoverableContext(record.recoveryContext, record.operation))
142
+ return unknown();
143
+ if (record.senderTracked !== undefined && typeof record.senderTracked !== "boolean")
144
+ return unknown();
145
+ const reservationId = createHash("sha256").update(contents).digest("hex");
146
+ const boundary = await readStable(`${path}.dispatch-${reservationId}`);
147
+ let boundaryEvidence = "unknown";
148
+ if (boundary !== undefined) {
149
+ try {
150
+ const marker = JSON.parse(boundary);
151
+ if (marker.version === 1 && marker.reservationId === reservationId && marker.owner === record.owner)
152
+ boundaryEvidence = "dispatch-possible-recorded";
153
+ }
154
+ catch { /* A damaged marker provides no proof. */ }
155
+ }
156
+ const settled = await readSettlement(path, reservationId);
157
+ const sender = record.senderTracked !== true ? (active !== undefined || settled !== undefined ? "unknown" : "untracked")
158
+ : active !== undefined ? (settled === undefined && markerMatches(active, reservationId) ? "active-or-interrupted" : "unknown")
159
+ : settled !== undefined && markerMatches(settled, reservationId) ? "sender-settled" : "unknown";
160
+ if (await exists(`${path}.lock`) || await readStable(path) !== contents || await readStable(`${path}.active`) !== active
161
+ || await readSettlement(path, reservationId) !== settled || await readStable(`${path}.dispatch-${reservationId}`) !== boundary)
162
+ return unknown();
163
+ const context = record.version === 3 || record.version === 4 ? record.recoveryContext : undefined;
164
+ return { status: "recovery-required", nativeQuiescence: "unproven", recoveryEligibility: "unavailable", sender: { status: sender },
165
+ dispatchState: "possibly-dispatched", boundaryEvidence, missingEvidence: ["receiver-terminal-quiescence", "independent-target-outcome", "legacy-writer-exclusion"],
166
+ safeNextActions: ["inspect", "retain-reservation"],
167
+ ...(context ? { intent: { requestedTarget: context.requestedTarget, artifactDigest: context.artifactDigest,
168
+ ...(context.kind === "materialization" ? { desiredDigest: context.desiredDigest, ...(context.destination ? { destination: context.destination } : {}) } : {}) } } : {}),
169
+ reservation: { version: record.version, reservationId, operation: record.operation,
170
+ ...(context ? { jobId: context.jobId, dispatchId: context.dispatchId, jobCorrelation: "unverified" } : {}) } };
171
+ }
172
+ catch {
173
+ return unknown();
174
+ }
175
+ }