@morshoto/framekit 0.1.5 → 0.1.6

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.
@@ -1,6 +1,6 @@
1
1
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
2
2
  import { InMemoryEditorAdapter } from "../../../packages/testkit/src/index.js";
3
- import { createCommandAnalyzers, createFinalCutLiveAdapter, FcpxmlDocumentAdapter, FinalCutAssetRegistry, FinalCutConnectionManager, FinalCutNativeAutomationAdapter, DisposableNativeEditWorkflow, FinalCutProjectPublisher, FinalCutVideoExporter, FinalCutSessionAdapter, createNativeOperationLease, isFinalCutVideoProbeAvailable, } from "../../../adapters/final-cut/typescript/src/index.js";
3
+ import { createCommandAnalyzers, createFinalCutLiveAdapter, FcpxmlDocumentAdapter, FinalCutAssetRegistry, FinalCutConnectionManager, assertCanonicalProviderConfiguration, FinalCutCanonicalNativeProvider, FinalCutCanonicalSnapshotSource, FinalCutNativeAutomationAdapter, createFinalCutNativeTargetResolver, DisposableNativeEditWorkflow, FinalCutProjectPublisher, FinalCutVideoExporter, FinalCutSessionAdapter, createNativeOperationLease, isFinalCutVideoProbeAvailable, } from "../../../adapters/final-cut/typescript/src/index.js";
4
4
  import { FixtureAudioAnalyzer, FixtureMetadataAnalyzer, FixtureSpeechAnalyzer, FixtureVisualAnalyzer } from "../../../packages/testkit/src/index.js";
5
5
  import { AgentVideoRuntime } from "../../../packages/runtime/src/index.js";
6
6
  import { createMcpServer } from "./server.js";
@@ -51,7 +51,20 @@ const fixture = new InMemoryEditorAdapter({
51
51
  const liveMode = process.env.FRAMEKIT_EDITOR === "final-cut-live";
52
52
  const headlessFinalCut = liveMode && process.env.FRAMEKIT_FINAL_CUT_HEADLESS === "1";
53
53
  const fcpxmlPath = liveMode ? process.env.FRAMEKIT_FCPXML_PATH : undefined;
54
- const connection = liveMode ? new FinalCutConnectionManager({ headless: headlessFinalCut }) : undefined;
54
+ const canonicalNativeProviderEnabled = liveMode && process.env.FRAMEKIT_FINAL_CUT_CANONICAL_PROVIDER === "native";
55
+ if (canonicalNativeProviderEnabled && headlessFinalCut) {
56
+ throw new Error("FINAL_CUT_CANONICAL_NATIVE_REQUIRES_HEADED: set FRAMEKIT_FINAL_CUT_HEADLESS=0 for the native provider");
57
+ }
58
+ if (canonicalNativeProviderEnabled && process.env.FRAMEKIT_FINAL_CUT_NATIVE_WRITES !== "1") {
59
+ throw new Error("FINAL_CUT_CANONICAL_NATIVE_REQUIRES_WRITES: set FRAMEKIT_FINAL_CUT_NATIVE_WRITES=1 for the native provider");
60
+ }
61
+ const canonicalProviderRequired = liveMode
62
+ && process.env.FRAMEKIT_FINAL_CUT_CANONICAL_REQUIRED === "1"
63
+ && !canonicalNativeProviderEnabled;
64
+ assertCanonicalProviderConfiguration({ required: canonicalProviderRequired || canonicalNativeProviderEnabled, fcpxmlPath });
65
+ const connection = liveMode
66
+ ? new FinalCutConnectionManager({ headless: headlessFinalCut, canonicalProviderRequired })
67
+ : undefined;
55
68
  const autoConnect = liveMode && process.env.FRAMEKIT_AUTO_CONNECT !== "0";
56
69
  if (autoConnect)
57
70
  connection?.startAutoConnect();
@@ -59,10 +72,40 @@ const liveAdapter = liveMode ? createFinalCutLiveAdapter() : undefined;
59
72
  const nativeOperationLease = autoConnect
60
73
  ? createNativeOperationLease(() => connection?.stopAutoConnect(), () => connection?.startAutoConnect())
61
74
  : undefined;
75
+ const nativeEditor = liveMode
76
+ ? new FinalCutNativeAutomationAdapter({
77
+ enabled: !headlessFinalCut && process.env.FRAMEKIT_FINAL_CUT_NATIVE_WRITES === "1",
78
+ liveState: () => liveAdapter.readLiveState(),
79
+ nativeOperationLease,
80
+ })
81
+ : undefined;
82
+ const canonicalNativeMutationEditor = canonicalNativeProviderEnabled
83
+ ? new FinalCutNativeAutomationAdapter({
84
+ enabled: true,
85
+ nativeOperationLease,
86
+ })
87
+ : nativeEditor;
88
+ const canonicalNativeProvider = canonicalNativeProviderEnabled
89
+ ? new FinalCutCanonicalNativeProvider({
90
+ live: liveAdapter,
91
+ native: {
92
+ renameSelectedClip: async (name) => {
93
+ const result = await canonicalNativeMutationEditor.edit({ type: "rename-selected-clip", name });
94
+ return { operationId: result.operationId, undoAvailable: result.undoAvailable };
95
+ },
96
+ undo: async (operationId) => {
97
+ const result = await canonicalNativeMutationEditor.undo(operationId);
98
+ return { undone: result.undone, verification: result.verification };
99
+ },
100
+ },
101
+ readSnapshot: () => new FinalCutCanonicalSnapshotSource().readSnapshot(),
102
+ resolveTarget: createFinalCutNativeTargetResolver(nativeEditor),
103
+ })
104
+ : undefined;
62
105
  const editor = liveMode
63
106
  ? new FinalCutSessionAdapter({
64
- live: liveAdapter,
65
- ...(fcpxmlPath
107
+ live: canonicalNativeProvider ?? liveAdapter,
108
+ ...(fcpxmlPath && !canonicalNativeProviderEnabled
66
109
  ? (() => {
67
110
  const document = new FcpxmlDocumentAdapter(fcpxmlPath);
68
111
  return { snapshot: document, mutation: document };
@@ -73,6 +116,7 @@ const editor = liveMode
73
116
  ?.split(process.platform === "win32" ? ";" : ":")
74
117
  .map((root) => root.trim())
75
118
  .filter(Boolean),
119
+ nativeTitleProvider: nativeEditor?.capabilities().titleDiscovery ? nativeEditor : undefined,
76
120
  }),
77
121
  })
78
122
  : fixture;
@@ -91,13 +135,6 @@ const analyzers = liveMode
91
135
  metadataAnalyzer: new FixtureMetadataAnalyzer(),
92
136
  };
93
137
  const runtime = new AgentVideoRuntime(editor, analyzers);
94
- const nativeEditor = liveMode
95
- ? new FinalCutNativeAutomationAdapter({
96
- enabled: !headlessFinalCut && process.env.FRAMEKIT_FINAL_CUT_NATIVE_WRITES === "1",
97
- liveState: () => liveAdapter.readLiveState(),
98
- nativeOperationLease,
99
- })
100
- : undefined;
101
138
  const disposableNative = liveMode && !headlessFinalCut && !fcpxmlPath && nativeEditor
102
139
  ? new DisposableNativeEditWorkflow({
103
140
  native: nativeEditor,
@@ -32,11 +32,26 @@ const operationRequirements = {
32
32
  editorRequirement("readAfterWrite"),
33
33
  editorRequirement("rollback"),
34
34
  ],
35
+ "timeline.mask.add": [
36
+ editorRequirement("projectRead"),
37
+ editorRequirement("timelineSnapshotRead"),
38
+ editorRequirement("timelineWrite"),
39
+ editorRequirement("readAfterWrite"),
40
+ editorRequirement("rollback"),
41
+ editorRequirement("masking"),
42
+ ],
35
43
  "editor.native.edit": [
36
44
  nativeRequirement("selectionEdit"),
37
45
  nativeRequirement("timelineFocus"),
38
46
  nativeRequirement("undo"),
39
47
  ],
48
+ "editor.native.picture-in-picture": [
49
+ nativeRequirement("pictureInPicture"),
50
+ nativeRequirement("mediaSelection"),
51
+ nativeRequirement("timelineOccurrenceLocate"),
52
+ nativeRequirement("timelineFocus"),
53
+ nativeRequirement("undo"),
54
+ ],
40
55
  "timeline.publish.new-project": [
41
56
  {
42
57
  label: "editor.artifactPublish",
@@ -62,6 +62,39 @@ const markerSchema = z.object({
62
62
  duration: z.number().nonnegative(),
63
63
  name: z.string().min(1),
64
64
  });
65
+ const maskBoundsSchema = z.object({
66
+ x: z.number().finite().min(0).max(1),
67
+ y: z.number().finite().min(0).max(1),
68
+ width: z.number().finite().positive().max(1),
69
+ height: z.number().finite().positive().max(1),
70
+ }).strict().superRefine((bounds, context) => {
71
+ if (bounds.x + bounds.width > 1) {
72
+ context.addIssue({ code: z.ZodIssueCode.custom, path: ["width"], message: "x plus width must fit within the frame" });
73
+ }
74
+ if (bounds.y + bounds.height > 1) {
75
+ context.addIssue({ code: z.ZodIssueCode.custom, path: ["height"], message: "y plus height must fit within the frame" });
76
+ }
77
+ });
78
+ const maskSchema = z.discriminatedUnion("mode", [
79
+ z.object({
80
+ mode: z.literal("rectangle"),
81
+ bounds: maskBoundsSchema,
82
+ inverted: z.boolean().optional(),
83
+ }).strict(),
84
+ z.object({
85
+ mode: z.literal("supplied-alpha"),
86
+ alphaMediaId: z.string().trim().min(1),
87
+ bounds: maskBoundsSchema.optional(),
88
+ inverted: z.boolean().optional(),
89
+ }).strict(),
90
+ z.object({
91
+ mode: z.literal("person-cutout"),
92
+ }).strict(),
93
+ ]);
94
+ const nativeMaskSchema = z.object({
95
+ mode: z.literal("rectangle"),
96
+ bounds: maskBoundsSchema,
97
+ }).strict();
65
98
  const renameClipSchema = z.object({ type: z.literal("rename-clip"), clipId: z.string().min(1), name: z.string().min(1), baseRevision: revisionSchema });
66
99
  const trimClipSchema = z.object({
67
100
  type: z.literal("trim-clip"),
@@ -290,6 +323,28 @@ const workflowOperationSchema = z.discriminatedUnion("type", [
290
323
  duration: z.number().positive(),
291
324
  targetLane: z.union([z.literal("primary"), z.number().int()]).optional(),
292
325
  }),
326
+ z.object({
327
+ type: z.literal("timeline.picture-in-picture.add"),
328
+ occurrenceId: z.string().min(1),
329
+ mediaId: z.string().min(1),
330
+ attachedTo: z.string().min(1),
331
+ start: z.number().finite().nonnegative(),
332
+ duration: z.number().finite().positive(),
333
+ targetLane: z.number().int().refine((lane) => lane !== 0, "PIP requires a connected non-primary lane"),
334
+ position: z.object({ x: z.number().finite(), y: z.number().finite() }),
335
+ scale: z.number().finite().positive(),
336
+ crop: z.object({
337
+ top: z.number().finite().min(0).lt(1),
338
+ right: z.number().finite().min(0).lt(1),
339
+ bottom: z.number().finite().min(0).lt(1),
340
+ left: z.number().finite().min(0).lt(1),
341
+ }).optional(),
342
+ frame: z.object({
343
+ style: z.literal("solid"),
344
+ color: z.string().regex(/^#[0-9a-f]{6}$/i),
345
+ width: z.number().finite().nonnegative(),
346
+ }).optional(),
347
+ }),
293
348
  z.object({
294
349
  type: z.literal("timeline.audio.fades"),
295
350
  clipId: z.string().min(1),
@@ -344,6 +399,11 @@ const workflowOperationSchema = z.discriminatedUnion("type", [
344
399
  fadeIn: z.number().nonnegative().optional(),
345
400
  fadeOut: z.number().nonnegative().optional(),
346
401
  }),
402
+ z.object({
403
+ type: z.literal("timeline.mask.add"),
404
+ occurrenceId: z.string().min(1),
405
+ mask: maskSchema,
406
+ }),
347
407
  ]);
348
408
  const workflowOperationsSchema = z.array(workflowOperationSchema).min(1).superRefine((operations, context) => {
349
409
  operations.forEach((operation, index) => {
@@ -359,6 +419,11 @@ const workflowOperationsSchema = z.array(workflowOperationSchema).min(1).superRe
359
419
  && (typeof operation.targetLane !== "number" || operation.targetLane === 0)) {
360
420
  context.addIssue({ code: z.ZodIssueCode.custom, path: [index, "targetLane"], message: "audio requires an explicit non-primary lane" });
361
421
  }
422
+ if (operation.type === "timeline.picture-in-picture.add"
423
+ && operation.crop
424
+ && (operation.crop.left + operation.crop.right >= 1 || operation.crop.top + operation.crop.bottom >= 1)) {
425
+ context.addIssue({ code: z.ZodIssueCode.custom, path: [index, "crop"], message: "PIP crop must leave a positive source rectangle" });
426
+ }
362
427
  if (operation.type === "timeline.audio.mix"
363
428
  && operation.gainDb === undefined && operation.fadeIn === undefined && operation.fadeOut === undefined) {
364
429
  context.addIssue({ code: z.ZodIssueCode.custom, path: [index], message: "audio mix requires a gain or fade change" });
@@ -470,6 +535,37 @@ const nativeTransitionPreviewSchema = {
470
535
  afterOccurrenceHandle: z.string().min(1),
471
536
  duration: rationalTimeSchema,
472
537
  };
538
+ const nativePictureInPicturePreviewSchema = {
539
+ mediaHandle: z.string().min(1),
540
+ anchorOccurrenceHandle: z.string().min(1),
541
+ start: rationalTimeSchema,
542
+ duration: rationalTimeSchema,
543
+ position: z.object({ x: z.number().finite(), y: z.number().finite() }),
544
+ scale: z.number().finite().positive(),
545
+ crop: z.object({
546
+ top: z.number().finite().min(0).lt(1),
547
+ right: z.number().finite().min(0).lt(1),
548
+ bottom: z.number().finite().min(0).lt(1),
549
+ left: z.number().finite().min(0).lt(1),
550
+ }).optional(),
551
+ frame: z.object({
552
+ style: z.literal("solid"),
553
+ color: z.string().regex(/^#[0-9a-f]{6}$/i),
554
+ width: z.number().finite().nonnegative(),
555
+ }).optional(),
556
+ };
557
+ const nativeMaskPreviewSchema = {
558
+ occurrenceHandle: z.string().trim().min(1),
559
+ mask: nativeMaskSchema,
560
+ };
561
+ const timelineMaskInputSchema = {
562
+ projectId: z.string().trim().min(1),
563
+ sequenceId: z.string().trim().min(1),
564
+ baseRevision: revisionValueSchema,
565
+ occurrenceId: z.string().trim().min(1),
566
+ mask: maskSchema,
567
+ verification: verificationPolicySchema.optional(),
568
+ };
473
569
  const exportAssertionSchema = z.discriminatedUnion("type", [
474
570
  z.object({
475
571
  type: z.literal("audio-audibility"),
@@ -711,7 +807,9 @@ export function createMcpServer(runtime, options = {}) {
711
807
  inputSchema: {
712
808
  operation: z.enum([
713
809
  "timeline.edit",
810
+ "timeline.mask.add",
714
811
  "editor.native.edit",
812
+ "editor.native.picture-in-picture",
715
813
  "timeline.publish.new-project",
716
814
  "timeline.export",
717
815
  ]),
@@ -795,6 +893,24 @@ export function createMcpServer(runtime, options = {}) {
795
893
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native title placement is not configured");
796
894
  return jsonResult(await options.nativeEditor.executeTitleAdd(previewToken));
797
895
  });
896
+ server.registerTool("editor.native.picture-in-picture.preview", {
897
+ description: "Preview connecting selected Final Cut Browser video to a stable timeline occurrence with verified transform properties.",
898
+ inputSchema: nativePictureInPicturePreviewSchema,
899
+ }, async (request) => {
900
+ if (!options.nativeEditor)
901
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native picture-in-picture placement is not configured");
902
+ await requireEditingRoute(runtime, options, "editor.native.picture-in-picture");
903
+ return jsonResult(await options.nativeEditor.previewPictureInPicture(request));
904
+ });
905
+ server.registerTool("editor.native.picture-in-picture.execute", {
906
+ description: "Execute a native Final Cut picture-in-picture preview and return transform readback, revision, and Undo verification.",
907
+ inputSchema: { previewToken: z.string().min(1) },
908
+ }, async ({ previewToken }) => {
909
+ if (!options.nativeEditor)
910
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native picture-in-picture placement is not configured");
911
+ await requireEditingRoute(runtime, options, "editor.native.picture-in-picture");
912
+ return jsonResult(await options.nativeEditor.executePictureInPicture(previewToken));
913
+ });
798
914
  server.registerTool("editor.native.transition.search", {
799
915
  description: "Search the visible Final Cut Transitions browser and return only transitions with stable native identities.",
800
916
  inputSchema: { query: z.string().trim().min(1) },
@@ -830,6 +946,22 @@ export function createMcpServer(runtime, options = {}) {
830
946
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native transition placement is not configured");
831
947
  return jsonResult(await options.nativeEditor.executeTransitionAdd(previewToken));
832
948
  });
949
+ server.registerTool("editor.native.mask.preview", {
950
+ description: "Preview adding a bounded native Final Cut Draw Mask to one located occurrence without mutating the timeline.",
951
+ inputSchema: nativeMaskPreviewSchema,
952
+ }, async ({ occurrenceHandle, mask }) => {
953
+ if (!options.nativeEditor)
954
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native masking is not configured");
955
+ return jsonResult(await options.nativeEditor.previewMask({ occurrenceHandle, mask }));
956
+ });
957
+ server.registerTool("editor.native.mask.execute", {
958
+ description: "Execute a previously previewed native Draw Mask and return readback verification and native Undo state.",
959
+ inputSchema: { previewToken: z.string().trim().min(1) },
960
+ }, async ({ previewToken }) => {
961
+ if (!options.nativeEditor)
962
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native masking is not configured");
963
+ return jsonResult(await options.nativeEditor.executeMask(previewToken));
964
+ });
833
965
  server.registerTool("editor.native.undo", {
834
966
  description: "Undo a previously accepted native Final Cut UI edit using Final Cut's native Undo command.",
835
967
  inputSchema: { operationId: z.string().min(1) },
@@ -1211,6 +1343,17 @@ export function createMcpServer(runtime, options = {}) {
1211
1343
  await requireEditingRoute(runtime, options, "timeline.edit");
1212
1344
  return jsonResult(await runtime.previewEdit(request));
1213
1345
  });
1346
+ server.registerTool("timeline.mask.add.preview", {
1347
+ description: "Preview a bounded or supplied-alpha mask against an explicit project, sequence, revision, and occurrence without mutation.",
1348
+ inputSchema: timelineMaskInputSchema,
1349
+ }, async ({ projectId, sequenceId, baseRevision, occurrenceId, mask, verification }) => {
1350
+ await requireEditingRoute(runtime, options, "timeline.mask.add");
1351
+ return jsonResult(await runtime.previewTimelineEdit({ projectId, sequenceId }, {
1352
+ baseRevision,
1353
+ operations: [{ type: "timeline.mask.add", occurrenceId, mask }],
1354
+ ...(verification ? { verification } : {}),
1355
+ }));
1356
+ });
1214
1357
  server.registerTool("artifact.edit.preview", {
1215
1358
  description: "Validate and preview an ordered artifact edit against the identified FCPXML artifact without mutating it.",
1216
1359
  inputSchema: {
@@ -1245,6 +1388,13 @@ export function createMcpServer(runtime, options = {}) {
1245
1388
  await requireEditingRoute(runtime, options, "timeline.edit");
1246
1389
  return jsonResult(await runtime.executeEdit(previewToken));
1247
1390
  });
1391
+ server.registerTool("timeline.mask.add.execute", {
1392
+ description: "Execute one short-lived mask preview token after capability and revision checks, then verify the mask state.",
1393
+ inputSchema: { previewToken: z.string().trim().min(1) },
1394
+ }, async ({ previewToken }) => {
1395
+ await requireEditingRoute(runtime, options, "timeline.mask.add");
1396
+ return jsonResult(await runtime.executeEdit(previewToken));
1397
+ });
1248
1398
  server.registerTool("speech.analyze", {
1249
1399
  description: "Analyze speech words, filler markers, and optional VAD for one media item or source range.",
1250
1400
  inputSchema: { mediaId: z.string().min(1), range: rangeSchema.optional() },
@@ -1387,8 +1537,11 @@ async function inspectMcpEditor(runtime, options) {
1387
1537
  mediaAppend: Boolean(native?.mediaAppend),
1388
1538
  mediaInsert: Boolean(native?.mediaInsert),
1389
1539
  titlePlacement: Boolean(native?.titlePlacement),
1540
+ titleDiscovery: Boolean(native?.titleDiscovery),
1541
+ pictureInPicture: Boolean(native?.pictureInPicture),
1390
1542
  transitionDiscovery: Boolean(native?.transitionDiscovery),
1391
1543
  transitionPlacement: Boolean(native?.transitionPlacement),
1544
+ masking: Boolean(native?.masking),
1392
1545
  timelineFocus: Boolean(native?.timelineFocus),
1393
1546
  projectCreation: false,
1394
1547
  clipInsertion: false,
@@ -42,7 +42,8 @@ export class MediaAnalysisService {
42
42
  throw new Error(`TARGET_MISMATCH: occurrence ${occurrenceId} does not reference media ${mediaId}`);
43
43
  }
44
44
  const media = findMedia(project, mediaId);
45
- const requestedRange = { start: 0, end: clip.duration };
45
+ const sourceStart = clip.sourceStart ?? 0;
46
+ const requestedRange = { start: sourceStart, end: sourceStart + clip.duration };
46
47
  const analysis = await this.options.audioAnalyzer.analyze({ project, media }, requestedRange);
47
48
  const analyzedDurationSeconds = analysis.analyzedDurationSeconds ?? clip.duration;
48
49
  const valid = analysis.valid !== false
@@ -1,3 +1,12 @@
1
+ /** Defaults for the version 1.0.0 dialogue-normalization Skill. */
2
+ export const DIALOGUE_NORMALIZATION_DEFAULTS = {
3
+ targetLufs: -16,
4
+ toleranceDb: 0.5,
5
+ maxTruePeakDb: -1,
6
+ minGainDb: -6,
7
+ maxGainDb: 6,
8
+ minDialogueDurationSeconds: 1,
9
+ };
1
10
  /** Plan a bounded clip-level gain change without mutating an editor. */
2
11
  export function planDialogueGain(measurement, options) {
3
12
  validateOptions(options);
@@ -56,6 +56,7 @@ export function withCanonicalTimelineMode(capabilities) {
56
56
  titlePlacement: refreshDescriptor(Boolean(normalized.editor.titlePlacement), previous.editing.titlePlacement, "verified", "title placement is unavailable"),
57
57
  pictureInPicture: previous.editing.pictureInPicture,
58
58
  masking: previous.editing.masking,
59
+ personCutout: previous.editing.personCutout,
59
60
  },
60
61
  native: nativeAvailability(previous.native),
61
62
  publishing: previous.publishing.projectCreation,
@@ -135,8 +136,9 @@ function editingFamily(editor, overrides, backend) {
135
136
  return {
136
137
  compositeTransactions: descriptorFrom(overrides.compositeTransactions ?? Boolean(editor.compositeTransactions), backend, "verified", "composite editing transactions are unavailable"),
137
138
  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"),
139
+ pictureInPicture: descriptorFrom(overrides.pictureInPicture ?? Boolean(editor.pictureInPicture), backend, "verified", "picture-in-picture editing is unavailable"),
140
+ masking: descriptorFrom(overrides.masking ?? Boolean(editor.masking), backend, "verified", "masking is unavailable"),
141
+ personCutout: descriptorFrom(overrides.personCutout ?? Boolean(editor.personCutout), backend, "verified", "person cutout is unavailable"),
140
142
  };
141
143
  }
142
144
  export function createCapabilityPreflight(identity, capabilities, options = {}) {
@@ -188,12 +190,15 @@ function nativeFamily(native, backend) {
188
190
  "mediaAppend",
189
191
  "mediaInsert",
190
192
  "titlePlacement",
193
+ "titleDiscovery",
191
194
  "timelineFocus",
192
195
  "projectCreation",
193
196
  "clipInsertion",
194
197
  "clipMovement",
195
198
  "transitionDiscovery",
196
199
  "transitionPlacement",
200
+ "pictureInPicture",
201
+ "masking",
197
202
  ];
198
203
  return Object.fromEntries(nativeOperations.map((operation) => [
199
204
  operation,
@@ -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
+ }
@@ -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
  ];
@@ -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";
@@ -234,6 +235,17 @@ export class EditService {
234
235
  verificationPolicy,
235
236
  status: "APPLIED",
236
237
  };
238
+ const authorizedDiffCheck = sameDiffContent(transaction.diff, preview.expectedDiff)
239
+ ? undefined
240
+ : {
241
+ name: "authorized-diff",
242
+ passed: false,
243
+ status: "failed",
244
+ reason: "UNAUTHORIZED_DIFF",
245
+ expected: structuredClone(preview.expectedDiff),
246
+ observed: structuredClone(transaction.diff),
247
+ detail: "canonical diff contains changes outside the preview-authorized operations",
248
+ };
237
249
  try {
238
250
  await this.reanalyzeForVerification(transaction, verificationPolicy);
239
251
  }
@@ -258,6 +270,13 @@ export class EditService {
258
270
  }
259
271
  throw new Error(`VERIFICATION_FAILED: canonical state was restored (${String(verificationError)})`);
260
272
  }
273
+ if (authorizedDiffCheck && transaction.verification) {
274
+ transaction.verification = {
275
+ ...transaction.verification,
276
+ passed: false,
277
+ checks: [...transaction.verification.checks, authorizedDiffCheck],
278
+ };
279
+ }
261
280
  if (transaction.verification.passed) {
262
281
  transaction.status = "VERIFIED";
263
282
  }
@@ -316,6 +335,9 @@ export class EditService {
316
335
  if (operations.some((operation) => operation.type === "timeline.media.add") && !capabilities.mediaPlacement) {
317
336
  throw new Error("CAPABILITY_UNAVAILABLE: timeline media placement");
318
337
  }
338
+ if (operations.some((operation) => operation.type === "timeline.picture-in-picture.add") && !capabilities.pictureInPicture) {
339
+ throw new Error("CAPABILITY_UNAVAILABLE: picture-in-picture placement");
340
+ }
319
341
  if (operations.some((operation) => operation.type === "timeline.title.add")
320
342
  && (!capabilities.titlePlacement || !capabilities.assetDiscovery)) {
321
343
  throw new Error("CAPABILITY_UNAVAILABLE: timeline title placement");
@@ -344,6 +366,13 @@ export class EditService {
344
366
  && (!capabilities.transitionPlacement || !capabilities.assetDiscovery)) {
345
367
  throw new Error("CAPABILITY_UNAVAILABLE: timeline transition placement");
346
368
  }
369
+ const maskOperations = operations.filter((operation) => operation.type === "timeline.mask.add");
370
+ if (maskOperations.some((operation) => operation.mask.mode !== "person-cutout") && !capabilities.masking) {
371
+ throw new Error("CAPABILITY_UNAVAILABLE: masking");
372
+ }
373
+ if (maskOperations.some((operation) => operation.mask.mode === "person-cutout") && !capabilities.personCutout) {
374
+ throw new Error("CAPABILITY_UNAVAILABLE: person cutout");
375
+ }
347
376
  if (operations.some((operation) => operation.type === "timeline.audio.attach") && !capabilities.audioAttachment) {
348
377
  throw new Error("CAPABILITY_UNAVAILABLE: timeline audio attachment");
349
378
  }
@@ -434,7 +463,20 @@ function postWriteAnalysisRequirements(policy) {
434
463
  visual: assertions.some((assertion) => assertion.type === "visual-content"),
435
464
  };
436
465
  }
466
+ function sameDiffContent(left, right) {
467
+ const comparable = (diff) => {
468
+ const { from: _from, to: _to, ...content } = diff;
469
+ return content;
470
+ };
471
+ return JSON.stringify(comparable(left)) === JSON.stringify(comparable(right));
472
+ }
437
473
  function assertValidWorkflowOperation(operation) {
474
+ if (operation.type === "timeline.mask.add") {
475
+ if (!operation.occurrenceId.trim())
476
+ throw new Error("INVALID_OPERATION: mask occurrenceId is required");
477
+ assertValidMaskConfiguration(operation.mask);
478
+ return;
479
+ }
438
480
  if (operation.type !== "trim-clip")
439
481
  return;
440
482
  if (!Number.isFinite(operation.duration) || operation.duration <= 0) {