@morshoto/framekit 0.1.0

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 (31) hide show
  1. package/README.md +67 -0
  2. package/bin/framekit.mjs +26 -0
  3. package/dist-package/adapters/final-cut/typescript/src/analyzers.js +116 -0
  4. package/dist-package/adapters/final-cut/typescript/src/assets.js +112 -0
  5. package/dist-package/adapters/final-cut/typescript/src/connection.js +379 -0
  6. package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +282 -0
  7. package/dist-package/adapters/final-cut/typescript/src/export.js +382 -0
  8. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +503 -0
  9. package/dist-package/adapters/final-cut/typescript/src/index.js +11 -0
  10. package/dist-package/adapters/final-cut/typescript/src/live.js +415 -0
  11. package/dist-package/adapters/final-cut/typescript/src/native-operation.js +18 -0
  12. package/dist-package/adapters/final-cut/typescript/src/native.js +3134 -0
  13. package/dist-package/adapters/final-cut/typescript/src/publisher.js +102 -0
  14. package/dist-package/adapters/final-cut/typescript/src/session.js +171 -0
  15. package/dist-package/apps/cli/src/main.js +130 -0
  16. package/dist-package/apps/mcp-server/src/main.js +146 -0
  17. package/dist-package/apps/mcp-server/src/server.js +617 -0
  18. package/dist-package/packages/runtime/src/capabilities.js +24 -0
  19. package/dist-package/packages/runtime/src/context/context-engine.js +142 -0
  20. package/dist-package/packages/runtime/src/diff/diff.js +145 -0
  21. package/dist-package/packages/runtime/src/domain/types.js +1 -0
  22. package/dist-package/packages/runtime/src/editing/intent.js +83 -0
  23. package/dist-package/packages/runtime/src/index.js +8 -0
  24. package/dist-package/packages/runtime/src/runtime.js +890 -0
  25. package/dist-package/packages/runtime/src/snapshot-digest.js +24 -0
  26. package/dist-package/packages/runtime/src/speech/filler-removal.js +87 -0
  27. package/dist-package/packages/runtime/src/verification/verification.js +113 -0
  28. package/dist-package/packages/testkit/src/fixture-analyzers.js +39 -0
  29. package/dist-package/packages/testkit/src/in-memory-editor.js +520 -0
  30. package/dist-package/packages/testkit/src/index.js +2 -0
  31. package/package.json +64 -0
@@ -0,0 +1,24 @@
1
+ import { createHash } from "node:crypto";
2
+ /** Digest canonical editor content while deliberately excluding observation revisions and analysis. */
3
+ export function canonicalSnapshotDigest(snapshot) {
4
+ const canonical = {
5
+ projectId: snapshot.projectId,
6
+ projectName: snapshot.projectName,
7
+ timeline: snapshot.timeline,
8
+ media: snapshot.media.map(({ mediaId, source }) => ({ mediaId, source })),
9
+ };
10
+ return createHash("sha256").update(stableJson(canonical)).digest("hex");
11
+ }
12
+ function stableJson(value) {
13
+ if (value === null || typeof value !== "object")
14
+ return JSON.stringify(value);
15
+ if (Array.isArray(value))
16
+ return `[${value.map(stableJson).join(",")}]`;
17
+ const entries = Object.entries(value)
18
+ .filter(([, child]) => child !== undefined)
19
+ .sort(([left], [right]) => compareText(left, right));
20
+ return `{${entries.map(([key, child]) => `${JSON.stringify(key)}:${stableJson(child)}`).join(",")}}`;
21
+ }
22
+ function compareText(left, right) {
23
+ return left < right ? -1 : left > right ? 1 : 0;
24
+ }
@@ -0,0 +1,87 @@
1
+ export const DEFAULT_FILLER_CONFIDENCE = 0.92;
2
+ export const DEFAULT_PRESERVE_PAUSE_MS = 700;
3
+ export const DEFAULT_TARGET_PAUSE_MS = 500;
4
+ /** Resolve transcript fillers into conservative, exact timeline ranges. */
5
+ export function planFillerRemoval(words, selectedRange, options = {}) {
6
+ validateRange(selectedRange);
7
+ const confidenceThreshold = options.confidenceThreshold ?? DEFAULT_FILLER_CONFIDENCE;
8
+ const preservePauseMs = options.preservePauseMs ?? DEFAULT_PRESERVE_PAUSE_MS;
9
+ const targetPauseMs = options.targetPauseMs ?? DEFAULT_TARGET_PAUSE_MS;
10
+ validateOptions(confidenceThreshold, preservePauseMs, targetPauseMs);
11
+ const orderedWords = words
12
+ .map((word) => ({ ...word }))
13
+ .sort((left, right) => left.start - right.start || left.end - right.end);
14
+ for (let index = 0; index < orderedWords.length; index += 1) {
15
+ const word = orderedWords[index];
16
+ if (!word.text.trim() || !Number.isFinite(word.start) || !Number.isFinite(word.end)
17
+ || word.start < 0 || word.end <= word.start || !Number.isFinite(word.confidence)) {
18
+ throw new Error("ANALYSIS_INVALID: speech word boundaries or confidence");
19
+ }
20
+ const previous = orderedWords[index - 1];
21
+ if (previous && previous.end > word.start) {
22
+ throw new Error("ANALYSIS_INVALID: speech word boundaries overlap");
23
+ }
24
+ }
25
+ return orderedWords
26
+ .map((word, index) => ({ word, index }))
27
+ .filter(({ word }) => word.filler === true
28
+ && word.confidence >= confidenceThreshold
29
+ && word.start >= selectedRange.start
30
+ && word.end <= selectedRange.end)
31
+ .map(({ word, index }) => ({
32
+ word,
33
+ range: resolveSafeRange(orderedWords, index, word, preservePauseMs, targetPauseMs),
34
+ }))
35
+ .sort((left, right) => right.range.start - left.range.start);
36
+ }
37
+ function resolveSafeRange(words, index, word, preservePauseMs, targetPauseMs) {
38
+ let end = word.end;
39
+ const previous = words[index - 1];
40
+ const next = words[index + 1];
41
+ const hasAdjacentSpeech = previous?.filler !== true && next?.filler !== true;
42
+ const followingPauseMs = next ? (next.start - word.end) * 1000 : 0;
43
+ if (hasAdjacentSpeech && followingPauseMs > preservePauseMs) {
44
+ end += (followingPauseMs - targetPauseMs) / 1000;
45
+ }
46
+ return {
47
+ start: word.start,
48
+ end,
49
+ startTime: secondsToRational(word.start),
50
+ durationTime: secondsToRational(end - word.start),
51
+ };
52
+ }
53
+ function validateRange(range) {
54
+ if (!Number.isFinite(range.start) || !Number.isFinite(range.end)
55
+ || range.start < 0 || range.end <= range.start) {
56
+ throw new Error("INVALID_OPERATION: filler selection range must be positive");
57
+ }
58
+ }
59
+ function validateOptions(confidenceThreshold, preservePauseMs, targetPauseMs) {
60
+ if (!Number.isFinite(confidenceThreshold) || confidenceThreshold < 0 || confidenceThreshold > 1) {
61
+ throw new Error("INVALID_OPERATION: filler confidence threshold must be between 0 and 1");
62
+ }
63
+ if (!Number.isFinite(preservePauseMs) || preservePauseMs < 0
64
+ || !Number.isFinite(targetPauseMs) || targetPauseMs < 0 || targetPauseMs > preservePauseMs) {
65
+ throw new Error("INVALID_OPERATION: filler pause settings must be non-negative and target pause cannot exceed preserved pause");
66
+ }
67
+ }
68
+ function secondsToRational(seconds) {
69
+ const text = seconds.toFixed(6).replace(/0+$/, "").replace(/\.$/, "");
70
+ if (!text.includes("."))
71
+ return { value: text || "0", timescale: "1" };
72
+ const [whole, fraction = ""] = text.split(".");
73
+ let numerator = BigInt(`${whole}${fraction}`);
74
+ let denominator = 10n ** BigInt(fraction.length);
75
+ const divisor = greatestCommonDivisor(numerator < 0n ? -numerator : numerator, denominator);
76
+ numerator /= divisor;
77
+ denominator /= divisor;
78
+ return { value: String(numerator), timescale: String(denominator) };
79
+ }
80
+ function greatestCommonDivisor(left, right) {
81
+ while (right !== 0n) {
82
+ const remainder = left % right;
83
+ left = right;
84
+ right = remainder;
85
+ }
86
+ return left || 1n;
87
+ }
@@ -0,0 +1,113 @@
1
+ export class DefaultVerificationEngine {
2
+ async verify(transaction, policy) {
3
+ const checks = [
4
+ {
5
+ name: "timeline-valid",
6
+ passed: transaction.after.timeline.clips.every((clip) => clip.duration >= 0)
7
+ && transaction.after.timeline.clips.every((clip) => !clip.mediaId
8
+ || transaction.after.media.some((media) => media.mediaId === clip.mediaId)),
9
+ detail: "clip durations are valid and media references resolve",
10
+ },
11
+ {
12
+ name: "audio-state",
13
+ passed: audioStateIsValid(transaction),
14
+ detail: audioStateDetail(transaction),
15
+ },
16
+ {
17
+ name: "read-after-write",
18
+ passed: transaction.attemptedAfter.revision.sequence > transaction.before.revision.sequence,
19
+ detail: "the editor returned a newer revision after the write",
20
+ },
21
+ ];
22
+ if (policy.requireExpectedChange !== false) {
23
+ checks.push({
24
+ name: "expected-change",
25
+ passed: transaction.diff.added.length + transaction.diff.removed.length + transaction.diff.modified.length
26
+ + transaction.diff.markerChanges.length + transaction.diff.captionChanges.length
27
+ + transaction.diff.storyElementChanges.length + transaction.diff.mediaChanges.length > 0,
28
+ detail: "the canonical diff contains the requested project change",
29
+ });
30
+ }
31
+ if (policy.maxTruePeakDb !== undefined) {
32
+ const peaks = transaction.attemptedAfter.media
33
+ .map((media) => media.audio?.truePeakDb)
34
+ .filter((peak) => peak !== undefined);
35
+ const passed = peaks.length > 0 && peaks.every((peak) => peak <= policy.maxTruePeakDb);
36
+ checks.push({
37
+ name: "true-peak-limit",
38
+ passed,
39
+ detail: passed
40
+ ? `all measured peaks are at or below ${policy.maxTruePeakDb} dB`
41
+ : `a measured peak exceeds ${policy.maxTruePeakDb} dB`,
42
+ });
43
+ }
44
+ if (policy.targetLufs !== undefined) {
45
+ const tolerance = policy.loudnessToleranceDb ?? 0.5;
46
+ const loudness = transaction.attemptedAfter.media
47
+ .map((media) => media.audio?.integratedLufs)
48
+ .filter((value) => value !== undefined);
49
+ const passed = loudness.length > 0 && loudness.every((value) => Math.abs(value - policy.targetLufs) <= tolerance);
50
+ checks.push({
51
+ name: "integrated-loudness-target",
52
+ passed,
53
+ detail: passed
54
+ ? `all measured loudness values are within ${tolerance} dB of ${policy.targetLufs} LUFS`
55
+ : `a measured loudness value is outside ${tolerance} dB of ${policy.targetLufs} LUFS`,
56
+ });
57
+ }
58
+ if (policy.requireSpeechContinuity) {
59
+ const beforeSpeechClips = transaction.before.timeline.clips.filter((clip) => {
60
+ const media = transaction.before.media.find((candidate) => candidate.mediaId === clip.mediaId);
61
+ return Boolean(media?.speech);
62
+ });
63
+ const continuity = beforeSpeechClips.every((beforeClip) => {
64
+ const afterClip = transaction.attemptedAfter.timeline.clips.find((clip) => clip.id === beforeClip.id);
65
+ if (!afterClip)
66
+ return false;
67
+ const media = transaction.attemptedAfter.media.find((candidate) => candidate.mediaId === afterClip.mediaId);
68
+ return !media?.speech || media.speech.words.every((word) => word.end <= afterClip.duration);
69
+ });
70
+ checks.push({
71
+ name: "speech-continuity",
72
+ passed: continuity,
73
+ detail: continuity ? "speech words remain inside their clip bounds" : "a speech word would be clipped",
74
+ });
75
+ }
76
+ return { passed: checks.every((check) => check.passed), checks };
77
+ }
78
+ }
79
+ function audioStateIsValid(transaction) {
80
+ if (transaction.after.timeline.clips.some((clip) => {
81
+ const fadeIn = clip.fadeIn ?? 0;
82
+ const fadeOut = clip.fadeOut ?? 0;
83
+ return (clip.gainDb !== undefined && !Number.isFinite(clip.gainDb))
84
+ || !Number.isFinite(fadeIn)
85
+ || !Number.isFinite(fadeOut)
86
+ || fadeIn < 0
87
+ || fadeOut < 0
88
+ || fadeIn + fadeOut > clip.duration;
89
+ }))
90
+ return false;
91
+ return transaction.planned.every((operation) => {
92
+ if (operation.type === "set-gain") {
93
+ const clip = transaction.after.timeline.clips.find((candidate) => candidate.id === operation.clipId);
94
+ return clip?.gainDb === operation.gainDb;
95
+ }
96
+ if (operation.type === "timeline.audio.fades") {
97
+ const clip = transaction.after.timeline.clips.find((candidate) => candidate.id === operation.clipId);
98
+ return clip?.fadeIn === operation.fadeIn && clip.fadeOut === operation.fadeOut;
99
+ }
100
+ if (operation.type === "timeline.media.add" && operation.role === "music") {
101
+ const clip = transaction.after.timeline.clips.find((candidate) => candidate.id === operation.occurrenceId);
102
+ return clip?.start === operation.start
103
+ && clip.duration === operation.duration
104
+ && clip.track === operation.targetLane;
105
+ }
106
+ return true;
107
+ });
108
+ }
109
+ function audioStateDetail(transaction) {
110
+ return audioStateIsValid(transaction)
111
+ ? "music placement, duration, gain, and fades match the planned audio state"
112
+ : "music placement, duration, gain, or fades do not match the planned audio state";
113
+ }
@@ -0,0 +1,39 @@
1
+ export class FixtureSpeechAnalyzer {
2
+ async analyze(input, range) {
3
+ const speech = input.media.speech;
4
+ if (!speech)
5
+ throw new Error(`ANALYSIS_FAILED: no speech fixture for ${input.media.mediaId}`);
6
+ return {
7
+ words: filterRange(speech.words, range),
8
+ };
9
+ }
10
+ }
11
+ export class FixtureAudioAnalyzer {
12
+ async analyze(input, range) {
13
+ if (!input.media.audio)
14
+ throw new Error(`ANALYSIS_FAILED: no audio fixture for ${input.media.mediaId}`);
15
+ return { ...input.media.audio };
16
+ }
17
+ }
18
+ export class FixtureVisualAnalyzer {
19
+ async analyze(input, range) {
20
+ const visual = input.media.visual;
21
+ if (!visual)
22
+ throw new Error(`ANALYSIS_FAILED: no visual fixture for ${input.media.mediaId}`);
23
+ if (!range)
24
+ return structuredClone(visual);
25
+ return {
26
+ scenes: visual.scenes.filter((scene) => scene.end > range.start && scene.start < range.end).map((scene) => ({ ...scene })),
27
+ subjects: visual.subjects.filter((subject) => (subject.end ?? Number.POSITIVE_INFINITY) > range.start && (subject.start ?? 0) < range.end).map((subject) => ({ ...subject })),
28
+ keyframes: visual.keyframes.filter((keyframe) => keyframe.time >= range.start && keyframe.time <= range.end).map((keyframe) => ({ ...keyframe, labels: keyframe.labels ? [...keyframe.labels] : undefined })),
29
+ motion: visual.motion ? { ...visual.motion } : undefined,
30
+ };
31
+ }
32
+ }
33
+ function filterRange(words, range) {
34
+ if (!range)
35
+ return words.map((word) => ({ ...word }));
36
+ return words
37
+ .filter((word) => word.end > range.start && word.start < range.end)
38
+ .map((word) => ({ ...word }));
39
+ }