@morshoto/framekit 0.1.0 → 0.1.5

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 (65) hide show
  1. package/README.md +42 -17
  2. package/dist-package/adapters/final-cut/typescript/src/analyzers.js +86 -2
  3. package/dist-package/adapters/final-cut/typescript/src/connection.js +5 -1
  4. package/dist-package/adapters/final-cut/typescript/src/export.js +231 -8
  5. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +70 -9
  6. package/dist-package/adapters/final-cut/typescript/src/live.js +2 -2
  7. package/dist-package/adapters/final-cut/typescript/src/native.js +1000 -100
  8. package/dist-package/adapters/final-cut/typescript/src/publisher.js +242 -30
  9. package/dist-package/adapters/final-cut/typescript/src/session.js +86 -9
  10. package/dist-package/apps/mcp-server/src/main.js +10 -1
  11. package/dist-package/apps/mcp-server/src/routing.js +172 -0
  12. package/dist-package/apps/mcp-server/src/server.js +867 -52
  13. package/dist-package/apps/mcp-server/src/version.js +34 -0
  14. package/dist-package/packages/runtime/src/application/duration-policy-service.js +6 -0
  15. package/dist-package/packages/runtime/src/application/media-analysis-service.js +473 -0
  16. package/dist-package/packages/runtime/src/application/project-service.js +146 -0
  17. package/dist-package/packages/runtime/src/application/runtime-options.js +1 -0
  18. package/dist-package/packages/runtime/src/application/transaction-store.js +12 -0
  19. package/dist-package/packages/runtime/src/audio/dialogue-normalization.js +64 -0
  20. package/dist-package/packages/runtime/src/audio/noise-reduction.js +46 -0
  21. package/dist-package/packages/runtime/src/capabilities.js +187 -1
  22. package/dist-package/packages/runtime/src/color-correction.js +48 -0
  23. package/dist-package/packages/runtime/src/context/context-engine.js +20 -6
  24. package/dist-package/packages/runtime/src/context/context-service.js +30 -0
  25. package/dist-package/packages/runtime/src/context/revision.js +3 -0
  26. package/dist-package/packages/runtime/src/domain/capabilities.js +1 -0
  27. package/dist-package/packages/runtime/src/domain/context.js +1 -0
  28. package/dist-package/packages/runtime/src/domain/diff.js +1 -0
  29. package/dist-package/packages/runtime/src/domain/duration.js +1 -0
  30. package/dist-package/packages/runtime/src/domain/editing.js +1 -0
  31. package/dist-package/packages/runtime/src/domain/index.js +12 -0
  32. package/dist-package/packages/runtime/src/domain/media.js +8 -0
  33. package/dist-package/packages/runtime/src/domain/ports.js +1 -0
  34. package/dist-package/packages/runtime/src/domain/primitives.js +1 -0
  35. package/dist-package/packages/runtime/src/domain/project.js +1 -0
  36. package/dist-package/packages/runtime/src/domain/rough-cut.js +69 -0
  37. package/dist-package/packages/runtime/src/domain/skills.js +33 -0
  38. package/dist-package/packages/runtime/src/domain/types.js +5 -1
  39. package/dist-package/packages/runtime/src/domain/verification.js +1 -0
  40. package/dist-package/packages/runtime/src/editing/dialogue-normalization-service.js +141 -0
  41. package/dist-package/packages/runtime/src/editing/duration-policy.js +187 -0
  42. package/dist-package/packages/runtime/src/editing/edit-service.js +449 -0
  43. package/dist-package/packages/runtime/src/editing/filler-removal-service.js +361 -0
  44. package/dist-package/packages/runtime/src/editing/music-service.js +85 -0
  45. package/dist-package/packages/runtime/src/index.js +14 -3
  46. package/dist-package/packages/runtime/src/planning/rough-cut.js +71 -0
  47. package/dist-package/packages/runtime/src/runtime.js +131 -826
  48. package/dist-package/packages/runtime/src/skills/builtin.js +339 -0
  49. package/dist-package/packages/runtime/src/skills/index.js +3 -0
  50. package/dist-package/packages/runtime/src/skills/registry.js +74 -0
  51. package/dist-package/packages/runtime/src/skills/requirements.js +170 -0
  52. package/dist-package/packages/runtime/src/skills/runtime.js +239 -0
  53. package/dist-package/packages/runtime/src/speech/analysis.js +301 -0
  54. package/dist-package/packages/runtime/src/speech/filler-detector.js +132 -0
  55. package/dist-package/packages/runtime/src/speech/mapping.js +227 -0
  56. package/dist-package/packages/runtime/src/speech/safe-cut-resolver.js +314 -0
  57. package/dist-package/packages/runtime/src/timeline/rational-time.js +63 -0
  58. package/dist-package/packages/runtime/src/verification/verification.js +712 -1
  59. package/dist-package/packages/testkit/src/fixture-analyzers.js +28 -0
  60. package/dist-package/packages/testkit/src/in-memory-editor.js +287 -3
  61. package/dist-package/packages/testkit/src/index.js +1 -0
  62. package/dist-package/packages/testkit/src/skill-fixtures.js +64 -0
  63. package/package.json +17 -8
  64. /package/dist-package/packages/runtime/src/{diff/diff.js → timeline/snapshot-diff.js} +0 -0
  65. /package/dist-package/packages/runtime/src/{snapshot-digest.js → timeline/snapshot-digest.js} +0 -0
@@ -0,0 +1,64 @@
1
+ /** Plan a bounded clip-level gain change without mutating an editor. */
2
+ export function planDialogueGain(measurement, options) {
3
+ validateOptions(options);
4
+ const currentLufs = finiteOrZero(measurement.integratedLufs);
5
+ const desiredGainDb = roundDb(options.targetLufs - currentLufs);
6
+ const clampedGainDb = clamp(desiredGainDb, options.minGainDb, options.maxGainDb);
7
+ const estimatedPeakDb = roundDb(finiteOrZero(measurement.truePeakDb) + clampedGainDb);
8
+ const base = {
9
+ ...structuredClone(options),
10
+ currentLufs,
11
+ desiredGainDb,
12
+ clampedGainDb,
13
+ estimatedPeakDb,
14
+ };
15
+ if (!measurement.valid || !Number.isFinite(measurement.integratedLufs)
16
+ || !Number.isFinite(measurement.truePeakDb) || !Number.isFinite(measurement.silenceMs)
17
+ || !Number.isFinite(measurement.analyzedDurationSeconds)) {
18
+ return { ...base, decision: "SKIP", reasonCodes: ["MEASUREMENT_INVALID"] };
19
+ }
20
+ if (!measurement.dialoguePresent) {
21
+ return { ...base, decision: "SKIP", reasonCodes: ["NO_DIALOGUE"] };
22
+ }
23
+ if (measurement.silenceMs >= measurement.analyzedDurationSeconds * 1000) {
24
+ return { ...base, decision: "SKIP", reasonCodes: ["SILENCE"] };
25
+ }
26
+ if (measurement.analyzedDurationSeconds < options.minDialogueDurationSeconds) {
27
+ return { ...base, decision: "SKIP", reasonCodes: ["DIALOGUE_TOO_SHORT"] };
28
+ }
29
+ if (Math.abs(measurement.integratedLufs - options.targetLufs) <= options.toleranceDb) {
30
+ return {
31
+ ...base,
32
+ decision: "NO_OP",
33
+ desiredGainDb: 0,
34
+ clampedGainDb: 0,
35
+ estimatedPeakDb: measurement.truePeakDb,
36
+ reasonCodes: ["ALREADY_IN_TOLERANCE"],
37
+ };
38
+ }
39
+ if (desiredGainDb < options.minGainDb || desiredGainDb > options.maxGainDb) {
40
+ return { ...base, decision: "SKIP", reasonCodes: ["GAIN_OUT_OF_BOUNDS"] };
41
+ }
42
+ if (estimatedPeakDb > options.maxTruePeakDb) {
43
+ return { ...base, decision: "SKIP", reasonCodes: ["PEAK_RISK"] };
44
+ }
45
+ return { ...base, decision: "APPLY", reasonCodes: ["APPLY_GAIN"] };
46
+ }
47
+ function validateOptions(options) {
48
+ if (!Number.isFinite(options.targetLufs) || !Number.isFinite(options.toleranceDb) || options.toleranceDb < 0
49
+ || !Number.isFinite(options.maxTruePeakDb)
50
+ || !Number.isFinite(options.minGainDb) || !Number.isFinite(options.maxGainDb)
51
+ || options.minGainDb > options.maxGainDb
52
+ || !Number.isFinite(options.minDialogueDurationSeconds) || options.minDialogueDurationSeconds < 0) {
53
+ throw new Error("INVALID_OPERATION: dialogue gain policy is invalid");
54
+ }
55
+ }
56
+ function finiteOrZero(value) {
57
+ return Number.isFinite(value) ? value : 0;
58
+ }
59
+ function clamp(value, minimum, maximum) {
60
+ return Math.min(Math.max(value, minimum), maximum);
61
+ }
62
+ function roundDb(value) {
63
+ return Number(value.toFixed(6));
64
+ }
@@ -0,0 +1,46 @@
1
+ export function planNoiseReduction(measurement, options) {
2
+ validateOptions(options);
3
+ const recommendedReductionDb = finiteOrZero(measurement.recommendedReductionDb);
4
+ const reductionDb = Math.min(Math.max(recommendedReductionDb, 0), options.maxReductionDb);
5
+ const base = {
6
+ ...structuredClone(options),
7
+ noiseFloorDb: measurement.noiseFloorDb,
8
+ recommendedReductionDb,
9
+ reductionDb,
10
+ affectedRanges: clampRanges(measurement.affectedRanges, measurement.requestedRange),
11
+ };
12
+ if (measurement.valid !== true || !Number.isFinite(measurement.noiseFloorDb)) {
13
+ return { ...base, decision: "SKIP", reasonCodes: ["MEASUREMENT_INVALID"] };
14
+ }
15
+ if (measurement.noiseFloorDb <= options.noiseThresholdDb) {
16
+ return { ...base, decision: "NO_OP", reductionDb: 0, reasonCodes: ["ALREADY_BELOW_THRESHOLD"] };
17
+ }
18
+ if (measurement.confidence < options.minConfidence) {
19
+ return { ...base, decision: "SKIP", reasonCodes: ["CONFIDENCE_TOO_LOW"] };
20
+ }
21
+ if (base.affectedRanges.length === 0) {
22
+ return { ...base, decision: "SKIP", reasonCodes: ["NO_AFFECTED_RANGE"] };
23
+ }
24
+ if (!Number.isFinite(recommendedReductionDb) || recommendedReductionDb <= 0 || reductionDb <= 0) {
25
+ return { ...base, decision: "SKIP", reasonCodes: ["REDUCTION_INVALID"] };
26
+ }
27
+ return { ...base, decision: "APPLY", reasonCodes: ["APPLY_NOISE_REDUCTION"] };
28
+ }
29
+ function validateOptions(options) {
30
+ if (!Number.isFinite(options.noiseThresholdDb)
31
+ || !Number.isFinite(options.maxReductionDb) || options.maxReductionDb <= 0
32
+ || !Number.isFinite(options.minConfidence) || options.minConfidence < 0 || options.minConfidence > 1) {
33
+ throw new Error("INVALID_OPERATION: noise reduction policy is invalid");
34
+ }
35
+ }
36
+ function clampRanges(ranges, bounds) {
37
+ return ranges
38
+ .map((range) => ({
39
+ start: Math.max(bounds.start, range.start),
40
+ end: Math.min(bounds.end, range.end),
41
+ }))
42
+ .filter((range) => Number.isFinite(range.start) && Number.isFinite(range.end) && range.end > range.start);
43
+ }
44
+ function finiteOrZero(value) {
45
+ return Number.isFinite(value) ? value : 0;
46
+ }
@@ -1,3 +1,4 @@
1
+ import { CAPABILITY_SCHEMA_VERSION } from "./domain/capabilities.js";
1
2
  export function canonicalTimelineMode(capabilities) {
2
3
  const editor = capabilities.editor;
3
4
  const hasExplicitTargeting = Boolean(editor.projectCatalogRead && editor.projectSelection);
@@ -14,11 +15,196 @@ export function canonicalTimelineMode(capabilities) {
14
15
  return "metadata-only";
15
16
  }
16
17
  export function withCanonicalTimelineMode(capabilities) {
17
- return {
18
+ const normalized = {
18
19
  ...capabilities,
19
20
  editor: {
20
21
  ...capabilities.editor,
21
22
  canonicalTimelineMode: canonicalTimelineMode(capabilities),
22
23
  },
23
24
  };
25
+ const previous = capabilities.families;
26
+ if (!previous)
27
+ return normalized;
28
+ const canonicalRead = normalized.editor.canonicalTimelineMode === "canonical-read"
29
+ || normalized.editor.canonicalTimelineMode === "canonical-write";
30
+ const canonicalWrite = normalized.editor.canonicalTimelineMode === "canonical-write";
31
+ const compositeTransactions = Boolean(normalized.editor.compositeTransactions
32
+ && normalized.editor.timelineSnapshotRead
33
+ && normalized.editor.readAfterWrite
34
+ && normalized.editor.rollback
35
+ && (normalized.editor.timelineArtifactWrite || canonicalWrite));
36
+ return withCapabilityFamilies(normalized, {
37
+ backend: previous.connection.status.backend,
38
+ nativeBackend: previous.native.selectionWrite.backend,
39
+ publishingBackend: previous.publishing.projectCreation.backend,
40
+ exportBackend: previous.export.timeline.backend,
41
+ analyzerBackends: {
42
+ speechTranscribe: previous.analyzers.speechTranscribe.backend,
43
+ speechVad: previous.analyzers.speechVad.backend,
44
+ audioLoudness: previous.analyzers.audioLoudness.backend,
45
+ audioNoise: previous.analyzers.audioNoise?.backend,
46
+ visualTrack: previous.analyzers.visualTrack.backend,
47
+ },
48
+ connection: previous.connection.status,
49
+ canonicalDocument: {
50
+ read: refreshDescriptor(canonicalRead, previous.canonicalDocument.read, "canonical-read", "canonical timeline reads are unavailable"),
51
+ write: refreshDescriptor(canonicalWrite, previous.canonicalDocument.write, "canonical-write", "canonical timeline writes are unavailable"),
52
+ artifactWrite: refreshDescriptor(normalized.editor.timelineArtifactWrite, previous.canonicalDocument.artifactWrite, "artifact-write", "canonical artifact writes are unavailable"),
53
+ },
54
+ editing: {
55
+ compositeTransactions: refreshDescriptor(compositeTransactions, previous.editing.compositeTransactions, "verified", "composite editing transactions are unavailable"),
56
+ titlePlacement: refreshDescriptor(Boolean(normalized.editor.titlePlacement), previous.editing.titlePlacement, "verified", "title placement is unavailable"),
57
+ pictureInPicture: previous.editing.pictureInPicture,
58
+ masking: previous.editing.masking,
59
+ },
60
+ native: nativeAvailability(previous.native),
61
+ publishing: previous.publishing.projectCreation,
62
+ export: previous.export.timeline,
63
+ });
64
+ }
65
+ function refreshDescriptor(available, previous, guarantee, unavailableReason) {
66
+ if (available && previous.available)
67
+ return previous;
68
+ return descriptorFrom(available, previous.backend, guarantee, unavailableReason);
69
+ }
70
+ /**
71
+ * Adds the versioned operation-level contract while retaining the legacy
72
+ * boolean fields used by existing runtime consumers.
73
+ */
74
+ export function withCapabilityFamilies(capabilities, options = {}) {
75
+ const previous = capabilities.families;
76
+ const backend = options.backend ?? previous?.connection.status.backend ?? "unknown";
77
+ const normalized = {
78
+ ...capabilities,
79
+ schemaVersion: CAPABILITY_SCHEMA_VERSION,
80
+ editor: {
81
+ ...capabilities.editor,
82
+ canonicalTimelineMode: canonicalTimelineMode(capabilities),
83
+ },
84
+ };
85
+ const editor = normalized.editor;
86
+ const analyzerBackend = (operation) => options.analyzerBackends?.[operation]
87
+ ?? options.analyzerBackend
88
+ ?? previous?.analyzers[operation]?.backend
89
+ ?? backend;
90
+ const native = {
91
+ ...nativeAvailability(previous?.native),
92
+ ...options.native,
93
+ };
94
+ const canonicalDocument = {
95
+ ...previous?.canonicalDocument,
96
+ ...options.canonicalDocument,
97
+ };
98
+ const editing = {
99
+ ...previous?.editing,
100
+ ...options.editing,
101
+ };
102
+ const families = {
103
+ connection: {
104
+ status: descriptorFrom(options.connection ?? previous?.connection.status ?? true, options.connectionBackend ?? backend, "observed", "editor connection is unavailable"),
105
+ },
106
+ observation: {
107
+ timeline: descriptorFrom(editor.timelineSnapshotRead || editor.liveStateRead, backend, editor.timelineSnapshotRead ? "canonical-read" : "observed", "timeline observation is unavailable"),
108
+ media: descriptorFrom(editor.timelineSnapshotRead && editor.projectRead, backend, "canonical-read", "media observation is unavailable"),
109
+ },
110
+ canonicalDocument: {
111
+ read: descriptorFrom(canonicalDocument.read ?? (editor.canonicalTimelineMode === "canonical-read"
112
+ || editor.canonicalTimelineMode === "canonical-write"), backend, "canonical-read", "canonical timeline reads are unavailable"),
113
+ write: descriptorFrom(canonicalDocument.write ?? (editor.canonicalTimelineMode === "canonical-write"), backend, "canonical-write", "canonical timeline writes are unavailable"),
114
+ artifactWrite: descriptorFrom(canonicalDocument.artifactWrite ?? editor.timelineArtifactWrite, backend, "artifact-write", "canonical artifact writes are unavailable"),
115
+ },
116
+ editing: editingFamily(editor, editing, options.editingBackend ?? previous?.editing?.compositeTransactions.backend ?? backend),
117
+ native: nativeFamily(native, options.nativeBackend ?? previous?.native.selectionWrite.backend ?? backend),
118
+ publishing: {
119
+ projectCreation: descriptorFrom(options.publishing ?? previous?.publishing.projectCreation ?? false, options.publishingBackend ?? backend, "verified", "new project publishing is unavailable"),
120
+ },
121
+ export: {
122
+ timeline: descriptorFrom(options.export ?? previous?.export.timeline ?? false, options.exportBackend ?? backend, "verified", "timeline export is unavailable"),
123
+ },
124
+ analyzers: {
125
+ speechTranscribe: analyzerDescriptor(capabilities.analyzers.speechTranscribe, analyzerBackend("speechTranscribe"), "speech transcription"),
126
+ speechVad: analyzerDescriptor(capabilities.analyzers.speechVad, analyzerBackend("speechVad"), "speech VAD"),
127
+ audioLoudness: analyzerDescriptor(capabilities.analyzers.audioLoudness, analyzerBackend("audioLoudness"), "audio loudness analysis"),
128
+ audioNoise: analyzerDescriptor(Boolean(capabilities.analyzers.audioNoise), analyzerBackend("audioNoise"), "audio noise analysis"),
129
+ visualTrack: analyzerDescriptor(capabilities.analyzers.visualTrack, analyzerBackend("visualTrack"), "visual analysis"),
130
+ },
131
+ };
132
+ return { ...normalized, families };
133
+ }
134
+ function editingFamily(editor, overrides, backend) {
135
+ return {
136
+ compositeTransactions: descriptorFrom(overrides.compositeTransactions ?? Boolean(editor.compositeTransactions), backend, "verified", "composite editing transactions are unavailable"),
137
+ titlePlacement: descriptorFrom(overrides.titlePlacement ?? Boolean(editor.titlePlacement), backend, "verified", "title placement is unavailable"),
138
+ pictureInPicture: descriptorFrom(overrides.pictureInPicture ?? false, backend, "verified", "picture-in-picture editing is unavailable"),
139
+ masking: descriptorFrom(overrides.masking ?? false, backend, "verified", "masking is unavailable"),
140
+ };
141
+ }
142
+ export function createCapabilityPreflight(identity, capabilities, options = {}) {
143
+ const normalized = capabilities.families
144
+ ? capabilities
145
+ : withCapabilityFamilies(capabilities, { backend: identity.backend });
146
+ const editor = normalized.editor;
147
+ const documentMode = identity.backend === "fixture"
148
+ ? "fixture"
149
+ : editor.timelineArtifactWrite && !editor.timelineWrite
150
+ ? "fcpxml-artifact"
151
+ : editor.canonicalTimelineMode === "metadata-only"
152
+ ? "metadata-only"
153
+ : "canonical-live";
154
+ const processMode = options.processMode ?? "headless";
155
+ const mode = options.nativeWrite && processMode === "headed"
156
+ ? "native-write"
157
+ : documentMode;
158
+ return {
159
+ mode,
160
+ documentMode,
161
+ processMode,
162
+ backend: identity.backend,
163
+ capabilities: normalized.families,
164
+ };
165
+ }
166
+ function descriptorFrom(value, backend, guarantee, unavailableReason) {
167
+ if (typeof value !== "boolean")
168
+ return value;
169
+ return value
170
+ ? { available: true, backend, guarantee }
171
+ : { available: false, backend, guarantee: "none", unavailableReason };
172
+ }
173
+ function analyzerDescriptor(available, backend, operation) {
174
+ return descriptorFrom(available, backend, "verified", `${operation} is unavailable`);
175
+ }
176
+ function nativeFamily(native, backend) {
177
+ const nativeOperations = [
178
+ "selectionWrite",
179
+ "undo",
180
+ "mediaLibrarySearch",
181
+ "mediaImport",
182
+ "mediaSelection",
183
+ "mediaAppendSelected",
184
+ "timelineOccurrenceLocate",
185
+ "bladeAtPlayhead",
186
+ "deleteRange",
187
+ "trimToDuration",
188
+ "mediaAppend",
189
+ "mediaInsert",
190
+ "titlePlacement",
191
+ "timelineFocus",
192
+ "projectCreation",
193
+ "clipInsertion",
194
+ "clipMovement",
195
+ "transitionDiscovery",
196
+ "transitionPlacement",
197
+ ];
198
+ return Object.fromEntries(nativeOperations.map((operation) => [
199
+ operation,
200
+ descriptorFrom(Boolean(native[operation]), backend, "native-verified", `native ${nativeOperationLabel(operation)} is unavailable`),
201
+ ]));
202
+ }
203
+ function nativeOperationLabel(operation) {
204
+ return operation.replace(/[A-Z]/g, (character) => ` ${character.toLowerCase()}`);
205
+ }
206
+ function nativeAvailability(native) {
207
+ if (!native)
208
+ return {};
209
+ return Object.fromEntries(Object.entries(native).map(([operation, capability]) => [operation, capability.available]));
24
210
  }
@@ -0,0 +1,48 @@
1
+ export const COLOR_CORRECTION_PRESETS = {
2
+ neutral: { exposure: 0, contrast: 0, saturation: 0, temperature: 0, tint: 0, preset: "neutral" },
3
+ warm: { exposure: 0.1, contrast: 0, saturation: 0.1, temperature: 15, tint: 0, preset: "warm" },
4
+ cool: { exposure: 0.1, contrast: 0, saturation: 0, temperature: -15, tint: 0, preset: "cool" },
5
+ "high-contrast": { exposure: 0, contrast: 0.25, saturation: 0.05, temperature: 0, tint: 0, preset: "high-contrast" },
6
+ };
7
+ export function planColorCorrection(clip, request) {
8
+ const before = normalizeCorrection(clip.colorCorrection);
9
+ const preset = request.preset ? COLOR_CORRECTION_PRESETS[request.preset] : before;
10
+ const after = {
11
+ exposure: request.exposure ?? preset.exposure,
12
+ contrast: request.contrast ?? preset.contrast,
13
+ saturation: request.saturation ?? preset.saturation,
14
+ temperature: request.temperature ?? preset.temperature,
15
+ tint: request.tint ?? preset.tint,
16
+ ...(request.preset ? { preset: request.preset } : clip.colorCorrection?.preset ? { preset: clip.colorCorrection.preset } : {}),
17
+ };
18
+ validateCorrection(after);
19
+ const changedFields = Object.keys(after)
20
+ .filter((field) => after[field] !== before[field]);
21
+ return {
22
+ decision: changedFields.length > 0 ? "APPLY" : "NO_OP",
23
+ clipId: clip.id,
24
+ before,
25
+ after,
26
+ changedFields,
27
+ reasonCodes: changedFields.length > 0 ? ["APPLY_COLOR_CORRECTION"] : ["ALREADY_MATCHES"],
28
+ };
29
+ }
30
+ export function normalizeCorrection(correction) {
31
+ return {
32
+ exposure: correction?.exposure ?? 0,
33
+ contrast: correction?.contrast ?? 0,
34
+ saturation: correction?.saturation ?? 0,
35
+ temperature: correction?.temperature ?? 0,
36
+ tint: correction?.tint ?? 0,
37
+ ...(correction?.preset ? { preset: correction.preset } : {}),
38
+ };
39
+ }
40
+ function validateCorrection(correction) {
41
+ if (!Number.isFinite(correction.exposure) || correction.exposure < -4 || correction.exposure > 4
42
+ || !Number.isFinite(correction.contrast) || correction.contrast < -1 || correction.contrast > 1
43
+ || !Number.isFinite(correction.saturation) || correction.saturation < -1 || correction.saturation > 1
44
+ || !Number.isFinite(correction.temperature) || correction.temperature < -100 || correction.temperature > 100
45
+ || !Number.isFinite(correction.tint) || correction.tint < -100 || correction.tint > 100) {
46
+ throw new Error("INVALID_OPERATION: color correction values are outside the supported basic range");
47
+ }
48
+ }
@@ -1,4 +1,6 @@
1
- import { diffSnapshots } from "../diff/diff.js";
1
+ import { diffSnapshots } from "../timeline/snapshot-diff.js";
2
+ import { sameMediaSourceIdentity } from "../domain/media.js";
3
+ import { sameRevision } from "./revision.js";
2
4
  export class ContextEngine {
3
5
  editor;
4
6
  snapshots = new Map();
@@ -109,19 +111,31 @@ export class ContextEngine {
109
111
  const next = structuredClone(snapshot);
110
112
  next.media = next.media.map((media) => {
111
113
  const understanding = this.mediaUnderstanding.get(media.mediaId);
112
- if (!understanding || understanding.source !== media.source)
114
+ if (!understanding)
113
115
  return media;
116
+ if (!isCurrentUnderstanding(understanding, media, snapshot.revision)) {
117
+ this.mediaUnderstanding.delete(media.mediaId);
118
+ return media;
119
+ }
120
+ const attached = structuredClone(understanding);
114
121
  return {
115
122
  ...media,
116
- speech: understanding.speech,
117
- audio: understanding.audio,
118
- visual: understanding.visual,
119
- analysisRevision: understanding.analysisRevision.id,
123
+ metadata: attached.metadata,
124
+ speech: attached.speech,
125
+ audio: attached.audio,
126
+ visual: attached.visual,
127
+ semantic: attached.semantic,
128
+ analysis: attached.analysis,
129
+ analysisRevision: attached.analysisRevision.id,
120
130
  };
121
131
  });
122
132
  return next;
123
133
  }
124
134
  }
135
+ function isCurrentUnderstanding(understanding, media, revision) {
136
+ return sameMediaSourceIdentity(understanding.sourceIdentity, media)
137
+ && sameRevision(understanding.analysisRevision, revision);
138
+ }
125
139
  function isOptionalLiveUnavailable(error) {
126
140
  const message = String(error);
127
141
  return message.includes("FINAL_CUT_LIVE_UNAVAILABLE") || message.includes("CAPABILITY_UNAVAILABLE: live Final Cut editor state");
@@ -0,0 +1,30 @@
1
+ export class ContextService {
2
+ adapter;
3
+ context;
4
+ constructor(adapter, context) {
5
+ this.adapter = adapter;
6
+ this.context = context;
7
+ }
8
+ async inspectContext(capabilities) {
9
+ return this.context.inspectContext(capabilities);
10
+ }
11
+ async inspectLiveEditor() {
12
+ return this.liveAdapter().readLiveState();
13
+ }
14
+ async liveChangesSince(revision, waitMs = 0) {
15
+ return this.liveAdapter().liveChangesSince(revision, waitMs);
16
+ }
17
+ async changesSince(revision) {
18
+ return this.context.changesSince(revision);
19
+ }
20
+ async contextChangesSince(revision, waitMs = 0) {
21
+ return this.context.contextChangesSince(revision, waitMs);
22
+ }
23
+ liveAdapter() {
24
+ const candidate = this.adapter;
25
+ if (typeof candidate.readLiveState !== "function" || typeof candidate.liveChangesSince !== "function") {
26
+ throw new Error("CAPABILITY_UNAVAILABLE: live Framekit editor state");
27
+ }
28
+ return candidate;
29
+ }
30
+ }
@@ -0,0 +1,3 @@
1
+ export function sameRevision(left, right) {
2
+ return left.id === right.id && left.sequence === right.sequence;
3
+ }
@@ -0,0 +1 @@
1
+ export const CAPABILITY_SCHEMA_VERSION = 1;
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,12 @@
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 "./rough-cut.js";
11
+ export * from "./duration.js";
12
+ export * from "./skills.js";
@@ -0,0 +1,8 @@
1
+ export const SPEECH_ANALYSIS_SCHEMA_VERSION = 1;
2
+ export function sameMediaSourceIdentity(left, right) {
3
+ return left.mediaId === right.mediaId
4
+ && left.source === right.source
5
+ && left.sourceDigest === right.sourceDigest
6
+ && left.mediaKind === right.mediaKind
7
+ && left.duration === right.duration;
8
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,69 @@
1
+ /** Build a deterministic primary-storyline workflow without mutating a project. */
2
+ export function planRoughCutConstruction(snapshot, request) {
3
+ assertRevision(snapshot.revision, request.baseRevision);
4
+ if (request.shots.length === 0)
5
+ throw new Error("INVALID_ROUGH_CUT: at least one shot is required");
6
+ const imports = request.imports ?? [];
7
+ const knownMedia = new Map(snapshot.media.map((media) => [media.mediaId, media]));
8
+ const importedIds = new Set();
9
+ for (const media of imports) {
10
+ if (importedIds.has(media.mediaId) || knownMedia.has(media.mediaId)) {
11
+ throw new Error(`MEDIA_ALREADY_EXISTS: ${media.mediaId}`);
12
+ }
13
+ if (!media.mediaId.trim() || !media.source.trim() || !media.sourceDigest.trim()
14
+ || !Number.isFinite(media.duration) || media.duration <= 0) {
15
+ throw new Error("INVALID_OPERATION: imported media requires mediaId, source, duration, and digest");
16
+ }
17
+ if (media.mediaKind !== "video") {
18
+ throw new Error(`ROUGH_CUT_VIDEO_REQUIRED: ${media.mediaId}`);
19
+ }
20
+ importedIds.add(media.mediaId);
21
+ knownMedia.set(media.mediaId, media);
22
+ }
23
+ const occurrenceIds = new Set(snapshot.timeline.clips.map((clip) => clip.id));
24
+ const operations = imports.map((media) => ({ ...media }));
25
+ let start = snapshot.timeline.duration;
26
+ for (const shot of request.shots) {
27
+ if (!shot.occurrenceId.trim() || !shot.mediaId.trim()) {
28
+ throw new Error("INVALID_ROUGH_CUT: shot occurrenceId and mediaId are required");
29
+ }
30
+ if (occurrenceIds.has(shot.occurrenceId)) {
31
+ throw new Error(`OCCURRENCE_ALREADY_EXISTS: ${shot.occurrenceId}`);
32
+ }
33
+ occurrenceIds.add(shot.occurrenceId);
34
+ const media = knownMedia.get(shot.mediaId);
35
+ if (!media)
36
+ throw new Error(`MEDIA_NOT_FOUND: ${shot.mediaId}`);
37
+ if (media.mediaKind !== "video")
38
+ throw new Error(`ROUGH_CUT_VIDEO_REQUIRED: ${shot.mediaId}`);
39
+ const duration = shot.duration ?? media.duration;
40
+ if (duration === undefined || !Number.isFinite(duration) || duration <= 0) {
41
+ throw new Error(`ROUGH_CUT_DURATION_REQUIRED: ${shot.mediaId}`);
42
+ }
43
+ if (media.duration !== undefined && duration > media.duration) {
44
+ throw new Error(`ROUGH_CUT_DURATION_EXCEEDS_SOURCE: ${shot.mediaId}`);
45
+ }
46
+ operations.push({
47
+ type: "timeline.media.add",
48
+ occurrenceId: shot.occurrenceId,
49
+ mediaId: shot.mediaId,
50
+ role: "video",
51
+ start,
52
+ duration,
53
+ targetLane: "primary",
54
+ });
55
+ start += duration;
56
+ }
57
+ return {
58
+ projectId: snapshot.projectId,
59
+ timelineId: snapshot.timeline.id,
60
+ baseRevision: structuredClone(request.baseRevision),
61
+ operations,
62
+ duration: start,
63
+ };
64
+ }
65
+ function assertRevision(actual, expected) {
66
+ if (actual.id !== expected.id || actual.sequence !== expected.sequence) {
67
+ throw new Error("STALE_CONTEXT: rough-cut plan base revision does not match current project");
68
+ }
69
+ }
@@ -0,0 +1,33 @@
1
+ /** Version of the editor-independent Skill contract. */
2
+ export const SKILL_CONTRACT_VERSION = 1;
3
+ /** The ordered phases shared by every Skill implementation. */
4
+ export const SKILL_LIFECYCLE = [
5
+ "discover",
6
+ "resolve",
7
+ "plan",
8
+ "preview",
9
+ "execute",
10
+ "verify",
11
+ "accept",
12
+ "rollback",
13
+ ];
14
+ /** Semantic operation names are deliberately independent of editor commands. */
15
+ export const SKILL_OPERATIONS = [
16
+ "rename-clip",
17
+ "trim-clip",
18
+ "set-gain",
19
+ "reduce-noise",
20
+ "set-color-correction",
21
+ "ripple-delete",
22
+ "add-marker",
23
+ "media.import",
24
+ "timeline.media.add",
25
+ "timeline.audio.fades",
26
+ "timeline.title.add",
27
+ "timeline.media.move",
28
+ "timeline.media.replace",
29
+ "timeline.media.remove",
30
+ "timeline.transition.add",
31
+ "timeline.audio.attach",
32
+ "timeline.audio.mix",
33
+ ];
@@ -1 +1,5 @@
1
- export {};
1
+ /**
2
+ * Backwards-compatible type barrel. New code should import from the focused
3
+ * domain modules when it needs a narrower dependency surface.
4
+ */
5
+ export * from "./index.js";