@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,179 @@
1
+ import type { ContextRevision, RationalTime, RationalTimeRange } from "./primitives.js";
2
+ import type { ProjectSnapshot } from "./project.js";
3
+ import type { MediaContext } from "./media.js";
4
+ import type { TimelineDiff, TimelineChange, AssetChange } from "./diff.js";
5
+ import type { ProjectSelectionMode, RuntimeCapabilities } from "./capabilities.js";
6
+ /**
7
+ * State that Final Cut can expose live through its Workflow Extension host.
8
+ * This deliberately does not pretend to be a complete timeline snapshot.
9
+ */
10
+ export interface EditorLiveState {
11
+ project?: {
12
+ id: string;
13
+ name: string;
14
+ };
15
+ sequence?: {
16
+ id: string;
17
+ name: string;
18
+ startTime: RationalTime;
19
+ duration: RationalTime;
20
+ frameDuration: RationalTime;
21
+ };
22
+ playheadTime?: RationalTime;
23
+ sequenceTimeRange?: RationalTimeRange;
24
+ revision: ContextRevision;
25
+ }
26
+ export interface ProjectCatalogSource {
27
+ source: string;
28
+ backend: string;
29
+ guarantee: "observed" | "canonical-read";
30
+ }
31
+ export interface ProjectCatalogLiveSource {
32
+ source: string;
33
+ backend: string;
34
+ guarantee: "observed";
35
+ }
36
+ export type ProjectCatalogIdentityMatchMethod = "stable-id" | "name-only" | "ambiguous-name" | "unresolved";
37
+ export type ProjectCatalogIdentityDiagnosticCode = "stable-id-mismatch" | "ambiguous-name" | "identity-unresolved";
38
+ export interface ProjectCatalogIdentityDiagnostic {
39
+ scope: "project" | "sequence";
40
+ code: ProjectCatalogIdentityDiagnosticCode;
41
+ liveId?: string;
42
+ liveName?: string;
43
+ catalogId?: string;
44
+ candidateCatalogIds?: string[];
45
+ }
46
+ export interface ProjectCatalogIdentityMatch {
47
+ method: ProjectCatalogIdentityMatchMethod;
48
+ catalogId?: string;
49
+ liveId?: string;
50
+ candidateCatalogIds?: string[];
51
+ }
52
+ export type ProjectCatalogReconciliationBlockerCode = "target-selection-required";
53
+ export interface ProjectCatalogReconciliationBlocker {
54
+ code: ProjectCatalogReconciliationBlockerCode;
55
+ message: string;
56
+ }
57
+ export interface ProjectCatalogReconciliation {
58
+ status: "matched" | "unresolved" | "stale";
59
+ project: ProjectCatalogIdentityMatch;
60
+ sequence: ProjectCatalogIdentityMatch;
61
+ beforeRevision?: ContextRevision;
62
+ afterRevision?: ContextRevision;
63
+ diagnostics?: ProjectCatalogIdentityDiagnostic[];
64
+ blocker?: ProjectCatalogReconciliationBlocker;
65
+ reason?: string;
66
+ }
67
+ export interface ProjectCatalogSelectionCapability {
68
+ available: boolean;
69
+ mode: ProjectSelectionMode;
70
+ unavailableReason?: string;
71
+ }
72
+ export interface ProjectCatalogProvenance {
73
+ catalog: ProjectCatalogSource;
74
+ live?: ProjectCatalogLiveSource & {
75
+ state: EditorLiveState;
76
+ };
77
+ reconciliation: ProjectCatalogReconciliation;
78
+ selection: ProjectCatalogSelectionCapability;
79
+ }
80
+ /** Stable project and sequence identities exposed by an editor backend. */
81
+ export interface ProjectSequence {
82
+ id: string;
83
+ name: string;
84
+ }
85
+ export interface ProjectDescriptor {
86
+ id: string;
87
+ name: string;
88
+ sequences: ProjectSequence[];
89
+ }
90
+ export interface ProjectCatalog {
91
+ projects: ProjectDescriptor[];
92
+ activeProjectId?: string;
93
+ activeSequenceId?: string;
94
+ provenance?: ProjectCatalogProvenance;
95
+ }
96
+ export interface ProjectSelection {
97
+ projectId: string;
98
+ sequenceId?: string;
99
+ }
100
+ export interface TimelineChangesRequest {
101
+ target: ProjectSelection;
102
+ from: ContextRevision;
103
+ }
104
+ export type TimelineChangesStatus = "ready" | "stale" | "ambiguous" | "unavailable";
105
+ export interface TimelineChangesSource {
106
+ source: string;
107
+ backend: string;
108
+ guarantee: "canonical-read" | "metadata-only";
109
+ }
110
+ export interface TimelineChangesResult {
111
+ status: TimelineChangesStatus;
112
+ target: ProjectSelection;
113
+ source: TimelineChangesSource;
114
+ from: ContextRevision;
115
+ to?: ContextRevision;
116
+ changes: TimelineChange[];
117
+ timeline?: TimelineDiff;
118
+ reason?: string;
119
+ }
120
+ export interface ProjectSelectionResult extends ProjectCatalog {
121
+ requestedTarget: ProjectSelection;
122
+ observedActiveTarget: {
123
+ projectId: string;
124
+ sequenceId: string;
125
+ };
126
+ observedRevision: ContextRevision;
127
+ }
128
+ export declare function createProjectSelectionResult(catalog: ProjectCatalog, requestedTarget: ProjectSelection, observedRevision: ContextRevision): ProjectSelectionResult;
129
+ export type EditorChangeKind = "active-sequence-changed" | "playhead-changed" | "sequence-time-range-changed";
130
+ export interface EditorChange {
131
+ kind: EditorChangeKind;
132
+ revision: ContextRevision;
133
+ state: EditorLiveState;
134
+ }
135
+ export interface ContextChangeSet {
136
+ from: ContextRevision;
137
+ to: ContextRevision;
138
+ timeline?: TimelineDiff;
139
+ stateChanges: EditorChange[];
140
+ assetChanges: AssetChange[];
141
+ }
142
+ export type ContextSource = "canonical-timeline" | "live-metadata" | "fcpxml-artifact" | "deterministic-fixture";
143
+ export type ContextEvidenceTier = "deterministic" | "metadata-only" | "fcpxml-artifact" | "canonical-live" | "headed-native";
144
+ export interface ContextTarget {
145
+ projectId: string;
146
+ sequenceId: string;
147
+ }
148
+ export interface ContextCursor {
149
+ revision: ContextRevision;
150
+ target?: ContextTarget;
151
+ }
152
+ export interface ContextProvenance {
153
+ source: ContextSource;
154
+ provider: string;
155
+ evidenceTier: ContextEvidenceTier;
156
+ target?: ContextTarget;
157
+ }
158
+ export type ContextChangedScope = "project" | "sequence" | "timeline" | "playhead" | "assets" | "media";
159
+ export interface ContextDiff {
160
+ from: ContextRevision;
161
+ to: ContextRevision;
162
+ cursor: ContextCursor;
163
+ provenance: ContextProvenance[];
164
+ changedScopes: ContextChangedScope[];
165
+ timeline?: TimelineDiff;
166
+ stateChanges: EditorChange[];
167
+ assetChanges: AssetChange[];
168
+ }
169
+ export interface AgentContext {
170
+ revision: ContextRevision;
171
+ cursor: ContextCursor;
172
+ provenance: ContextProvenance;
173
+ changedScopes: ContextChangedScope[];
174
+ project?: ProjectSnapshot;
175
+ editorState?: EditorLiveState;
176
+ media: MediaContext[];
177
+ recentChanges: ContextDiff;
178
+ capabilities: RuntimeCapabilities;
179
+ }
@@ -0,0 +1,104 @@
1
+ import type { ContextRevision, RationalTime, TimeRange } from "./primitives.js";
2
+ import type { Clip, Marker, Caption, StoryElement } from "./project.js";
3
+ import type { MediaContext } from "./media.js";
4
+ import type { EditorAsset } from "./ports.js";
5
+ export interface TimelineDiffProvenance {
6
+ source: "project-snapshot";
7
+ projectId: string;
8
+ sequenceId: string;
9
+ fromRevision: ContextRevision;
10
+ toRevision: ContextRevision;
11
+ }
12
+ export interface ClipChange {
13
+ type: "ITEM_ADDED" | "ITEM_REMOVED" | "ITEM_MODIFIED";
14
+ itemId: string;
15
+ before?: Clip;
16
+ after?: Clip;
17
+ }
18
+ export type TimelineChange = {
19
+ scope: "clip";
20
+ type: ClipChange["type"];
21
+ itemId: string;
22
+ before?: Clip;
23
+ after?: Clip;
24
+ } | {
25
+ scope: "marker";
26
+ type: "MARKER_ADDED" | "MARKER_REMOVED" | "MARKER_MODIFIED";
27
+ itemId: string;
28
+ before?: Marker;
29
+ after?: Marker;
30
+ } | {
31
+ scope: "caption";
32
+ type: "CAPTION_ADDED" | "CAPTION_REMOVED" | "CAPTION_MODIFIED";
33
+ itemId: string;
34
+ before?: Caption;
35
+ after?: Caption;
36
+ } | {
37
+ scope: "story-element";
38
+ type: "STORY_ELEMENT_ADDED" | "STORY_ELEMENT_REMOVED" | "STORY_ELEMENT_MODIFIED";
39
+ itemId: string;
40
+ before?: StoryElement;
41
+ after?: StoryElement;
42
+ } | {
43
+ scope: "media";
44
+ type: "MEDIA_ADDED" | "MEDIA_REMOVED" | "MEDIA_MODIFIED";
45
+ itemId: string;
46
+ before?: MediaContext;
47
+ after?: MediaContext;
48
+ };
49
+ export interface MarkerChange {
50
+ type: "MARKER_ADDED" | "MARKER_REMOVED" | "MARKER_MODIFIED";
51
+ itemId: string;
52
+ marker: Marker;
53
+ before?: Marker;
54
+ after?: Marker;
55
+ }
56
+ export interface CaptionChange {
57
+ type: "CAPTION_ADDED" | "CAPTION_REMOVED" | "CAPTION_MODIFIED";
58
+ itemId: string;
59
+ caption: Caption;
60
+ before?: Caption;
61
+ after?: Caption;
62
+ }
63
+ export interface StoryElementChange {
64
+ type: "STORY_ELEMENT_ADDED" | "STORY_ELEMENT_REMOVED" | "STORY_ELEMENT_MODIFIED";
65
+ itemId: string;
66
+ element: StoryElement;
67
+ before?: StoryElement;
68
+ after?: StoryElement;
69
+ }
70
+ export interface MediaChange {
71
+ type: "MEDIA_ADDED" | "MEDIA_REMOVED" | "MEDIA_MODIFIED";
72
+ itemId: string;
73
+ media: MediaContext;
74
+ before?: MediaContext;
75
+ after?: MediaContext;
76
+ }
77
+ export interface PlayheadChange {
78
+ before?: RationalTime;
79
+ after?: RationalTime;
80
+ }
81
+ export interface TimelineDiff {
82
+ from: ContextRevision;
83
+ to: ContextRevision;
84
+ provenance: TimelineDiffProvenance;
85
+ added: ClipChange[];
86
+ removed: ClipChange[];
87
+ modified: ClipChange[];
88
+ durationDelta: number;
89
+ durationDeltaTime: RationalTime;
90
+ playheadChange?: PlayheadChange;
91
+ markerChanges: MarkerChange[];
92
+ captionChanges: CaptionChange[];
93
+ storyElementChanges: StoryElementChange[];
94
+ mediaChanges: MediaChange[];
95
+ /** All canonical changes in deterministic timeline order. */
96
+ changes: TimelineChange[];
97
+ affectedRanges: TimeRange[];
98
+ }
99
+ export interface AssetChange {
100
+ type: "ASSET_ADDED" | "ASSET_REMOVED" | "ASSET_MODIFIED";
101
+ assetId: string;
102
+ before?: EditorAsset;
103
+ after?: EditorAsset;
104
+ }
@@ -0,0 +1,63 @@
1
+ export type DurationConstraint = "hard" | "soft";
2
+ export type DurationPolicyAction = "deliver-exact-duration" | "deliver-shorter-strong-edit" | "reuse-selected-b-roll" | "request-additional-footage";
3
+ export type DurationAlternativeKind = "deliver-shorter-strong-edit" | "reuse-selected-b-roll" | "slow-motion" | "request-additional-footage" | "generated-interstitial";
4
+ export type DurationAlternativeStatus = "recommended" | "available" | "requires-confirmation" | "not-permitted";
5
+ export interface DurationRange {
6
+ startSeconds: number;
7
+ endSeconds: number;
8
+ }
9
+ export interface DurationPolicyFootage {
10
+ id: string;
11
+ durationSeconds: number;
12
+ usableDurationSeconds?: number;
13
+ usableRanges?: DurationRange[];
14
+ reusable?: boolean;
15
+ }
16
+ export interface DurationPolicyPermissions {
17
+ allowReuse?: boolean;
18
+ allowSlowMotion?: boolean;
19
+ allowGeneratedAssets?: boolean;
20
+ }
21
+ export interface DurationPolicyRequest {
22
+ requestedDurationSeconds: number;
23
+ footage: DurationPolicyFootage[];
24
+ constraint?: DurationConstraint;
25
+ permissions?: DurationPolicyPermissions;
26
+ actualDurationSeconds?: number;
27
+ }
28
+ export interface DurationRangeUse {
29
+ footageId: string;
30
+ sourceRange: DurationRange;
31
+ occurrence: number;
32
+ }
33
+ export interface DurationPolicyAlternative {
34
+ kind: DurationAlternativeKind;
35
+ status: DurationAlternativeStatus;
36
+ resultingDurationSeconds: number | null;
37
+ tradeoffs: string[];
38
+ confirmationRequired?: string;
39
+ reusedRanges?: DurationRangeUse[];
40
+ }
41
+ export interface DurationPolicyPlan {
42
+ policy: {
43
+ constraint: DurationConstraint;
44
+ constraintWasExplicit: boolean;
45
+ };
46
+ requestedDurationSeconds: number;
47
+ availableFootage: {
48
+ uniqueDurationSeconds: number;
49
+ reusableDurationSeconds: number;
50
+ };
51
+ achievableDurationSeconds: number;
52
+ actualDurationSeconds: number | null;
53
+ durationReport: {
54
+ requestedDurationSeconds: number;
55
+ achievableDurationSeconds: number;
56
+ actualDurationSeconds: number | null;
57
+ };
58
+ selectedAction: DurationPolicyAction;
59
+ reusedRanges: DurationRangeUse[];
60
+ unmetConstraints: string[];
61
+ confirmationRequired: string[];
62
+ alternatives: DurationPolicyAlternative[];
63
+ }
@@ -0,0 +1,227 @@
1
+ import type { ContextRevision, RationalTime, TimeRange } from "./primitives.js";
2
+ import type { Marker, PictureInPictureCrop, PictureInPictureFrame, PictureInPicturePosition, ProjectSnapshot } from "./project.js";
3
+ import type { TimelineDiff } from "./diff.js";
4
+ import type { VerificationPolicy, VerificationReport } from "./verification.js";
5
+ export interface ArtifactEditTarget {
6
+ kind: "artifact";
7
+ artifactId: string;
8
+ artifactPath: string;
9
+ }
10
+ export interface EditorTimelineEditTarget {
11
+ kind: "editor.timeline";
12
+ projectId: string;
13
+ sequenceId: string;
14
+ }
15
+ export type EditTarget = ArtifactEditTarget | EditorTimelineEditTarget;
16
+ export interface ArtifactEditTargetInput {
17
+ artifactPath: string;
18
+ }
19
+ export interface EditorTimelineEditTargetInput {
20
+ projectId: string;
21
+ sequenceId: string;
22
+ }
23
+ export type MaskMode = "rectangle" | "supplied-alpha" | "person-cutout";
24
+ export interface MaskBounds {
25
+ x: number;
26
+ y: number;
27
+ width: number;
28
+ height: number;
29
+ }
30
+ export interface MaskConfiguration {
31
+ mode: MaskMode;
32
+ bounds?: MaskBounds;
33
+ alphaMediaId?: string;
34
+ inverted?: boolean;
35
+ }
36
+ export interface AddMaskOperation {
37
+ type: "timeline.mask.add";
38
+ occurrenceId: string;
39
+ mask: MaskConfiguration;
40
+ }
41
+ export declare function assertValidMaskConfiguration(mask: MaskConfiguration): void;
42
+ export type EditOperation = {
43
+ type: "rename-clip";
44
+ clipId: string;
45
+ name: string;
46
+ baseRevision?: ContextRevision;
47
+ } | {
48
+ type: "trim-clip";
49
+ clipId: string;
50
+ duration: number;
51
+ durationTime?: RationalTime;
52
+ baseRevision?: ContextRevision;
53
+ } | {
54
+ type: "set-gain";
55
+ clipId: string;
56
+ gainDb: number;
57
+ baseRevision?: ContextRevision;
58
+ } | {
59
+ type: "reduce-noise";
60
+ clipId: string;
61
+ range: TimeRange;
62
+ reductionDb: number;
63
+ baseRevision?: ContextRevision;
64
+ } | {
65
+ type: "set-color-correction";
66
+ clipId: string;
67
+ correction: import("./project.js").ColorCorrection;
68
+ baseRevision?: ContextRevision;
69
+ } | {
70
+ type: "ripple-delete";
71
+ timelineId: string;
72
+ range: TimeRange;
73
+ reason?: string;
74
+ /** Optional Skill provenance for a guarded semantic deletion. */
75
+ candidateId?: string;
76
+ baseRevision?: ContextRevision;
77
+ } | {
78
+ type: "add-marker";
79
+ timelineId: string;
80
+ marker: Marker;
81
+ baseRevision?: ContextRevision;
82
+ };
83
+ export interface ImportMediaOperation {
84
+ type: "media.import";
85
+ mediaId: string;
86
+ source: string;
87
+ mediaKind: "video" | "audio";
88
+ duration: number;
89
+ sourceDigest: string;
90
+ }
91
+ export interface AddMediaOperation {
92
+ type: "timeline.media.add";
93
+ occurrenceId: string;
94
+ mediaId: string;
95
+ role: "video" | "music" | "audio";
96
+ start: number;
97
+ duration: number;
98
+ targetLane?: "primary" | number;
99
+ }
100
+ export interface AddPictureInPictureOperation {
101
+ type: "timeline.picture-in-picture.add";
102
+ occurrenceId: string;
103
+ mediaId: string;
104
+ /** Existing primary-storyline occurrence that owns the connected clip. */
105
+ attachedTo: string;
106
+ start: number;
107
+ duration: number;
108
+ /** Connected lane; zero and the primary storyline are not valid. */
109
+ targetLane: number;
110
+ position: PictureInPicturePosition;
111
+ scale: number;
112
+ crop?: PictureInPictureCrop;
113
+ frame?: PictureInPictureFrame;
114
+ }
115
+ export interface SetAudioFadesOperation {
116
+ type: "timeline.audio.fades";
117
+ clipId: string;
118
+ fadeIn: number;
119
+ fadeOut: number;
120
+ }
121
+ export interface MusicImportSource {
122
+ mediaId: string;
123
+ source: string;
124
+ duration: number;
125
+ sourceDigest: string;
126
+ }
127
+ export interface MusicAddRequest {
128
+ baseRevision: ContextRevision;
129
+ occurrenceId: string;
130
+ mediaId?: string;
131
+ import?: MusicImportSource;
132
+ placement: "append" | "insert";
133
+ start?: number;
134
+ duration?: number;
135
+ targetLane: number;
136
+ gainDb?: number;
137
+ fadeIn?: number;
138
+ fadeOut?: number;
139
+ ducking?: {
140
+ enabled: boolean;
141
+ dialogueClipIds?: string[];
142
+ reductionDb?: number;
143
+ };
144
+ verification?: VerificationPolicy;
145
+ }
146
+ export interface AddTitleOperation {
147
+ type: "timeline.title.add";
148
+ occurrenceId: string;
149
+ assetId: string;
150
+ text: string;
151
+ start: number;
152
+ duration: number;
153
+ targetLane: number;
154
+ }
155
+ export interface MoveMediaOperation {
156
+ type: "timeline.media.move";
157
+ occurrenceId: string;
158
+ start: number;
159
+ targetLane?: "primary" | number;
160
+ }
161
+ export interface ReplaceMediaOperation {
162
+ type: "timeline.media.replace";
163
+ occurrenceId: string;
164
+ mediaId: string;
165
+ duration?: number;
166
+ }
167
+ export interface RemoveMediaOperation {
168
+ type: "timeline.media.remove";
169
+ occurrenceId: string;
170
+ }
171
+ export interface AddTransitionOperation {
172
+ type: "timeline.transition.add";
173
+ transitionId: string;
174
+ assetId: string;
175
+ beforeClipId: string;
176
+ afterClipId: string;
177
+ duration: number;
178
+ }
179
+ export interface AttachAudioOperation {
180
+ type: "timeline.audio.attach";
181
+ occurrenceId: string;
182
+ targetClipId: string;
183
+ mediaId: string;
184
+ startOffset?: number;
185
+ duration?: number;
186
+ }
187
+ export interface MixAudioOperation {
188
+ type: "timeline.audio.mix";
189
+ clipId: string;
190
+ gainDb?: number;
191
+ fadeIn?: number;
192
+ fadeOut?: number;
193
+ }
194
+ export type WorkflowOperation = EditOperation | ImportMediaOperation | AddMediaOperation | AddPictureInPictureOperation | SetAudioFadesOperation | AddTitleOperation | MoveMediaOperation | ReplaceMediaOperation | RemoveMediaOperation | AddTransitionOperation | AttachAudioOperation | MixAudioOperation | AddMaskOperation;
195
+ export interface CompositeEditRequest {
196
+ baseRevision: ContextRevision;
197
+ operations: WorkflowOperation[];
198
+ verification?: VerificationPolicy;
199
+ }
200
+ export interface CompositeEditPreview {
201
+ previewToken: string;
202
+ target: EditTarget;
203
+ baseRevision: ContextRevision;
204
+ artifactDigest?: string;
205
+ operations: WorkflowOperation[];
206
+ expectedDiff: TimelineDiff;
207
+ warnings: string[];
208
+ expiresAt: string;
209
+ verification?: VerificationPolicy;
210
+ }
211
+ export interface EditTransaction {
212
+ id: string;
213
+ target?: EditTarget;
214
+ artifactDigest?: string;
215
+ operation?: EditOperation;
216
+ intent: string;
217
+ planned: WorkflowOperation[];
218
+ applied: WorkflowOperation[];
219
+ baseRevision: ContextRevision;
220
+ before: ProjectSnapshot;
221
+ after: ProjectSnapshot;
222
+ attemptedAfter: ProjectSnapshot;
223
+ diff: TimelineDiff;
224
+ verificationPolicy?: VerificationPolicy;
225
+ verification?: VerificationReport;
226
+ status: "APPLIED" | "VERIFIED" | "FAILED" | "ROLLED_BACK" | "ACCEPTED";
227
+ }
@@ -0,0 +1,67 @@
1
+ import type { ContextRevision } from "./primitives.js";
2
+ export declare const CANONICAL_INCREMENTAL_SYNC_CONTRACT_VERSION: 1;
3
+ export type CanonicalSyncEvidenceTier = "metadata-only" | "artifact-only" | "canonical-read" | "canonical-live" | "headed-native" | "fixture";
4
+ export type CanonicalSyncSurface = "live" | "artifact" | "fixture";
5
+ export interface CanonicalSyncTarget {
6
+ /** Stable provider identity; names are descriptive and never sufficient. */
7
+ projectId: string;
8
+ /** Stable provider identity for the selected sequence/timeline. */
9
+ sequenceId: string;
10
+ }
11
+ export interface CanonicalSyncCursor {
12
+ target: CanonicalSyncTarget;
13
+ revision: ContextRevision;
14
+ }
15
+ export interface CanonicalSyncSource {
16
+ provider: string;
17
+ backend: string;
18
+ surface: CanonicalSyncSurface;
19
+ evidenceTier: CanonicalSyncEvidenceTier;
20
+ }
21
+ export interface CanonicalSyncProvenance {
22
+ source: CanonicalSyncSource;
23
+ observedAt: string;
24
+ }
25
+ export type CanonicalChangeEntity = "clip" | "connected-item" | "marker" | "caption" | "role" | "audio" | "playhead";
26
+ export type CanonicalChangeOperation = "added" | "removed" | "modified";
27
+ export interface CanonicalSyncChange {
28
+ /** Contiguous zero-based order within one result. */
29
+ order: number;
30
+ revision: ContextRevision;
31
+ entity: CanonicalChangeEntity;
32
+ operation: CanonicalChangeOperation;
33
+ /** Stable identity of the changed entity; playhead uses the target timeline ID. */
34
+ entityId: string;
35
+ before?: unknown;
36
+ after?: unknown;
37
+ }
38
+ export interface CanonicalSyncSuccess {
39
+ contractVersion: typeof CANONICAL_INCREMENTAL_SYNC_CONTRACT_VERSION;
40
+ ok: true;
41
+ status: "complete";
42
+ target: CanonicalSyncTarget;
43
+ from: CanonicalSyncCursor;
44
+ to: CanonicalSyncCursor;
45
+ changes: CanonicalSyncChange[];
46
+ provenance: CanonicalSyncProvenance;
47
+ }
48
+ export type CanonicalSyncFailureStatus = "unavailable" | "stale" | "ambiguous";
49
+ export type CanonicalSyncFailureCode = "CAPABILITY_UNAVAILABLE" | "METADATA_ONLY" | "STALE_CURSOR" | "AMBIGUOUS_TARGET" | "TARGET_MISMATCH";
50
+ export interface CanonicalSyncFailure {
51
+ contractVersion: typeof CANONICAL_INCREMENTAL_SYNC_CONTRACT_VERSION;
52
+ ok: false;
53
+ status: CanonicalSyncFailureStatus;
54
+ target?: CanonicalSyncTarget;
55
+ cursor?: CanonicalSyncCursor;
56
+ provenance?: CanonicalSyncProvenance;
57
+ failure: {
58
+ code: CanonicalSyncFailureCode;
59
+ message: string;
60
+ };
61
+ }
62
+ export type CanonicalSyncResult = CanonicalSyncSuccess | CanonicalSyncFailure;
63
+ /**
64
+ * Validates the structural guarantees shared by timeline.changes and
65
+ * context.changes. Provider-specific payload validation belongs at the edge.
66
+ */
67
+ export declare function assertCanonicalSyncResult(result: CanonicalSyncResult): void;
@@ -0,0 +1,14 @@
1
+ export * from "./primitives.js";
2
+ export * from "./project.js";
3
+ export * from "./context.js";
4
+ export * from "./media.js";
5
+ export * from "./editing.js";
6
+ export * from "./diff.js";
7
+ export * from "./capabilities.js";
8
+ export * from "./ports.js";
9
+ export * from "./verification.js";
10
+ export * from "./timeline-target.js";
11
+ export * from "./rough-cut.js";
12
+ export * from "./duration.js";
13
+ export * from "./skills.js";
14
+ export * from "./incremental-sync.js";