@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,8 +1,12 @@
1
1
  import { readFileSync } from "node:fs";
2
- import { dirname, join } from "node:path";
2
+ import { dirname, isAbsolute, join, resolve } from "node:path";
3
3
  import { fileURLToPath } from "node:url";
4
4
  const FRAMEKIT_PACKAGE_NAME = "@morshoto/framekit";
5
5
  export const FRAMEKIT_VERSION = readFramekitVersion();
6
+ export const FRAMEKIT_BUILD_FINGERPRINT = Object.freeze({
7
+ version: FRAMEKIT_VERSION,
8
+ commit: readFramekitCommit(),
9
+ });
6
10
  function readFramekitVersion() {
7
11
  let directory = dirname(fileURLToPath(import.meta.url));
8
12
  while (true) {
@@ -32,3 +36,107 @@ function isMissingFile(error) {
32
36
  return false;
33
37
  return error.code === "ENOENT";
34
38
  }
39
+ function readFramekitCommit() {
40
+ const configured = process.env.FRAMEKIT_BUILD_COMMIT?.trim();
41
+ if (configured)
42
+ return configured;
43
+ const repositoryRoot = findRepositoryRoot(dirname(fileURLToPath(import.meta.url)));
44
+ if (!repositoryRoot)
45
+ return "unknown";
46
+ try {
47
+ const gitEntry = join(repositoryRoot, ".git");
48
+ const gitDirectory = readGitDirectory(gitEntry);
49
+ const head = readFileSync(join(gitDirectory, "HEAD"), "utf8").trim();
50
+ if (/^[0-9a-f]{7,64}$/i.test(head))
51
+ return head;
52
+ if (!head.startsWith("ref: "))
53
+ return "unknown";
54
+ const ref = head.slice("ref: ".length).trim();
55
+ if (!ref)
56
+ return "unknown";
57
+ const commonDirectory = readCommonDirectory(gitDirectory);
58
+ const refCandidates = [join(gitDirectory, ref)];
59
+ if (commonDirectory)
60
+ refCandidates.push(join(commonDirectory, ref));
61
+ for (const refPath of refCandidates) {
62
+ try {
63
+ const commit = readFileSync(refPath, "utf8").trim();
64
+ if (/^[0-9a-f]{7,64}$/i.test(commit))
65
+ return commit;
66
+ }
67
+ catch (error) {
68
+ if (!isMissingFile(error))
69
+ throw error;
70
+ }
71
+ }
72
+ if (commonDirectory) {
73
+ const packedRefs = readFileSync(join(commonDirectory, "packed-refs"), "utf8");
74
+ const packedRef = packedRefs
75
+ .split("\n")
76
+ .map((line) => line.trim().split(" "))
77
+ .find(([commit, name]) => name === ref && /^[0-9a-f]{7,64}$/i.test(commit ?? ""));
78
+ if (packedRef?.[0])
79
+ return packedRef[0];
80
+ }
81
+ }
82
+ catch (error) {
83
+ if (!isMissingFile(error))
84
+ return "unknown";
85
+ }
86
+ return "unknown";
87
+ }
88
+ function findRepositoryRoot(start) {
89
+ let directory = start;
90
+ while (true) {
91
+ if (isGitEntry(join(directory, ".git")))
92
+ return directory;
93
+ const parent = dirname(directory);
94
+ if (parent === directory)
95
+ return undefined;
96
+ directory = parent;
97
+ }
98
+ }
99
+ function isGitEntry(path) {
100
+ try {
101
+ readFileSync(path, "utf8");
102
+ return true;
103
+ }
104
+ catch (error) {
105
+ if (!isMissingFile(error))
106
+ return true;
107
+ return false;
108
+ }
109
+ }
110
+ function readGitDirectory(gitEntry) {
111
+ let content;
112
+ try {
113
+ content = readFileSync(gitEntry, "utf8").trim();
114
+ }
115
+ catch (error) {
116
+ if (isDirectoryError(error))
117
+ return gitEntry;
118
+ throw error;
119
+ }
120
+ if (!content.startsWith("gitdir: "))
121
+ return gitEntry;
122
+ const configured = content.slice("gitdir: ".length).trim();
123
+ return isAbsolute(configured) ? configured : resolve(dirname(gitEntry), configured);
124
+ }
125
+ function readCommonDirectory(gitDirectory) {
126
+ try {
127
+ const configured = readFileSync(join(gitDirectory, "commondir"), "utf8").trim();
128
+ if (!configured)
129
+ return undefined;
130
+ return isAbsolute(configured) ? configured : resolve(gitDirectory, configured);
131
+ }
132
+ catch (error) {
133
+ if (!isMissingFile(error))
134
+ throw error;
135
+ return undefined;
136
+ }
137
+ }
138
+ function isDirectoryError(error) {
139
+ if (!error || typeof error !== "object" || !("code" in error))
140
+ return false;
141
+ return error.code === "EISDIR";
142
+ }
@@ -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
@@ -160,9 +161,7 @@ export class MediaAnalysisService {
160
161
  return findMedia(project, mediaId);
161
162
  }
162
163
  async searchMedia(query) {
163
- const project = await this.project.inspectProject();
164
- const normalized = query.trim().toLowerCase();
165
- return project.media.filter((media) => media.mediaId.toLowerCase().includes(normalized) || media.source.toLowerCase().includes(normalized));
164
+ return this.project.searchMedia(query);
166
165
  }
167
166
  async indexMedia(query = {}) {
168
167
  const project = await this.project.inspectProject();
@@ -1,4 +1,5 @@
1
- import { withCapabilityFamilies } from "../capabilities.js";
1
+ import { CapabilityUnavailableError } from "../domain/capabilities.js";
2
+ import { withCanonicalTimelineMode, withCapabilityFamilies } from "../capabilities.js";
2
3
  import { isWithinClip, parseRational, rationalDifferenceSeconds } from "../timeline/rational-time.js";
3
4
  export class ProjectService {
4
5
  adapter;
@@ -10,6 +11,14 @@ export class ProjectService {
10
11
  this.options = options;
11
12
  }
12
13
  async inspectProject() {
14
+ const identity = await this.adapter.getIdentity();
15
+ const capabilities = withCanonicalTimelineMode(withCapabilityFamilies(await this.adapter.getCapabilities(), {
16
+ backend: identity.backend,
17
+ }));
18
+ const projectRead = capabilities.families.canonicalDocument.read;
19
+ if (!projectRead.available) {
20
+ throw new CapabilityUnavailableError("project.inspect", "canonicalDocument.read", projectRead);
21
+ }
13
22
  return this.context.inspectProject();
14
23
  }
15
24
  async inspectTimeline() {
@@ -20,7 +29,9 @@ export class ProjectService {
20
29
  if (!this.adapter.getManagedArtifact) {
21
30
  throw new Error("CAPABILITY_UNAVAILABLE: managed FCPXML artifact");
22
31
  }
23
- return this.adapter.getManagedArtifact();
32
+ const artifact = await this.adapter.getManagedArtifact();
33
+ const digest = await this.adapter.getManagedArtifactDigest?.();
34
+ return digest ? { ...artifact, digest } : artifact;
24
35
  }
25
36
  async captureFrame(position, options = {}) {
26
37
  const exactPosition = parseRational(position, "INVALID_TIMELINE_POSITION");
@@ -67,16 +78,28 @@ export class ProjectService {
67
78
  };
68
79
  }
69
80
  async listProjects() {
70
- const capabilities = await this.adapter.getCapabilities();
81
+ const capabilities = await this.adapter.getCapabilities({ probeCanonicalSnapshot: false });
71
82
  if (!capabilities.editor.projectCatalogRead || !this.adapter.listProjects) {
72
- throw new Error("CAPABILITY_UNAVAILABLE: editor project catalog");
83
+ const identity = await this.adapter.getIdentity();
84
+ throw new CapabilityUnavailableError("project.list", "editor.projectCatalogRead", {
85
+ available: false,
86
+ backend: identity.backend,
87
+ guarantee: "none",
88
+ unavailableReason: "project catalog is unavailable",
89
+ });
73
90
  }
74
91
  return this.adapter.listProjects();
75
92
  }
76
93
  async selectProject(selection) {
77
94
  const capabilities = await this.adapter.getCapabilities();
78
95
  if (!capabilities.editor.projectSelection || !this.adapter.selectProject) {
79
- throw new Error("CAPABILITY_UNAVAILABLE: editor project selection");
96
+ const identity = await this.adapter.getIdentity();
97
+ throw new CapabilityUnavailableError("project.select", "editor.projectSelection", {
98
+ available: false,
99
+ backend: identity.backend,
100
+ guarantee: "none",
101
+ unavailableReason: "project selection is unavailable",
102
+ });
80
103
  }
81
104
  if (!selection.projectId.trim())
82
105
  throw new Error("INVALID_PROJECT_SELECTION: projectId is required");
@@ -85,9 +108,9 @@ export class ProjectService {
85
108
  }
86
109
  return this.adapter.selectProject(selection);
87
110
  }
88
- async inspectEditor() {
111
+ async inspectEditor(options = {}) {
89
112
  const identity = await this.adapter.getIdentity();
90
- const capabilities = withCapabilityFamilies(await this.adapter.getCapabilities(), { backend: identity.backend });
113
+ const capabilities = withCapabilityFamilies(await this.adapter.getCapabilities(options), { backend: identity.backend });
91
114
  const speechAnalyzer = this.options.speechAnalyzer;
92
115
  const speechTranscribe = capabilities.analyzers.speechTranscribe
93
116
  || (speechAnalyzer ? speechAnalyzer.capabilities?.transcription ?? true : false);
@@ -130,6 +153,22 @@ export class ProjectService {
130
153
  const assets = await this.context.listAssets(query);
131
154
  return assets.filter((asset) => matchesAssetQuery(asset, query));
132
155
  }
156
+ async searchMedia(query) {
157
+ const identity = await this.adapter.getIdentity();
158
+ const capabilities = withCapabilityFamilies(await this.adapter.getCapabilities(), {
159
+ backend: identity.backend,
160
+ });
161
+ const mediaObservation = capabilities.families.observation.media;
162
+ if (!mediaObservation.available) {
163
+ throw new CapabilityUnavailableError("media.search", "observation.media", mediaObservation);
164
+ }
165
+ if (capabilities.editor.backgroundMediaDiscovery && this.adapter.listMedia) {
166
+ return this.adapter.listMedia({ query });
167
+ }
168
+ const project = await this.inspectProject();
169
+ const normalized = query.trim().toLowerCase();
170
+ return project.media.filter((media) => media.mediaId.toLowerCase().includes(normalized) || media.source.toLowerCase().includes(normalized));
171
+ }
133
172
  }
134
173
  function matchesAssetQuery(asset, query) {
135
174
  if (!query)
@@ -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);
@@ -1,25 +1,34 @@
1
1
  import { CAPABILITY_SCHEMA_VERSION } from "./domain/capabilities.js";
2
2
  export function canonicalTimelineMode(capabilities) {
3
3
  const editor = capabilities.editor;
4
- const hasExplicitTargeting = Boolean(editor.projectCatalogRead && editor.projectSelection);
5
- if (editor.projectRead
6
- && editor.timelineSnapshotRead
7
- && hasExplicitTargeting
4
+ const hasCanonicalProjectRead = canonicalProjectReadAvailable(editor);
5
+ if (hasCanonicalProjectRead
8
6
  && editor.timelineWrite
9
7
  && editor.readAfterWrite
10
8
  && editor.rollback) {
11
9
  return "canonical-write";
12
10
  }
13
- if (editor.projectRead && editor.timelineSnapshotRead && hasExplicitTargeting)
11
+ if (hasCanonicalProjectRead)
14
12
  return "canonical-read";
15
13
  return "metadata-only";
16
14
  }
15
+ export function projectSelectionMode(editor) {
16
+ return editor.projectSelectionMode
17
+ ?? (editor.projectSelection ? "background-capable" : "unavailable");
18
+ }
19
+ function canonicalProjectReadAvailable(editor) {
20
+ return Boolean(editor.projectRead
21
+ && editor.timelineSnapshotRead
22
+ && editor.projectCatalogRead);
23
+ }
17
24
  export function withCanonicalTimelineMode(capabilities) {
18
25
  const normalized = {
19
26
  ...capabilities,
20
27
  editor: {
21
28
  ...capabilities.editor,
29
+ projectRead: canonicalProjectReadAvailable(capabilities.editor),
22
30
  canonicalTimelineMode: canonicalTimelineMode(capabilities),
31
+ projectSelectionMode: projectSelectionMode(capabilities.editor),
23
32
  },
24
33
  };
25
34
  const previous = capabilities.families;
@@ -28,6 +37,8 @@ export function withCanonicalTimelineMode(capabilities) {
28
37
  const canonicalRead = normalized.editor.canonicalTimelineMode === "canonical-read"
29
38
  || normalized.editor.canonicalTimelineMode === "canonical-write";
30
39
  const canonicalWrite = normalized.editor.canonicalTimelineMode === "canonical-write";
40
+ const backgroundLibraryInspection = normalized.editor.backgroundLibraryInspection
41
+ ?? previous.observation.library.available;
31
42
  const compositeTransactions = Boolean(normalized.editor.compositeTransactions
32
43
  && normalized.editor.timelineSnapshotRead
33
44
  && normalized.editor.readAfterWrite
@@ -38,6 +49,8 @@ export function withCanonicalTimelineMode(capabilities) {
38
49
  nativeBackend: previous.native.selectionWrite.backend,
39
50
  publishingBackend: previous.publishing.projectCreation.backend,
40
51
  exportBackend: previous.export.timeline.backend,
52
+ backgroundExportBackend: previous.export.background.backend,
53
+ externalExportBackend: previous.export.external.backend,
41
54
  analyzerBackends: {
42
55
  speechTranscribe: previous.analyzers.speechTranscribe.backend,
43
56
  speechVad: previous.analyzers.speechVad.backend,
@@ -46,6 +59,14 @@ export function withCanonicalTimelineMode(capabilities) {
46
59
  visualTrack: previous.analyzers.visualTrack.backend,
47
60
  },
48
61
  connection: previous.connection.status,
62
+ observation: {
63
+ media: normalized.editor.timelineSnapshotRead && normalized.editor.projectRead
64
+ || normalized.editor.backgroundMediaDiscovery
65
+ ? previous.observation.media
66
+ : false,
67
+ assets: normalized.editor.assetDiscovery ? previous.observation.assets : false,
68
+ library: backgroundLibraryInspection ? previous.observation.library : false,
69
+ },
49
70
  canonicalDocument: {
50
71
  read: refreshDescriptor(canonicalRead, previous.canonicalDocument.read, "canonical-read", "canonical timeline reads are unavailable"),
51
72
  write: refreshDescriptor(canonicalWrite, previous.canonicalDocument.write, "canonical-write", "canonical timeline writes are unavailable"),
@@ -56,6 +77,7 @@ export function withCanonicalTimelineMode(capabilities) {
56
77
  titlePlacement: refreshDescriptor(Boolean(normalized.editor.titlePlacement), previous.editing.titlePlacement, "verified", "title placement is unavailable"),
57
78
  pictureInPicture: previous.editing.pictureInPicture,
58
79
  masking: previous.editing.masking,
80
+ personCutout: previous.editing.personCutout,
59
81
  },
60
82
  native: nativeAvailability(previous.native),
61
83
  publishing: previous.publishing.projectCreation,
@@ -65,6 +87,8 @@ export function withCanonicalTimelineMode(capabilities) {
65
87
  function refreshDescriptor(available, previous, guarantee, unavailableReason) {
66
88
  if (available && previous.available)
67
89
  return previous;
90
+ if (!available && !previous.available)
91
+ return previous;
68
92
  return descriptorFrom(available, previous.backend, guarantee, unavailableReason);
69
93
  }
70
94
  /**
@@ -74,12 +98,20 @@ function refreshDescriptor(available, previous, guarantee, unavailableReason) {
74
98
  export function withCapabilityFamilies(capabilities, options = {}) {
75
99
  const previous = capabilities.families;
76
100
  const backend = options.backend ?? previous?.connection.status.backend ?? "unknown";
101
+ const configuredLibrary = options.observation?.library;
102
+ const backgroundLibraryInspection = capabilities.editor.backgroundLibraryInspection
103
+ ?? (typeof configuredLibrary === "boolean" ? configuredLibrary : configuredLibrary?.available)
104
+ ?? previous?.observation.library.available
105
+ ?? false;
77
106
  const normalized = {
78
107
  ...capabilities,
79
108
  schemaVersion: CAPABILITY_SCHEMA_VERSION,
80
109
  editor: {
81
110
  ...capabilities.editor,
111
+ projectRead: canonicalProjectReadAvailable(capabilities.editor),
82
112
  canonicalTimelineMode: canonicalTimelineMode(capabilities),
113
+ projectSelectionMode: projectSelectionMode(capabilities.editor),
114
+ backgroundLibraryInspection,
83
115
  },
84
116
  };
85
117
  const editor = normalized.editor;
@@ -105,7 +137,15 @@ export function withCapabilityFamilies(capabilities, options = {}) {
105
137
  },
106
138
  observation: {
107
139
  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"),
140
+ media: descriptorFrom(options.observation?.media ?? (editor.timelineSnapshotRead && editor.projectRead
141
+ ? previous?.observation.media ?? true
142
+ : editor.backgroundMediaDiscovery
143
+ ? previous?.observation.media ?? { available: true, backend, guarantee: "observed" }
144
+ : false), backend, editor.timelineSnapshotRead && editor.projectRead ? "canonical-read" : "observed", "media observation is unavailable"),
145
+ assets: descriptorFrom(options.observation?.assets ?? (editor.assetDiscovery ? previous?.observation.assets ?? true : false), backend, "observed", "asset discovery is unavailable"),
146
+ library: descriptorFrom(options.observation?.library ?? (backgroundLibraryInspection
147
+ ? previous?.observation.library ?? true
148
+ : false), backend, "observed", "background library inspection is unavailable"),
109
149
  },
110
150
  canonicalDocument: {
111
151
  read: descriptorFrom(canonicalDocument.read ?? (editor.canonicalTimelineMode === "canonical-read"
@@ -119,7 +159,9 @@ export function withCapabilityFamilies(capabilities, options = {}) {
119
159
  projectCreation: descriptorFrom(options.publishing ?? previous?.publishing.projectCreation ?? false, options.publishingBackend ?? backend, "verified", "new project publishing is unavailable"),
120
160
  },
121
161
  export: {
122
- timeline: descriptorFrom(options.export ?? previous?.export.timeline ?? false, options.exportBackend ?? backend, "verified", "timeline export is unavailable"),
162
+ timeline: exportDescriptor(options.export ?? previous?.export.timeline ?? false, options.exportBackend ?? backend, "verified", "timeline export is unavailable", "headed-native"),
163
+ background: exportDescriptor(options.backgroundExport ?? previous?.export.background ?? false, options.backgroundExportBackend ?? previous?.export.background?.backend ?? backend, "verified", "background rendering is unavailable", "background-native"),
164
+ external: exportDescriptor(options.externalExport ?? previous?.export.external ?? editor.externalRender ?? false, options.externalExportBackend ?? previous?.export.external?.backend ?? backend, "verified", "external rendering is unavailable", "external-rendered"),
123
165
  },
124
166
  analyzers: {
125
167
  speechTranscribe: analyzerDescriptor(capabilities.analyzers.speechTranscribe, analyzerBackend("speechTranscribe"), "speech transcription"),
@@ -135,8 +177,9 @@ function editingFamily(editor, overrides, backend) {
135
177
  return {
136
178
  compositeTransactions: descriptorFrom(overrides.compositeTransactions ?? Boolean(editor.compositeTransactions), backend, "verified", "composite editing transactions are unavailable"),
137
179
  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"),
180
+ pictureInPicture: descriptorFrom(overrides.pictureInPicture ?? Boolean(editor.pictureInPicture), backend, "verified", "picture-in-picture editing is unavailable"),
181
+ masking: descriptorFrom(overrides.masking ?? Boolean(editor.masking), backend, "verified", "masking is unavailable"),
182
+ personCutout: descriptorFrom(overrides.personCutout ?? Boolean(editor.personCutout), backend, "verified", "person cutout is unavailable"),
140
183
  };
141
184
  }
142
185
  export function createCapabilityPreflight(identity, capabilities, options = {}) {
@@ -170,6 +213,13 @@ function descriptorFrom(value, backend, guarantee, unavailableReason) {
170
213
  ? { available: true, backend, guarantee }
171
214
  : { available: false, backend, guarantee: "none", unavailableReason };
172
215
  }
216
+ function exportDescriptor(value, backend, guarantee, unavailableReason, evidenceTier) {
217
+ if (typeof value !== "boolean")
218
+ return value;
219
+ return value
220
+ ? { available: true, backend, guarantee, evidenceTier }
221
+ : { available: false, backend, guarantee: "none", unavailableReason };
222
+ }
173
223
  function analyzerDescriptor(available, backend, operation) {
174
224
  return descriptorFrom(available, backend, "verified", `${operation} is unavailable`);
175
225
  }
@@ -188,12 +238,15 @@ function nativeFamily(native, backend) {
188
238
  "mediaAppend",
189
239
  "mediaInsert",
190
240
  "titlePlacement",
241
+ "titleDiscovery",
191
242
  "timelineFocus",
192
243
  "projectCreation",
193
244
  "clipInsertion",
194
245
  "clipMovement",
195
246
  "transitionDiscovery",
196
247
  "transitionPlacement",
248
+ "pictureInPicture",
249
+ "masking",
197
250
  ];
198
251
  return Object.fromEntries(nativeOperations.map((operation) => [
199
252
  operation,
@@ -0,0 +1,159 @@
1
+ import { parseRational } from "../timeline/rational-time.js";
2
+ export function reconcileProjectCatalog(catalog, options) {
3
+ validateProjectCatalog(catalog);
4
+ if (options.before)
5
+ validateLiveState(options.before);
6
+ if (options.after)
7
+ validateLiveState(options.after);
8
+ const state = options.after ?? options.before;
9
+ const beforeRevision = options.before?.revision;
10
+ const afterRevision = options.after?.revision;
11
+ const project = state?.project
12
+ ? matchIdentity(catalog.projects, state.project.id, state.project.name, (candidate) => candidate.id, (candidate) => candidate.name)
13
+ : unresolvedIdentity();
14
+ const projectDescriptor = project.catalogId
15
+ ? catalog.projects.find((candidate) => candidate.id === project.catalogId)
16
+ : undefined;
17
+ const sequence = state?.sequence && projectDescriptor
18
+ ? matchIdentity(projectDescriptor.sequences, state.sequence.id, state.sequence.name, (candidate) => candidate.id, (candidate) => candidate.name)
19
+ : unresolvedIdentity(state?.sequence?.id);
20
+ let status = project.method === "stable-id"
21
+ && sequence.method === "stable-id"
22
+ ? "matched"
23
+ : "unresolved";
24
+ let reason = status === "unresolved" ? "stable project and sequence IDs could not be reconciled" : undefined;
25
+ if (status === "matched"
26
+ && ((catalog.activeProjectId !== undefined && catalog.activeProjectId !== project.catalogId)
27
+ || (catalog.activeSequenceId !== undefined && catalog.activeSequenceId !== sequence.catalogId))) {
28
+ status = "stale";
29
+ reason = "background active target differs from live target";
30
+ }
31
+ if (options.before && options.after) {
32
+ if (options.after.revision.sequence < options.before.revision.sequence) {
33
+ throw new Error("PROJECT_CATALOG_INVALID: live revision sequence regressed");
34
+ }
35
+ if (!sameTarget(options.before, options.after)) {
36
+ status = "stale";
37
+ reason = "live target changed during project catalog reconciliation";
38
+ }
39
+ else if (!sameRevision(options.before.revision, options.after.revision)) {
40
+ status = "stale";
41
+ reason = "live revision changed during project catalog reconciliation";
42
+ }
43
+ }
44
+ const result = structuredClone(catalog);
45
+ if (status === "matched" && state?.project && state.sequence) {
46
+ result.activeProjectId = project.catalogId;
47
+ result.activeSequenceId = sequence.catalogId;
48
+ }
49
+ else {
50
+ delete result.activeProjectId;
51
+ delete result.activeSequenceId;
52
+ }
53
+ result.provenance = {
54
+ catalog: { ...options.provenance.catalog },
55
+ ...(state && options.provenance.live
56
+ ? { live: { ...options.provenance.live, state: structuredClone(state) } }
57
+ : {}),
58
+ reconciliation: {
59
+ status,
60
+ project,
61
+ sequence,
62
+ ...(beforeRevision ? { beforeRevision: { ...beforeRevision } } : {}),
63
+ ...(afterRevision ? { afterRevision: { ...afterRevision } } : {}),
64
+ ...(reason ? { reason } : {}),
65
+ },
66
+ selection: { ...options.provenance.selection },
67
+ };
68
+ return result;
69
+ }
70
+ function matchIdentity(values, liveId, liveName, id, name) {
71
+ const stable = values.find((value) => id(value) === liveId);
72
+ if (stable)
73
+ return { method: "stable-id", catalogId: id(stable), liveId };
74
+ const named = values.filter((value) => name(value) === liveName);
75
+ if (named.length === 1)
76
+ return { method: "name-only", catalogId: id(named[0]), liveId };
77
+ return unresolvedIdentity(liveId);
78
+ }
79
+ function unresolvedIdentity(liveId) {
80
+ return { method: "unresolved", ...(liveId ? { liveId } : {}) };
81
+ }
82
+ function sameTarget(left, right) {
83
+ return left.project?.id === right.project?.id
84
+ && left.sequence?.id === right.sequence?.id;
85
+ }
86
+ function sameRevision(left, right) {
87
+ return left.id === right.id && left.sequence === right.sequence;
88
+ }
89
+ export function validateProjectCatalog(catalog) {
90
+ if (!Array.isArray(catalog.projects))
91
+ throw new Error("PROJECT_CATALOG_INVALID: projects must be an array");
92
+ const projectIds = new Set();
93
+ for (const project of catalog.projects) {
94
+ if (!project || typeof project !== "object")
95
+ throw new Error("PROJECT_CATALOG_INVALID: project must be an object");
96
+ if (!project.id.trim())
97
+ throw new Error("PROJECT_CATALOG_INVALID: project id must be non-empty");
98
+ if (projectIds.has(project.id))
99
+ throw new Error(`PROJECT_CATALOG_INVALID: duplicate project id ${project.id}`);
100
+ projectIds.add(project.id);
101
+ if (!project.name.trim())
102
+ throw new Error(`PROJECT_CATALOG_INVALID: project ${project.id} name must be non-empty`);
103
+ if (!Array.isArray(project.sequences))
104
+ throw new Error(`PROJECT_CATALOG_INVALID: project ${project.id} sequences must be an array`);
105
+ const sequenceIds = new Set();
106
+ for (const sequence of project.sequences) {
107
+ if (!sequence || typeof sequence !== "object") {
108
+ throw new Error(`PROJECT_CATALOG_INVALID: sequence in project ${project.id} must be an object`);
109
+ }
110
+ if (!sequence.id.trim())
111
+ throw new Error(`PROJECT_CATALOG_INVALID: sequence in project ${project.id} id must be non-empty`);
112
+ if (sequenceIds.has(sequence.id))
113
+ throw new Error(`PROJECT_CATALOG_INVALID: duplicate sequence id ${sequence.id} in project ${project.id}`);
114
+ sequenceIds.add(sequence.id);
115
+ if (!sequence.name.trim())
116
+ throw new Error(`PROJECT_CATALOG_INVALID: sequence ${sequence.id} name must be non-empty`);
117
+ }
118
+ }
119
+ if (catalog.activeProjectId !== undefined && !projectIds.has(catalog.activeProjectId)) {
120
+ throw new Error(`PROJECT_CATALOG_INVALID: active project ${catalog.activeProjectId} is absent from the catalog`);
121
+ }
122
+ if (catalog.activeSequenceId !== undefined) {
123
+ const activeProject = catalog.projects.find(({ id }) => id === catalog.activeProjectId);
124
+ if (!activeProject?.sequences.some(({ id }) => id === catalog.activeSequenceId)) {
125
+ throw new Error(`PROJECT_CATALOG_INVALID: active sequence ${catalog.activeSequenceId} is absent from the active project`);
126
+ }
127
+ }
128
+ }
129
+ function validateLiveState(state) {
130
+ validateRevision(state.revision);
131
+ if (state.sequence) {
132
+ validateRational(state.sequence.startTime, "live sequence start time");
133
+ validateRational(state.sequence.duration, "live sequence duration");
134
+ validateRational(state.sequence.frameDuration, "live sequence frame duration");
135
+ }
136
+ if (state.playheadTime)
137
+ validateRational(state.playheadTime, "live playhead time");
138
+ if (state.sequenceTimeRange) {
139
+ validateRational(state.sequenceTimeRange.start, "live sequence range start");
140
+ validateRational(state.sequenceTimeRange.duration, "live sequence range duration");
141
+ }
142
+ }
143
+ function validateRevision(revision) {
144
+ if (!revision.id.trim())
145
+ throw new Error("PROJECT_CATALOG_INVALID: live revision id must be non-empty");
146
+ if (!Number.isInteger(revision.sequence) || revision.sequence < 0) {
147
+ throw new Error("PROJECT_CATALOG_INVALID: live revision sequence must be a non-negative integer");
148
+ }
149
+ if (!revision.timestamp.trim())
150
+ throw new Error("PROJECT_CATALOG_INVALID: live revision timestamp must be non-empty");
151
+ }
152
+ function validateRational(value, field) {
153
+ try {
154
+ parseRational(value, "PROJECT_CATALOG_INVALID");
155
+ }
156
+ catch {
157
+ throw new Error(`PROJECT_CATALOG_INVALID: ${field} must use an integer value and positive timescale`);
158
+ }
159
+ }
@@ -1 +1,34 @@
1
1
  export const CAPABILITY_SCHEMA_VERSION = 1;
2
+ export class CapabilityUnavailableError extends Error {
3
+ operation;
4
+ capability;
5
+ code = "CAPABILITY_UNAVAILABLE";
6
+ available = false;
7
+ backend;
8
+ guarantee = "none";
9
+ unavailableReason;
10
+ constructor(operation, capability, descriptor) {
11
+ const unavailableReason = descriptor.unavailableReason ?? `${capability} is unavailable`;
12
+ super(`CAPABILITY_UNAVAILABLE: ${operation} requires ${capability}: ${unavailableReason}`);
13
+ this.operation = operation;
14
+ this.capability = capability;
15
+ this.name = "CapabilityUnavailableError";
16
+ this.backend = descriptor.backend;
17
+ this.unavailableReason = unavailableReason;
18
+ }
19
+ toJSON() {
20
+ return {
21
+ code: this.code,
22
+ message: `${this.operation} requires ${this.capability}`,
23
+ operation: this.operation,
24
+ capability: this.capability,
25
+ available: this.available,
26
+ backend: this.backend,
27
+ guarantee: this.guarantee,
28
+ unavailableReason: this.unavailableReason,
29
+ };
30
+ }
31
+ }
32
+ export function serializeCapabilityUnavailableError(error) {
33
+ return error instanceof CapabilityUnavailableError ? error.toJSON() : undefined;
34
+ }
@@ -1 +1,14 @@
1
- export {};
1
+ export function createProjectSelectionResult(catalog, requestedTarget, observedRevision) {
2
+ if (!catalog.activeProjectId || !catalog.activeSequenceId) {
3
+ throw new Error("TARGET_MISMATCH: project selection did not produce an active target");
4
+ }
5
+ return {
6
+ ...catalog,
7
+ requestedTarget: { ...requestedTarget },
8
+ observedActiveTarget: {
9
+ projectId: catalog.activeProjectId,
10
+ sequenceId: catalog.activeSequenceId,
11
+ },
12
+ observedRevision: { ...observedRevision },
13
+ };
14
+ }