@morshoto/framekit 0.1.5 → 0.1.10

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 (40) hide show
  1. package/bin/framekit.mjs +2 -1
  2. package/dist-package/adapters/final-cut/typescript/src/assets.js +223 -15
  3. package/dist-package/adapters/final-cut/typescript/src/background-export.js +384 -0
  4. package/dist-package/adapters/final-cut/typescript/src/canonical.js +588 -0
  5. package/dist-package/adapters/final-cut/typescript/src/connection.js +20 -5
  6. package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +33 -7
  7. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +805 -51
  8. package/dist-package/adapters/final-cut/typescript/src/index.js +5 -0
  9. package/dist-package/adapters/final-cut/typescript/src/library-inspection.js +390 -0
  10. package/dist-package/adapters/final-cut/typescript/src/live.js +6 -3
  11. package/dist-package/adapters/final-cut/typescript/src/media.js +151 -0
  12. package/dist-package/adapters/final-cut/typescript/src/native-session.js +412 -0
  13. package/dist-package/adapters/final-cut/typescript/src/native.js +2271 -424
  14. package/dist-package/adapters/final-cut/typescript/src/publisher.js +225 -32
  15. package/dist-package/adapters/final-cut/typescript/src/session.js +145 -17
  16. package/dist-package/apps/mcp-server/src/main.js +73 -17
  17. package/dist-package/apps/mcp-server/src/routing.js +242 -39
  18. package/dist-package/apps/mcp-server/src/server.js +677 -89
  19. package/dist-package/apps/mcp-server/src/version.js +109 -1
  20. package/dist-package/packages/runtime/src/application/media-analysis-service.js +3 -4
  21. package/dist-package/packages/runtime/src/application/project-service.js +46 -7
  22. package/dist-package/packages/runtime/src/audio/dialogue-normalization.js +9 -0
  23. package/dist-package/packages/runtime/src/capabilities.js +62 -9
  24. package/dist-package/packages/runtime/src/context/project-catalog.js +159 -0
  25. package/dist-package/packages/runtime/src/domain/capabilities.js +33 -0
  26. package/dist-package/packages/runtime/src/domain/context.js +14 -1
  27. package/dist-package/packages/runtime/src/domain/editing.js +27 -1
  28. package/dist-package/packages/runtime/src/domain/index.js +1 -0
  29. package/dist-package/packages/runtime/src/domain/skills.js +2 -0
  30. package/dist-package/packages/runtime/src/domain/timeline-target.js +217 -0
  31. package/dist-package/packages/runtime/src/editing/edit-service.js +57 -1
  32. package/dist-package/packages/runtime/src/editing/intent.js +178 -2
  33. package/dist-package/packages/runtime/src/index.js +1 -0
  34. package/dist-package/packages/runtime/src/runtime.js +2 -2
  35. package/dist-package/packages/runtime/src/skills/builtin.js +314 -39
  36. package/dist-package/packages/runtime/src/skills/requirements.js +1 -0
  37. package/dist-package/packages/runtime/src/skills/runtime.js +33 -8
  38. package/dist-package/packages/runtime/src/verification/verification.js +81 -4
  39. package/dist-package/packages/testkit/src/in-memory-editor.js +130 -4
  40. package/package.json +12 -2
@@ -1 +1,27 @@
1
- export {};
1
+ export function assertValidMaskConfiguration(mask) {
2
+ if (!mask || typeof mask !== "object") {
3
+ throw new Error("INVALID_OPERATION: mask configuration is required");
4
+ }
5
+ if (mask.mode === "rectangle") {
6
+ if (!mask.bounds)
7
+ throw new Error("INVALID_OPERATION: rectangle mask bounds are required");
8
+ const { x, y, width, height } = mask.bounds;
9
+ if (![x, y, width, height].every(Number.isFinite)
10
+ || x < 0 || y < 0 || width <= 0 || height <= 0
11
+ || x + width > 1 || y + height > 1) {
12
+ throw new Error("INVALID_OPERATION: rectangle mask bounds must be normalized");
13
+ }
14
+ return;
15
+ }
16
+ if (mask.mode === "supplied-alpha") {
17
+ if (!mask.alphaMediaId?.trim()) {
18
+ throw new Error("INVALID_OPERATION: supplied-alpha masking requires alphaMediaId");
19
+ }
20
+ if (mask.bounds)
21
+ assertValidMaskConfiguration({ mode: "rectangle", bounds: mask.bounds });
22
+ return;
23
+ }
24
+ if (mask.mode === "person-cutout")
25
+ return;
26
+ throw new Error("INVALID_OPERATION: unsupported mask mode");
27
+ }
@@ -7,6 +7,7 @@ export * from "./diff.js";
7
7
  export * from "./capabilities.js";
8
8
  export * from "./ports.js";
9
9
  export * from "./verification.js";
10
+ export * from "./timeline-target.js";
10
11
  export * from "./rough-cut.js";
11
12
  export * from "./duration.js";
12
13
  export * from "./skills.js";
@@ -22,6 +22,7 @@ export const SKILL_OPERATIONS = [
22
22
  "add-marker",
23
23
  "media.import",
24
24
  "timeline.media.add",
25
+ "timeline.picture-in-picture.add",
25
26
  "timeline.audio.fades",
26
27
  "timeline.title.add",
27
28
  "timeline.media.move",
@@ -30,4 +31,5 @@ export const SKILL_OPERATIONS = [
30
31
  "timeline.transition.add",
31
32
  "timeline.audio.attach",
32
33
  "timeline.audio.mix",
34
+ "timeline.mask.add",
33
35
  ];
@@ -0,0 +1,217 @@
1
+ /** Capture a target from a canonical snapshot without deriving identity from names or indexes. */
2
+ export function createTimelineTarget(snapshot, selection = {}) {
3
+ const frameDuration = snapshot.timeline.frameDuration;
4
+ if (!frameDuration) {
5
+ throw new Error("FRAME_ALIGNMENT_UNAVAILABLE: timeline frame duration is required for stable targeting");
6
+ }
7
+ const target = {
8
+ projectId: snapshot.projectId,
9
+ sequenceId: snapshot.timeline.id,
10
+ revision: structuredClone(snapshot.revision),
11
+ timelineStartTime: { value: "0", timescale: "1" },
12
+ frameDuration: structuredClone(frameDuration),
13
+ ...(selection.mediaId !== undefined ? { mediaId: selection.mediaId } : {}),
14
+ ...(selection.range ? { range: structuredClone(selection.range) } : {}),
15
+ };
16
+ if (selection.occurrenceId !== undefined) {
17
+ const occurrence = findUniqueOccurrence(snapshot, selection.occurrenceId);
18
+ target.occurrence = occurrenceTarget(occurrence);
19
+ if (target.mediaId !== undefined && target.mediaId !== occurrence.mediaId) {
20
+ throw new Error(`TARGET_MISMATCH: occurrence ${occurrence.id} is bound to ${occurrence.mediaId ?? "no media"}`);
21
+ }
22
+ if (target.mediaId === undefined && occurrence.mediaId !== undefined) {
23
+ target.mediaId = occurrence.mediaId;
24
+ }
25
+ }
26
+ assertValidTimelineTarget(target);
27
+ validateTargetCoordinates(snapshot, target);
28
+ return target;
29
+ }
30
+ /** Resolve and validate an explicit target against the current canonical snapshot. */
31
+ export function resolveTimelineTarget(snapshot, target) {
32
+ assertValidTimelineTarget(target);
33
+ if (target.projectId !== snapshot.projectId || target.sequenceId !== snapshot.timeline.id) {
34
+ throw new Error(`TARGET_MISMATCH: requested ${target.projectId}/${target.sequenceId} while ${snapshot.projectId}/${snapshot.timeline.id} is active`);
35
+ }
36
+ if (!sameRevision(target.revision, snapshot.revision)) {
37
+ throw new Error("STALE_CONTEXT: timeline target revision does not match current editor state");
38
+ }
39
+ if (!snapshot.timeline.frameDuration) {
40
+ throw new Error("FRAME_ALIGNMENT_UNAVAILABLE: current timeline has no frame duration");
41
+ }
42
+ if (!sameRational(target.frameDuration, snapshot.timeline.frameDuration)) {
43
+ throw new Error("FRAME_ALIGNMENT_REQUIRED: target frame duration does not match current timeline");
44
+ }
45
+ validateTargetCoordinates(snapshot, target);
46
+ const occurrence = target.occurrence
47
+ ? findUniqueOccurrence(snapshot, target.occurrence.id)
48
+ : undefined;
49
+ if (occurrence && target.occurrence) {
50
+ assertOccurrenceBinding(target.occurrence, occurrence);
51
+ }
52
+ if (target.mediaId !== undefined && occurrence?.mediaId !== target.mediaId) {
53
+ throw new Error(`TARGET_MISMATCH: target media ${target.mediaId} is not bound to occurrence ${occurrence?.id ?? "unknown"}`);
54
+ }
55
+ return { target: structuredClone(target), ...(occurrence ? { occurrence: structuredClone(occurrence) } : {}) };
56
+ }
57
+ /**
58
+ * Verify that a post-write snapshot still addresses the same target.
59
+ * Coordinates may change for trim and move; occurrence and media identity may
60
+ * not change unless the operation explicitly removes the occurrence.
61
+ */
62
+ export function assertTimelineTargetReadAfterWrite(target, before, after, options = {}) {
63
+ resolveTimelineTarget(before, target);
64
+ if (after.projectId !== target.projectId || after.timeline.id !== target.sequenceId) {
65
+ throw new Error("TARGET_MISMATCH: read-after-write snapshot changed the addressed timeline");
66
+ }
67
+ if (!target.occurrence)
68
+ return;
69
+ const matches = findOccurrences(after, target.occurrence.id);
70
+ if (matches.length === 0 && options.allowOccurrenceRemoval)
71
+ return;
72
+ if (matches.length === 0) {
73
+ throw new Error(`TARGET_MISMATCH: read-after-write lost occurrence ${target.occurrence.id}`);
74
+ }
75
+ if (matches.length > 1) {
76
+ throw new Error(`AMBIGUOUS_TIMELINE_TARGET: read-after-write duplicated occurrence ${target.occurrence.id}`);
77
+ }
78
+ if (target.mediaId !== undefined && matches[0].mediaId !== target.mediaId) {
79
+ throw new Error(`TARGET_MISMATCH: read-after-write changed media for occurrence ${target.occurrence.id}`);
80
+ }
81
+ }
82
+ /** Validate the shape of a target before any provider-specific resolution. */
83
+ export function assertValidTimelineTarget(target) {
84
+ requireNonEmpty(target.projectId, "projectId");
85
+ requireNonEmpty(target.sequenceId, "sequenceId");
86
+ requireNonEmpty(target.revision?.id, "revision.id");
87
+ if (!Number.isInteger(target.revision?.sequence) || target.revision.sequence < 0) {
88
+ throw new Error("INVALID_TIMELINE_TARGET: revision.sequence must be a non-negative integer");
89
+ }
90
+ requireNonEmpty(target.revision.timestamp, "revision.timestamp");
91
+ parseRational(target.timelineStartTime, "INVALID_TIMELINE_TARGET: timelineStartTime");
92
+ const frame = parseRational(target.frameDuration, "INVALID_TIMELINE_TARGET: frameDuration");
93
+ if (frame.value <= 0n)
94
+ throw new Error("INVALID_TIMELINE_TARGET: frameDuration must be positive");
95
+ if (target.mediaId !== undefined)
96
+ requireNonEmpty(target.mediaId, "mediaId");
97
+ if (target.occurrence) {
98
+ requireNonEmpty(target.occurrence.id, "occurrence.id");
99
+ parseRational(target.occurrence.startTime, "INVALID_TIMELINE_TARGET: occurrence.startTime");
100
+ const duration = parseRational(target.occurrence.durationTime, "INVALID_TIMELINE_TARGET: occurrence.durationTime");
101
+ if (duration.value <= 0n)
102
+ throw new Error("INVALID_TIMELINE_TARGET: occurrence duration must be positive");
103
+ if (target.occurrence.mediaId !== undefined)
104
+ requireNonEmpty(target.occurrence.mediaId, "occurrence.mediaId");
105
+ if (target.occurrence.sourceStartTime) {
106
+ parseRational(target.occurrence.sourceStartTime, "INVALID_TIMELINE_TARGET: occurrence.sourceStartTime");
107
+ }
108
+ }
109
+ if (target.range) {
110
+ parseRational(target.range.start, "INVALID_TIMELINE_TARGET: range.start");
111
+ parseRational(target.range.end, "INVALID_TIMELINE_TARGET: range.end");
112
+ }
113
+ }
114
+ function validateTargetCoordinates(snapshot, target) {
115
+ const frame = parseRational(target.frameDuration, "INVALID_TIMELINE_TARGET: frameDuration");
116
+ const origin = parseRational(target.timelineStartTime, "INVALID_TIMELINE_TARGET: timelineStartTime");
117
+ const timelineDuration = snapshot.timeline.durationTime
118
+ ? parseRational(snapshot.timeline.durationTime, "INVALID_PROJECT_STATE: timeline duration")
119
+ : undefined;
120
+ const timelineEnd = timelineDuration
121
+ ? addRational(origin, timelineDuration)
122
+ : undefined;
123
+ const validatePoint = (time, label) => {
124
+ const point = parseRational(time, `INVALID_TIMELINE_TARGET: ${label}`);
125
+ if (!isFrameAligned(point, origin, frame)) {
126
+ throw new Error(`FRAME_ALIGNMENT_REQUIRED: ${label} is not aligned to the sequence frame duration`);
127
+ }
128
+ if (compareRational(point, origin) < 0 || (timelineEnd && compareRational(point, timelineEnd) > 0)) {
129
+ throw new Error(`TARGET_MISMATCH: ${label} is outside the addressed timeline`);
130
+ }
131
+ };
132
+ if (target.occurrence) {
133
+ validatePoint(target.occurrence.startTime, "occurrence.startTime");
134
+ const occurrenceEnd = addRational(parseRational(target.occurrence.startTime, "INVALID_TIMELINE_TARGET: occurrence.startTime"), parseRational(target.occurrence.durationTime, "INVALID_TIMELINE_TARGET: occurrence.durationTime"));
135
+ validatePoint({ value: occurrenceEnd.value.toString(), timescale: occurrenceEnd.timescale.toString() }, "occurrence.endTime");
136
+ }
137
+ if (target.range) {
138
+ validatePoint(target.range.start, "range.start");
139
+ validatePoint(target.range.end, "range.end");
140
+ if (compareRational(parseRational(target.range.end, "INVALID_TIMELINE_TARGET: range.end"), parseRational(target.range.start, "INVALID_TIMELINE_TARGET: range.start")) <= 0) {
141
+ throw new Error("INVALID_TIMELINE_TARGET: range.end must be greater than range.start");
142
+ }
143
+ }
144
+ }
145
+ function occurrenceTarget(occurrence) {
146
+ return {
147
+ id: occurrence.id,
148
+ ...(occurrence.mediaId ? { mediaId: occurrence.mediaId } : {}),
149
+ ...(occurrence.sourceStartTime ? { sourceStartTime: structuredClone(occurrence.sourceStartTime) } : {}),
150
+ startTime: structuredClone(occurrence.startTime),
151
+ durationTime: structuredClone(occurrence.durationTime),
152
+ };
153
+ }
154
+ function findUniqueOccurrence(snapshot, id) {
155
+ const matches = findOccurrences(snapshot, id);
156
+ if (matches.length === 0)
157
+ throw new Error(`TIMELINE_TARGET_NOT_FOUND: occurrence ${id}`);
158
+ if (matches.length > 1)
159
+ throw new Error(`AMBIGUOUS_TIMELINE_TARGET: occurrence ${id}`);
160
+ return matches[0];
161
+ }
162
+ function findOccurrences(snapshot, id) {
163
+ return snapshot.timeline.clips.filter((candidate) => candidate.id === id);
164
+ }
165
+ function assertOccurrenceBinding(target, occurrence) {
166
+ if (target.mediaId !== occurrence.mediaId
167
+ || !sameRational(target.startTime, occurrence.startTime)
168
+ || !sameRational(target.durationTime, occurrence.durationTime)
169
+ || (target.sourceStartTime !== undefined
170
+ && (!occurrence.sourceStartTime || !sameRational(target.sourceStartTime, occurrence.sourceStartTime)))) {
171
+ throw new Error(`TARGET_MISMATCH: occurrence ${target.id} identity or coordinates changed`);
172
+ }
173
+ }
174
+ function requireNonEmpty(value, field) {
175
+ if (!value?.trim())
176
+ throw new Error(`INVALID_TIMELINE_TARGET: ${field} is required`);
177
+ }
178
+ function parseRational(time, errorPrefix) {
179
+ if (!time || !/^-?\d+$/.test(time.value) || !/^\d+$/.test(time.timescale)) {
180
+ throw new Error(`${errorPrefix} requires an integer value and timescale`);
181
+ }
182
+ const value = BigInt(time.value);
183
+ const timescale = BigInt(time.timescale);
184
+ if (timescale <= 0n)
185
+ throw new Error(`${errorPrefix} requires a positive timescale`);
186
+ return { value, timescale };
187
+ }
188
+ function addRational(left, right) {
189
+ return normalizeRational(left.value * right.timescale + right.value * left.timescale, left.timescale * right.timescale);
190
+ }
191
+ function compareRational(left, right) {
192
+ const difference = left.value * right.timescale - right.value * left.timescale;
193
+ return difference < 0n ? -1 : difference > 0n ? 1 : 0;
194
+ }
195
+ function sameRational(left, right) {
196
+ return compareRational(parseRational(left, "INVALID_TIMELINE_TARGET"), parseRational(right, "INVALID_TIMELINE_TARGET")) === 0;
197
+ }
198
+ function isFrameAligned(time, origin, frame) {
199
+ const deltaNumerator = (time.value * origin.timescale - origin.value * time.timescale) * frame.timescale;
200
+ const deltaDenominator = time.timescale * origin.timescale * frame.value;
201
+ return deltaDenominator > 0n && deltaNumerator % deltaDenominator === 0n;
202
+ }
203
+ function normalizeRational(value, timescale) {
204
+ const divisor = greatestCommonDivisor(value < 0n ? -value : value, timescale);
205
+ return { value: value / divisor, timescale: timescale / divisor };
206
+ }
207
+ function greatestCommonDivisor(left, right) {
208
+ while (right !== 0n) {
209
+ const remainder = left % right;
210
+ left = right;
211
+ right = remainder;
212
+ }
213
+ return left || 1n;
214
+ }
215
+ function sameRevision(left, right) {
216
+ return left.id === right.id && left.sequence === right.sequence;
217
+ }
@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
2
2
  import { resolve as resolvePath } from "node:path";
3
3
  import { diffSnapshots } from "../timeline/snapshot-diff.js";
4
4
  import { canonicalSnapshotDigest } from "../timeline/snapshot-digest.js";
5
+ import { assertValidMaskConfiguration } from "../domain/editing.js";
5
6
  import { sameRevision } from "../context/revision.js";
6
7
  import { parseRational } from "../timeline/rational-time.js";
7
8
  import { assertValidVerificationPolicy } from "../verification/verification.js";
@@ -154,11 +155,13 @@ export class EditService {
154
155
  throw new Error("CAPABILITY_UNAVAILABLE: editor composite transaction preview");
155
156
  }
156
157
  const expectedAfter = await this.adapter.previewTransaction(request.operations, before.revision);
158
+ const artifactDigest = await this.readArtifactDigest(target);
157
159
  const previewToken = `preview-${randomUUID()}`;
158
160
  const preview = {
159
161
  previewToken,
160
162
  target: structuredClone(target),
161
163
  baseRevision: structuredClone(before.revision),
164
+ ...(artifactDigest ? { artifactDigest } : {}),
162
165
  operations: structuredClone(request.operations),
163
166
  expectedDiff: diffSnapshots(before, expectedAfter),
164
167
  warnings: [],
@@ -189,6 +192,12 @@ export class EditService {
189
192
  throw new Error("PREVIEW_TOKEN_EXPIRED: composite edit preview has expired");
190
193
  }
191
194
  const before = await this.project.inspectProject();
195
+ const currentArtifactDigest = await this.readArtifactDigest(preview.target);
196
+ if (preview.target.kind === "artifact"
197
+ && preview.artifactDigest !== undefined
198
+ && currentArtifactDigest !== preview.artifactDigest) {
199
+ throw new Error("ARTIFACT_SOURCE_CHANGED: FCPXML artifact digest changed before execution");
200
+ }
192
201
  if (!sameRevision(preview.baseRevision, before.revision)) {
193
202
  throw new Error("STALE_CONTEXT: preview base revision does not match current editor state");
194
203
  }
@@ -234,6 +243,17 @@ export class EditService {
234
243
  verificationPolicy,
235
244
  status: "APPLIED",
236
245
  };
246
+ const authorizedDiffCheck = sameDiffContent(transaction.diff, preview.expectedDiff)
247
+ ? undefined
248
+ : {
249
+ name: "authorized-diff",
250
+ passed: false,
251
+ status: "failed",
252
+ reason: "UNAUTHORIZED_DIFF",
253
+ expected: structuredClone(preview.expectedDiff),
254
+ observed: structuredClone(transaction.diff),
255
+ detail: "canonical diff contains changes outside the preview-authorized operations",
256
+ };
237
257
  try {
238
258
  await this.reanalyzeForVerification(transaction, verificationPolicy);
239
259
  }
@@ -258,6 +278,13 @@ export class EditService {
258
278
  }
259
279
  throw new Error(`VERIFICATION_FAILED: canonical state was restored (${String(verificationError)})`);
260
280
  }
281
+ if (authorizedDiffCheck && transaction.verification) {
282
+ transaction.verification = {
283
+ ...transaction.verification,
284
+ passed: false,
285
+ checks: [...transaction.verification.checks, authorizedDiffCheck],
286
+ };
287
+ }
261
288
  if (transaction.verification.passed) {
262
289
  transaction.status = "VERIFIED";
263
290
  }
@@ -288,6 +315,12 @@ export class EditService {
288
315
  }
289
316
  async undo(transactionId) {
290
317
  const transaction = this.getTransaction(transactionId);
318
+ const currentArtifactDigest = await this.readArtifactDigest(transaction.target);
319
+ if (transaction.target?.kind === "artifact"
320
+ && transaction.artifactDigest !== undefined
321
+ && currentArtifactDigest !== transaction.artifactDigest) {
322
+ throw new Error("ARTIFACT_SOURCE_CHANGED: FCPXML artifact digest changed after transaction");
323
+ }
291
324
  const current = await this.project.inspectProject();
292
325
  if (current.projectId !== transaction.before.projectId || current.timeline.id !== transaction.before.timeline.id) {
293
326
  throw new Error(`TARGET_MISMATCH: cannot undo ${transaction.before.projectId}/${transaction.before.timeline.id} while ${current.projectId}/${current.timeline.id} is active`);
@@ -316,6 +349,9 @@ export class EditService {
316
349
  if (operations.some((operation) => operation.type === "timeline.media.add") && !capabilities.mediaPlacement) {
317
350
  throw new Error("CAPABILITY_UNAVAILABLE: timeline media placement");
318
351
  }
352
+ if (operations.some((operation) => operation.type === "timeline.picture-in-picture.add") && !capabilities.pictureInPicture) {
353
+ throw new Error("CAPABILITY_UNAVAILABLE: picture-in-picture placement");
354
+ }
319
355
  if (operations.some((operation) => operation.type === "timeline.title.add")
320
356
  && (!capabilities.titlePlacement || !capabilities.assetDiscovery)) {
321
357
  throw new Error("CAPABILITY_UNAVAILABLE: timeline title placement");
@@ -344,6 +380,13 @@ export class EditService {
344
380
  && (!capabilities.transitionPlacement || !capabilities.assetDiscovery)) {
345
381
  throw new Error("CAPABILITY_UNAVAILABLE: timeline transition placement");
346
382
  }
383
+ const maskOperations = operations.filter((operation) => operation.type === "timeline.mask.add");
384
+ if (maskOperations.some((operation) => operation.mask.mode !== "person-cutout") && !capabilities.masking) {
385
+ throw new Error("CAPABILITY_UNAVAILABLE: masking");
386
+ }
387
+ if (maskOperations.some((operation) => operation.mask.mode === "person-cutout") && !capabilities.personCutout) {
388
+ throw new Error("CAPABILITY_UNAVAILABLE: person cutout");
389
+ }
347
390
  if (operations.some((operation) => operation.type === "timeline.audio.attach") && !capabilities.audioAttachment) {
348
391
  throw new Error("CAPABILITY_UNAVAILABLE: timeline audio attachment");
349
392
  }
@@ -386,7 +429,7 @@ export class EditService {
386
429
  return { kind: "artifact", artifactId: artifact.id, artifactPath: artifact.path };
387
430
  }
388
431
  async readArtifactDigest(target) {
389
- if (target.kind !== "artifact" || !this.adapter.getManagedArtifactDigest)
432
+ if (!target || target.kind !== "artifact" || !this.adapter.getManagedArtifactDigest)
390
433
  return undefined;
391
434
  return this.adapter.getManagedArtifactDigest();
392
435
  }
@@ -434,7 +477,20 @@ function postWriteAnalysisRequirements(policy) {
434
477
  visual: assertions.some((assertion) => assertion.type === "visual-content"),
435
478
  };
436
479
  }
480
+ function sameDiffContent(left, right) {
481
+ const comparable = (diff) => {
482
+ const { from: _from, to: _to, ...content } = diff;
483
+ return content;
484
+ };
485
+ return JSON.stringify(comparable(left)) === JSON.stringify(comparable(right));
486
+ }
437
487
  function assertValidWorkflowOperation(operation) {
488
+ if (operation.type === "timeline.mask.add") {
489
+ if (!operation.occurrenceId.trim())
490
+ throw new Error("INVALID_OPERATION: mask occurrenceId is required");
491
+ assertValidMaskConfiguration(operation.mask);
492
+ return;
493
+ }
438
494
  if (operation.type !== "trim-clip")
439
495
  return;
440
496
  if (!Number.isFinite(operation.duration) || operation.duration <= 0) {
@@ -3,9 +3,134 @@ const CLARIFICATION_OPTIONS = [
3
3
  "blade_at_playhead",
4
4
  "delete_range",
5
5
  ];
6
+ const ACTIVE_PROJECT = "active";
6
7
  /** Resolve only the explicit destructive language supported by Framekit. */
7
- export function resolveEditingIntent(request) {
8
- const normalized = request.trim().replace(/\s+/g, " ").toLowerCase();
8
+ export function resolveEditingIntent(request, context) {
9
+ const collapsed = request.trim().replace(/\s+/g, " ");
10
+ const normalized = collapsed.toLowerCase();
11
+ const importAndAppendPath = parseMediaPath(collapsed, true);
12
+ if (importAndAppendPath) {
13
+ return mediaResolution({
14
+ destructive: true,
15
+ previewRequired: true,
16
+ previewTool: "editor.native.media.append.preview",
17
+ executeTool: "editor.native.media.append.execute",
18
+ operation: {
19
+ type: "media_import_then_append",
20
+ path: importAndAppendPath,
21
+ targetProject: ACTIVE_PROJECT,
22
+ placement: "append",
23
+ },
24
+ requiredCapabilities: ["native.mediaImport", "native.mediaSelection", "native.mediaAppend"],
25
+ requiredParameters: ["path", "project", "placement"],
26
+ workflow: [
27
+ "editor.native.media.import",
28
+ "editor.native.media.select",
29
+ "editor.native.media.append.preview",
30
+ "editor.native.media.append.execute",
31
+ ],
32
+ }, context);
33
+ }
34
+ if (/^import\b/i.test(collapsed) && /\band\s+append\b/i.test(collapsed)) {
35
+ return mediaClarification("Which local media path should Framekit import before appending?", ["media_import_then_append", "media_import"]);
36
+ }
37
+ const importPath = parseMediaPath(collapsed, false);
38
+ if (importPath) {
39
+ return mediaResolution({
40
+ destructive: false,
41
+ previewRequired: false,
42
+ operation: { type: "media_import", path: importPath, targetProject: ACTIVE_PROJECT },
43
+ requiredCapabilities: ["native.mediaImport"],
44
+ requiredParameters: ["path"],
45
+ workflow: ["editor.native.media.import"],
46
+ }, context);
47
+ }
48
+ if (/^import\b/i.test(collapsed)) {
49
+ return mediaClarification("Which local media path should Framekit import?", ["media_import"], false);
50
+ }
51
+ const selectHandle = parseMediaHandle(collapsed, "select");
52
+ if (selectHandle) {
53
+ return mediaResolution({
54
+ destructive: false,
55
+ previewRequired: false,
56
+ operation: { type: "media_select", mediaHandle: selectHandle },
57
+ requiredCapabilities: ["native.mediaSelection"],
58
+ requiredParameters: ["mediaHandle"],
59
+ workflow: ["editor.native.media.select"],
60
+ }, context);
61
+ }
62
+ if (/^select\b/i.test(collapsed)) {
63
+ return mediaClarification("Which Browser media handle should Framekit select?", ["media_select"], false);
64
+ }
65
+ if (isAppendSelectedRequest(normalized)) {
66
+ return mediaResolution({
67
+ destructive: true,
68
+ previewRequired: true,
69
+ previewTool: "editor.native.media.append.selected.preview",
70
+ executeTool: "editor.native.media.append.selected.execute",
71
+ operation: {
72
+ type: "media_append_selected",
73
+ targetProject: ACTIVE_PROJECT,
74
+ placement: "append",
75
+ },
76
+ requiredCapabilities: ["native.mediaAppendSelected"],
77
+ requiredParameters: ["project", "placement"],
78
+ workflow: [
79
+ "editor.native.media.append.selected.preview",
80
+ "editor.native.media.append.selected.execute",
81
+ ],
82
+ }, context);
83
+ }
84
+ const insertHandle = parseMediaHandle(collapsed, "insert");
85
+ if (insertHandle) {
86
+ return mediaResolution({
87
+ destructive: true,
88
+ previewRequired: true,
89
+ previewTool: "editor.native.media.insert.preview",
90
+ executeTool: "editor.native.media.insert.execute",
91
+ operation: {
92
+ type: "media_insert",
93
+ mediaHandle: insertHandle,
94
+ targetProject: ACTIVE_PROJECT,
95
+ placement: "insert",
96
+ },
97
+ requiredCapabilities: ["native.mediaSelection", "native.mediaInsert"],
98
+ requiredParameters: ["mediaHandle", "project", "placement"],
99
+ workflow: [
100
+ "editor.native.media.select",
101
+ "editor.native.media.insert.preview",
102
+ "editor.native.media.insert.execute",
103
+ ],
104
+ }, context);
105
+ }
106
+ const appendHandle = parseMediaHandle(collapsed, "append");
107
+ if (appendHandle) {
108
+ return mediaResolution({
109
+ destructive: true,
110
+ previewRequired: true,
111
+ previewTool: "editor.native.media.append.preview",
112
+ executeTool: "editor.native.media.append.execute",
113
+ operation: {
114
+ type: "media_append",
115
+ mediaHandle: appendHandle,
116
+ targetProject: ACTIVE_PROJECT,
117
+ placement: "append",
118
+ },
119
+ requiredCapabilities: ["native.mediaSelection", "native.mediaAppend"],
120
+ requiredParameters: ["mediaHandle", "project", "placement"],
121
+ workflow: [
122
+ "editor.native.media.select",
123
+ "editor.native.media.append.preview",
124
+ "editor.native.media.append.execute",
125
+ ],
126
+ }, context);
127
+ }
128
+ if (/^append\b/i.test(collapsed)) {
129
+ return mediaClarification("Should Framekit append the currently selected Browser media or use a media handle?", ["media_append_selected", "media_append"]);
130
+ }
131
+ if (/^insert\b/i.test(collapsed)) {
132
+ return mediaClarification("Which Browser media handle should Framekit insert at the playhead?", ["media_insert", "media_select"]);
133
+ }
9
134
  const trimMatch = normalized.match(/^cut at (\d+(?:\.\d+)?) seconds? and remove the rest$/);
10
135
  if (trimMatch) {
11
136
  const duration = secondsToRational(trimMatch[1]);
@@ -53,6 +178,57 @@ export function resolveEditingIntent(request) {
53
178
  options: [...CLARIFICATION_OPTIONS],
54
179
  };
55
180
  }
181
+ function mediaResolution(input, context) {
182
+ const missingCapabilities = context
183
+ ? input.requiredCapabilities.filter((capability) => context.availableCapabilities[capability] !== true)
184
+ : [];
185
+ if (missingCapabilities.length > 0) {
186
+ return {
187
+ status: "capability_unavailable",
188
+ destructive: input.destructive,
189
+ previewRequired: false,
190
+ question: "The connected editor cannot perform this native media operation.",
191
+ options: [input.operation.type],
192
+ requiredCapabilities: [...input.requiredCapabilities],
193
+ missingCapabilities,
194
+ };
195
+ }
196
+ return {
197
+ status: "resolved",
198
+ ...input,
199
+ };
200
+ }
201
+ function mediaClarification(question, options, destructive = true) {
202
+ return {
203
+ status: "clarification_required",
204
+ destructive,
205
+ previewRequired: false,
206
+ question,
207
+ options,
208
+ };
209
+ }
210
+ function isAppendSelectedRequest(request) {
211
+ return /^append(?:\s+the)?\s+(?:currently\s+)?(?:selected\s+)?(?:browser\s+)?media(?:\s+to\s+(?:the\s+)?(?:active\s+)?timeline)?$/.test(request)
212
+ && /\bselected\b/.test(request);
213
+ }
214
+ function parseMediaPath(request, withAppend) {
215
+ const suffix = withAppend
216
+ ? "\\s+and\\s+append(?:\\s+it)?(?:\\s+to\\s+(?:the\\s+)?(?:active\\s+)?timeline)?"
217
+ : "";
218
+ const match = request.match(new RegExp(`^import(?:\\s+(?:this|the))?(?:\\s+(?:local\\s+)?(?:video|audio|media))?\\s+(?:from\\s+)?(?:\\\"([^\\\"]+)\\\"|'([^']+)'|(\\S+?))${suffix}$`, "i"));
219
+ const path = match?.[1] ?? match?.[2] ?? match?.[3];
220
+ return path && !["video", "audio", "media"].includes(path.toLowerCase()) ? path : undefined;
221
+ }
222
+ function parseMediaHandle(request, operation) {
223
+ const action = operation === "select" ? "select" : operation;
224
+ const suffix = operation === "insert"
225
+ ? "\\s+at\\s+(?:the\\s+)?playhead"
226
+ : operation === "append"
227
+ ? "(?:\\s+to\\s+(?:the\\s+)?(?:active\\s+)?timeline)?"
228
+ : "";
229
+ const match = request.match(new RegExp(`^${action}(?:\\s+(?:the\\s+)?)?(?:\\s+browser)?\\s+media(?:\\s+with)?(?:\\s+handle)?\\s+(?:\\\"([^\\\"]+)\\\"|'([^']+)'|(\\S+?))${suffix}$`, "i"));
230
+ return (match?.[1] ?? match?.[2] ?? match?.[3])?.trim();
231
+ }
56
232
  function secondsToRational(seconds) {
57
233
  if (!seconds.includes("."))
58
234
  return { value: seconds, timescale: "1" };
@@ -6,6 +6,7 @@ export * from "./editing/intent.js";
6
6
  export * from "./editing/duration-policy.js";
7
7
  export * from "./capabilities.js";
8
8
  export * from "./timeline/snapshot-digest.js";
9
+ export * from "./context/project-catalog.js";
9
10
  export * from "./speech/filler-removal.js";
10
11
  export * from "./audio/dialogue-normalization.js";
11
12
  export * from "./audio/noise-reduction.js";
@@ -63,8 +63,8 @@ export class AgentVideoRuntime {
63
63
  async selectProject(selection) {
64
64
  return this.projects.selectProject(selection);
65
65
  }
66
- async inspectEditor() {
67
- return this.projects.inspectEditor();
66
+ async inspectEditor(options = {}) {
67
+ return this.projects.inspectEditor(options);
68
68
  }
69
69
  async inspectContext() {
70
70
  const editor = await this.inspectEditor();