@morshoto/framekit 0.1.14 → 0.1.17
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.
- package/dist-package/adapters/final-cut/typescript/src/background-materialization.js +28 -0
- package/dist-package/adapters/final-cut/typescript/src/canonical.js +144 -35
- package/dist-package/adapters/final-cut/typescript/src/connection.js +8 -5
- package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +36 -7
- package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +21 -7
- package/dist-package/adapters/final-cut/typescript/src/index.js +2 -0
- package/dist-package/adapters/final-cut/typescript/src/live.js +56 -1
- package/dist-package/adapters/final-cut/typescript/src/native.js +311 -20
- package/dist-package/adapters/final-cut/typescript/src/pasteboard-snapshot.js +312 -0
- package/dist-package/adapters/final-cut/typescript/src/publisher.js +68 -8
- package/dist-package/adapters/final-cut/typescript/src/sqlite-wal-observation.js +263 -0
- package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +179 -25
- package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.js +62 -0
- package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +551 -0
- package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +181 -0
- package/dist-package/adapters/headless/typescript/src/index.js +3 -0
- package/dist-package/apps/mcp-server/src/headless-projects.js +370 -0
- package/dist-package/apps/mcp-server/src/headless-sessions.js +3 -0
- package/dist-package/apps/mcp-server/src/main.js +28 -4
- package/dist-package/apps/mcp-server/src/materialization-jobs.js +233 -4
- package/dist-package/apps/mcp-server/src/readback-policy.js +26 -0
- package/dist-package/apps/mcp-server/src/routing.js +134 -5
- package/dist-package/apps/mcp-server/src/server.js +311 -34
- package/dist-package/packages/runtime/src/application/local-media.js +157 -0
- package/dist-package/packages/runtime/src/application/media-analysis-service.js +347 -27
- package/dist-package/packages/runtime/src/application/project-store.js +234 -0
- package/dist-package/packages/runtime/src/application/project-transactions.js +227 -0
- package/dist-package/packages/runtime/src/application/semantic-media-index-store.js +86 -0
- package/dist-package/packages/runtime/src/index.js +7 -0
- package/dist-package/packages/runtime/src/planning/rough-cut.js +103 -7
- package/dist-package/packages/runtime/src/render/render-and-verify.js +126 -0
- package/dist-package/packages/runtime/src/render/render-contract.js +146 -0
- package/dist-package/packages/runtime/src/runtime.js +5 -2
- package/dist-package/packages/runtime/src/timeline/editing-session.js +277 -9
- package/dist-package/packages/runtime/src/timeline/fast-observation.js +141 -0
- package/package.json +2 -1
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { createHash } from "node:crypto";
|
|
2
2
|
import { addRationalTimes } from "./rational-time.js";
|
|
3
3
|
import { parseRational } from "./rational-time.js";
|
|
4
|
+
import { subtractRationalTimes } from "./rational-time.js";
|
|
4
5
|
import { reconcileTimelineIr } from "./drift-reconciliation.js";
|
|
5
6
|
export const TIMELINE_IR_SCHEMA_VERSION = 1;
|
|
6
7
|
export class EditingSession {
|
|
@@ -70,13 +71,13 @@ export class EditingSession {
|
|
|
70
71
|
after,
|
|
71
72
|
operations: structuredClone(operations),
|
|
72
73
|
...changed,
|
|
73
|
-
state:
|
|
74
|
+
state: changedTimelineElements(changed) ? editState(this.value.state) : this.value.state,
|
|
74
75
|
};
|
|
75
76
|
}
|
|
76
77
|
apply(operations, expectedRevision = this.value.desired.revision) {
|
|
77
78
|
const preview = this.preview(operations, expectedRevision);
|
|
78
79
|
this.value.desired = preview.after;
|
|
79
|
-
if (
|
|
80
|
+
if (changedTimelineElements(preview)) {
|
|
80
81
|
this.value.desired.revision = nextRevision(preview.after, this.value.desired.revision, this.clock());
|
|
81
82
|
this.value.state = editState(this.value.state);
|
|
82
83
|
preview.after = structuredClone(this.value.desired);
|
|
@@ -183,6 +184,13 @@ export function createTimelineIrFromProjectSnapshot(snapshot, provider) {
|
|
|
183
184
|
...(clip.role ? { role: clip.role } : {}),
|
|
184
185
|
...(clip.mediaId ? { mediaId: clip.mediaId } : {}),
|
|
185
186
|
...(clip.gainDb !== undefined ? { gainDb: clip.gainDb } : {}),
|
|
187
|
+
...(clip.scale !== undefined || clip.position ? {
|
|
188
|
+
transform: {
|
|
189
|
+
scaleX: clip.scale ?? 1,
|
|
190
|
+
scaleY: clip.scale ?? 1,
|
|
191
|
+
...(clip.position ? { positionX: clip.position.x, positionY: clip.position.y } : {}),
|
|
192
|
+
},
|
|
193
|
+
} : {}),
|
|
186
194
|
...(clip.fadeIn !== undefined ? { fadeIn: clip.fadeIn } : {}),
|
|
187
195
|
...(clip.fadeOut !== undefined ? { fadeOut: clip.fadeOut } : {}),
|
|
188
196
|
...(clip.enabled !== undefined ? { enabled: clip.enabled } : {}),
|
|
@@ -242,6 +250,10 @@ export function validateTimelineIr(timeline) {
|
|
|
242
250
|
throw new Error("TIMELINE_IR_INVALID: markers must be an array");
|
|
243
251
|
if (!Array.isArray(timeline.sequence.captions))
|
|
244
252
|
throw new Error("TIMELINE_IR_INVALID: captions must be an array");
|
|
253
|
+
if (timeline.sequence.titles !== undefined && !Array.isArray(timeline.sequence.titles))
|
|
254
|
+
throw new Error("TIMELINE_IR_INVALID: titles must be an array");
|
|
255
|
+
if (timeline.sequence.transitions !== undefined && !Array.isArray(timeline.sequence.transitions))
|
|
256
|
+
throw new Error("TIMELINE_IR_INVALID: transitions must be an array");
|
|
245
257
|
requireText(timeline.project?.id, "project.id");
|
|
246
258
|
requireText(timeline.project?.name, "project.name");
|
|
247
259
|
requireText(timeline.sequence?.id, "sequence.id");
|
|
@@ -257,6 +269,17 @@ export function validateTimelineIr(timeline) {
|
|
|
257
269
|
if (!["video", "audio", "unknown"].includes(resource.mediaKind)) {
|
|
258
270
|
throw new Error(`TIMELINE_IR_INVALID: resource ${resource.id} has unsupported mediaKind`);
|
|
259
271
|
}
|
|
272
|
+
if (resource.sourceKind !== undefined && resource.sourceKind !== "local-file") {
|
|
273
|
+
throw new Error(`TIMELINE_IR_INVALID: resource ${resource.id} has unsupported sourceKind`);
|
|
274
|
+
}
|
|
275
|
+
if (resource.sourceKind === "local-file") {
|
|
276
|
+
requireText(resource.source, `resource ${resource.id}.source`);
|
|
277
|
+
if (typeof resource.sourceDigest !== "string" || !/^[a-f0-9]{64}$/.test(resource.sourceDigest)) {
|
|
278
|
+
throw new Error(`TIMELINE_IR_INVALID: resource ${resource.id}.sourceDigest must be a SHA-256 hex digest`);
|
|
279
|
+
}
|
|
280
|
+
}
|
|
281
|
+
if (resource.metadata)
|
|
282
|
+
validateMediaMetadata(resource.metadata, `resource ${resource.id}.metadata`);
|
|
260
283
|
validateBinding(resource.binding, `resource ${resource.id}.binding`);
|
|
261
284
|
}
|
|
262
285
|
const occurrenceIds = uniqueIds(timeline.sequence.occurrences.map((occurrence) => occurrence.id), "occurrence");
|
|
@@ -275,8 +298,18 @@ export function validateTimelineIr(timeline) {
|
|
|
275
298
|
}
|
|
276
299
|
if (occurrence.sourceStartTime)
|
|
277
300
|
validateRational(occurrence.sourceStartTime, `occurrence ${occurrence.id}.sourceStartTime`, false);
|
|
301
|
+
const resource = occurrence.mediaId ? timeline.resources.find(({ id }) => id === occurrence.mediaId) : undefined;
|
|
302
|
+
if (resource?.metadata) {
|
|
303
|
+
const sourceStartTime = occurrence.sourceStartTime ?? { value: "0", timescale: "1" };
|
|
304
|
+
const sourceEndTime = addRationalTimes(sourceStartTime, occurrence.durationTime, "TIMELINE_IR_INVALID");
|
|
305
|
+
if (compareRational(sourceEndTime, resource.metadata.durationTime) > 0) {
|
|
306
|
+
throw new Error(`TIMELINE_IR_INVALID: occurrence ${occurrence.id} source range exceeds resource ${resource.id}`);
|
|
307
|
+
}
|
|
308
|
+
}
|
|
278
309
|
if (occurrence.gainDb !== undefined && !Number.isFinite(occurrence.gainDb))
|
|
279
310
|
throw new Error(`TIMELINE_IR_INVALID: occurrence ${occurrence.id}.gainDb must be finite`);
|
|
311
|
+
if (occurrence.transform)
|
|
312
|
+
validateTransform(occurrence.transform, `occurrence ${occurrence.id}.transform`);
|
|
280
313
|
validateBinding(occurrence.binding, `occurrence ${occurrence.id}.binding`);
|
|
281
314
|
}
|
|
282
315
|
uniqueIds(timeline.sequence.storyElements.map((element) => element.id), "story element");
|
|
@@ -300,6 +333,12 @@ export function validateTimelineIr(timeline) {
|
|
|
300
333
|
validateRational(caption.startTime, `caption ${caption.id}.startTime`, false);
|
|
301
334
|
validateRational(caption.durationTime, `caption ${caption.id}.durationTime`, false);
|
|
302
335
|
}
|
|
336
|
+
uniqueIds((timeline.sequence.titles ?? []).map(({ id }) => id), "title");
|
|
337
|
+
for (const title of timeline.sequence.titles ?? [])
|
|
338
|
+
validateTitle(title);
|
|
339
|
+
uniqueIds((timeline.sequence.transitions ?? []).map(({ id }) => id), "transition");
|
|
340
|
+
for (const transition of timeline.sequence.transitions ?? [])
|
|
341
|
+
validateTransition(timeline, transition);
|
|
303
342
|
}
|
|
304
343
|
export function validateEditingSessionDocument(document) {
|
|
305
344
|
if (!document || typeof document !== "object" || document.schemaVersion !== TIMELINE_IR_SCHEMA_VERSION) {
|
|
@@ -332,16 +371,64 @@ function validateEditingSessionObservation(observation) {
|
|
|
332
371
|
throw new Error("TIMELINE_IR_INVALID: storage observation cannot be canonical or complete");
|
|
333
372
|
}
|
|
334
373
|
}
|
|
374
|
+
function validateMediaMetadata(metadata, field) {
|
|
375
|
+
if (!metadata || typeof metadata !== "object")
|
|
376
|
+
throw new Error(`TIMELINE_IR_INVALID: ${field} must be an object`);
|
|
377
|
+
validateRational(metadata.durationTime, `${field}.durationTime`, true);
|
|
378
|
+
if (!Array.isArray(metadata.streams) || metadata.streams.length === 0) {
|
|
379
|
+
throw new Error(`TIMELINE_IR_INVALID: ${field}.streams must be non-empty`);
|
|
380
|
+
}
|
|
381
|
+
for (const [index, stream] of metadata.streams.entries()) {
|
|
382
|
+
const streamField = `${field}.streams[${index}]`;
|
|
383
|
+
if (!stream || (stream.kind !== "video" && stream.kind !== "audio")) {
|
|
384
|
+
throw new Error(`TIMELINE_IR_INVALID: ${streamField}.kind is unsupported`);
|
|
385
|
+
}
|
|
386
|
+
if (stream.codec !== undefined)
|
|
387
|
+
requireText(stream.codec, `${streamField}.codec`);
|
|
388
|
+
if (stream.kind === "video") {
|
|
389
|
+
requirePositiveInteger(stream.width, `${streamField}.width`);
|
|
390
|
+
requirePositiveInteger(stream.height, `${streamField}.height`);
|
|
391
|
+
if (!stream.frameRate)
|
|
392
|
+
throw new Error(`TIMELINE_IR_INVALID: ${streamField}.frameRate is required`);
|
|
393
|
+
validateRational(stream.frameRate, `${streamField}.frameRate`, true);
|
|
394
|
+
}
|
|
395
|
+
else {
|
|
396
|
+
requirePositiveInteger(stream.sampleRate, `${streamField}.sampleRate`);
|
|
397
|
+
requirePositiveInteger(stream.channels, `${streamField}.channels`);
|
|
398
|
+
}
|
|
399
|
+
}
|
|
400
|
+
}
|
|
335
401
|
export function timelineIrDigest(timeline) {
|
|
336
402
|
const content = structuredClone(timeline);
|
|
337
403
|
delete content.revision;
|
|
338
404
|
return createHash("sha256").update(stableJson(content)).digest("hex");
|
|
339
405
|
}
|
|
340
406
|
function applyOperation(timeline, operation) {
|
|
341
|
-
const
|
|
342
|
-
|
|
343
|
-
|
|
407
|
+
const occurrenceId = "occurrenceId" in operation ? operation.occurrenceId : undefined;
|
|
408
|
+
const occurrence = occurrenceId ? timeline.sequence.occurrences.find(({ id }) => id === occurrenceId) : undefined;
|
|
409
|
+
if (![
|
|
410
|
+
"add-marker",
|
|
411
|
+
"insert-occurrence",
|
|
412
|
+
"add-title",
|
|
413
|
+
"remove-title",
|
|
414
|
+
"add-transition",
|
|
415
|
+
"remove-transition",
|
|
416
|
+
].includes(operation.type) && !occurrence) {
|
|
417
|
+
throw new Error(`TIMELINE_IR_OPERATION_INVALID: occurrence not found: ${occurrenceId}`);
|
|
418
|
+
}
|
|
344
419
|
switch (operation.type) {
|
|
420
|
+
case "insert-occurrence": {
|
|
421
|
+
if (timeline.sequence.occurrences.some(({ id }) => id === operation.occurrence.id)) {
|
|
422
|
+
throw new Error(`TIMELINE_IR_OPERATION_INVALID: occurrence already exists: ${operation.occurrence.id}`);
|
|
423
|
+
}
|
|
424
|
+
const inserted = structuredClone(operation.occurrence);
|
|
425
|
+
if (operation.placement === "append")
|
|
426
|
+
inserted.startTime = normalizeRationalTime(timeline.sequence.durationTime);
|
|
427
|
+
timeline.sequence.occurrences.push(inserted);
|
|
428
|
+
timeline.sequence.durationTime = maxRational(timeline.sequence.durationTime, addRationalTimes(inserted.startTime, inserted.durationTime, "TIMELINE_IR_OPERATION_INVALID"));
|
|
429
|
+
canonicalizeOccurrences(timeline);
|
|
430
|
+
return;
|
|
431
|
+
}
|
|
345
432
|
case "rename-occurrence":
|
|
346
433
|
requireText(operation.name, "operation.name");
|
|
347
434
|
occurrence.name = operation.name;
|
|
@@ -349,7 +436,11 @@ function applyOperation(timeline, operation) {
|
|
|
349
436
|
case "trim-occurrence":
|
|
350
437
|
occurrence.durationTime = normalizeRationalTime(operation.durationTime);
|
|
351
438
|
validateRational(occurrence.durationTime, "operation.durationTime", true);
|
|
352
|
-
|
|
439
|
+
if (operation.sourceStartTime) {
|
|
440
|
+
occurrence.sourceStartTime = normalizeRationalTime(operation.sourceStartTime);
|
|
441
|
+
validateRational(occurrence.sourceStartTime, "operation.sourceStartTime", false);
|
|
442
|
+
}
|
|
443
|
+
recomputeSequenceDuration(timeline);
|
|
353
444
|
return;
|
|
354
445
|
case "move-occurrence":
|
|
355
446
|
occurrence.startTime = normalizeRationalTime(operation.startTime);
|
|
@@ -359,16 +450,45 @@ function applyOperation(timeline, operation) {
|
|
|
359
450
|
throw new Error("TIMELINE_IR_OPERATION_INVALID: track must be a non-negative integer");
|
|
360
451
|
occurrence.track = operation.track;
|
|
361
452
|
}
|
|
362
|
-
|
|
453
|
+
recomputeSequenceDuration(timeline);
|
|
454
|
+
canonicalizeOccurrences(timeline);
|
|
455
|
+
return;
|
|
456
|
+
case "split-occurrence": {
|
|
457
|
+
requireText(operation.newOccurrenceId, "operation.newOccurrenceId");
|
|
458
|
+
if (timeline.sequence.occurrences.some(({ id }) => id === operation.newOccurrenceId)) {
|
|
459
|
+
throw new Error(`TIMELINE_IR_OPERATION_INVALID: occurrence already exists: ${operation.newOccurrenceId}`);
|
|
460
|
+
}
|
|
461
|
+
const splitOffsetTime = normalizeRationalTime(operation.splitOffsetTime);
|
|
462
|
+
validateRational(splitOffsetTime, "operation.splitOffsetTime", true);
|
|
463
|
+
if (compareRational(splitOffsetTime, occurrence.durationTime) >= 0) {
|
|
464
|
+
throw new Error("TIMELINE_IR_OPERATION_INVALID: splitOffsetTime must be inside the occurrence duration");
|
|
465
|
+
}
|
|
466
|
+
const right = structuredClone(occurrence);
|
|
467
|
+
right.id = operation.newOccurrenceId;
|
|
468
|
+
right.startTime = addRationalTimes(occurrence.startTime, splitOffsetTime, "TIMELINE_IR_OPERATION_INVALID");
|
|
469
|
+
right.durationTime = subtractRationalTimes(occurrence.durationTime, splitOffsetTime, "TIMELINE_IR_OPERATION_INVALID");
|
|
470
|
+
const sourceStartTime = occurrence.sourceStartTime ?? { value: "0", timescale: "1" };
|
|
471
|
+
right.sourceStartTime = addRationalTimes(sourceStartTime, splitOffsetTime, "TIMELINE_IR_OPERATION_INVALID");
|
|
472
|
+
if (right.binding?.kind === "occurrence")
|
|
473
|
+
delete right.binding;
|
|
474
|
+
occurrence.durationTime = splitOffsetTime;
|
|
475
|
+
timeline.sequence.occurrences.push(right);
|
|
476
|
+
canonicalizeOccurrences(timeline);
|
|
363
477
|
return;
|
|
478
|
+
}
|
|
364
479
|
case "set-gain":
|
|
365
480
|
if (!Number.isFinite(operation.gainDb))
|
|
366
481
|
throw new Error("TIMELINE_IR_OPERATION_INVALID: gainDb must be finite");
|
|
367
482
|
occurrence.gainDb = operation.gainDb;
|
|
368
483
|
return;
|
|
484
|
+
case "set-transform":
|
|
485
|
+
validateTransform(operation.transform, "operation.transform");
|
|
486
|
+
occurrence.transform = structuredClone(operation.transform);
|
|
487
|
+
return;
|
|
369
488
|
case "remove-occurrence":
|
|
370
489
|
timeline.sequence.occurrences = timeline.sequence.occurrences.filter(({ id }) => id !== operation.occurrenceId);
|
|
371
490
|
timeline.sequence.storyElements = timeline.sequence.storyElements.filter(({ occurrenceId }) => occurrenceId !== operation.occurrenceId);
|
|
491
|
+
recomputeSequenceDuration(timeline);
|
|
372
492
|
return;
|
|
373
493
|
case "add-marker":
|
|
374
494
|
validateMarker(operation.marker);
|
|
@@ -376,14 +496,138 @@ function applyOperation(timeline, operation) {
|
|
|
376
496
|
throw new Error(`TIMELINE_IR_OPERATION_INVALID: marker already exists: ${operation.marker.id}`);
|
|
377
497
|
timeline.sequence.markers.push({ ...structuredClone(operation.marker), startTime: normalizeRationalTime(operation.marker.startTime), durationTime: normalizeRationalTime(operation.marker.durationTime) });
|
|
378
498
|
return;
|
|
499
|
+
case "add-title": {
|
|
500
|
+
const titles = timeline.sequence.titles ??= [];
|
|
501
|
+
if (titles.some(({ id }) => id === operation.title.id))
|
|
502
|
+
throw new Error(`TIMELINE_IR_OPERATION_INVALID: title already exists: ${operation.title.id}`);
|
|
503
|
+
validateTitle(operation.title);
|
|
504
|
+
titles.push(structuredClone(operation.title));
|
|
505
|
+
recomputeSequenceDuration(timeline);
|
|
506
|
+
return;
|
|
507
|
+
}
|
|
508
|
+
case "remove-title": {
|
|
509
|
+
const titles = timeline.sequence.titles ?? [];
|
|
510
|
+
if (!titles.some(({ id }) => id === operation.titleId))
|
|
511
|
+
throw new Error(`TIMELINE_IR_OPERATION_INVALID: title not found: ${operation.titleId}`);
|
|
512
|
+
timeline.sequence.titles = titles.filter(({ id }) => id !== operation.titleId);
|
|
513
|
+
recomputeSequenceDuration(timeline);
|
|
514
|
+
return;
|
|
515
|
+
}
|
|
516
|
+
case "add-transition": {
|
|
517
|
+
const transitions = timeline.sequence.transitions ??= [];
|
|
518
|
+
if (transitions.some(({ id }) => id === operation.transition.id))
|
|
519
|
+
throw new Error(`TIMELINE_IR_OPERATION_INVALID: transition already exists: ${operation.transition.id}`);
|
|
520
|
+
validateTransition(timeline, operation.transition);
|
|
521
|
+
transitions.push(structuredClone(operation.transition));
|
|
522
|
+
return;
|
|
523
|
+
}
|
|
524
|
+
case "remove-transition": {
|
|
525
|
+
const transitions = timeline.sequence.transitions ?? [];
|
|
526
|
+
if (!transitions.some(({ id }) => id === operation.transitionId))
|
|
527
|
+
throw new Error(`TIMELINE_IR_OPERATION_INVALID: transition not found: ${operation.transitionId}`);
|
|
528
|
+
timeline.sequence.transitions = transitions.filter(({ id }) => id !== operation.transitionId);
|
|
529
|
+
return;
|
|
530
|
+
}
|
|
531
|
+
default:
|
|
532
|
+
throw new Error(`TIMELINE_IR_UNSUPPORTED: unsupported Timeline IR operation: ${operation.type ?? "unknown"}`);
|
|
379
533
|
}
|
|
380
534
|
}
|
|
535
|
+
function canonicalizeOccurrences(timeline) {
|
|
536
|
+
timeline.sequence.occurrences.sort((left, right) => {
|
|
537
|
+
const start = compareRational(left.startTime, right.startTime);
|
|
538
|
+
if (start !== 0)
|
|
539
|
+
return start;
|
|
540
|
+
if (left.track !== right.track)
|
|
541
|
+
return left.track - right.track;
|
|
542
|
+
return left.id.localeCompare(right.id);
|
|
543
|
+
});
|
|
544
|
+
}
|
|
545
|
+
function recomputeSequenceDuration(timeline) {
|
|
546
|
+
let durationTime = { value: "0", timescale: "1" };
|
|
547
|
+
for (const item of [...timeline.sequence.occurrences, ...timeline.sequence.storyElements]) {
|
|
548
|
+
durationTime = maxRational(durationTime, addRationalTimes(item.startTime, item.durationTime, "TIMELINE_IR_OPERATION_INVALID"));
|
|
549
|
+
}
|
|
550
|
+
for (const title of timeline.sequence.titles ?? []) {
|
|
551
|
+
durationTime = maxRational(durationTime, addRationalTimes(title.startTime, title.durationTime, "TIMELINE_IR_OPERATION_INVALID"));
|
|
552
|
+
}
|
|
553
|
+
timeline.sequence.durationTime = durationTime;
|
|
554
|
+
}
|
|
381
555
|
function validateMarker(marker) {
|
|
382
556
|
requireText(marker.id, "marker.id");
|
|
383
557
|
requireText(marker.name, `marker ${marker.id}.name`);
|
|
384
558
|
validateRational(marker.startTime, `marker ${marker.id}.startTime`, false);
|
|
385
559
|
validateRational(marker.durationTime, `marker ${marker.id}.durationTime`, false);
|
|
386
560
|
}
|
|
561
|
+
function validateTitle(title) {
|
|
562
|
+
requireText(title.id, "title.id");
|
|
563
|
+
requireText(title.text, `title ${title.id}.text`);
|
|
564
|
+
validateRational(title.startTime, `title ${title.id}.startTime`, false);
|
|
565
|
+
validateRational(title.durationTime, `title ${title.id}.durationTime`, true);
|
|
566
|
+
if (!Number.isInteger(title.lane) || title.lane < 1)
|
|
567
|
+
throw new Error(`TIMELINE_IR_INVALID: title ${title.id}.lane must be a positive integer`);
|
|
568
|
+
if (title.position && (![title.position.x, title.position.y].every(Number.isFinite)
|
|
569
|
+
|| ![title.position.x, title.position.y].every((value) => value >= -1 && value <= 1))) {
|
|
570
|
+
throw new Error(`TIMELINE_IR_INVALID: title ${title.id}.position must use normalized coordinates in [-1, 1]`);
|
|
571
|
+
}
|
|
572
|
+
if (title.style) {
|
|
573
|
+
if (title.style.fontFamily !== undefined)
|
|
574
|
+
requireText(title.style.fontFamily, `title ${title.id}.style.fontFamily`);
|
|
575
|
+
if (title.style.fontSize !== undefined && (!Number.isFinite(title.style.fontSize) || title.style.fontSize <= 0)) {
|
|
576
|
+
throw new Error(`TIMELINE_IR_INVALID: title ${title.id}.style.fontSize must be positive`);
|
|
577
|
+
}
|
|
578
|
+
if (title.style.color !== undefined)
|
|
579
|
+
requireText(title.style.color, `title ${title.id}.style.color`);
|
|
580
|
+
if (title.style.alignment !== undefined && !["left", "center", "right"].includes(title.style.alignment)) {
|
|
581
|
+
throw new Error(`TIMELINE_IR_INVALID: title ${title.id}.style.alignment is unsupported`);
|
|
582
|
+
}
|
|
583
|
+
}
|
|
584
|
+
}
|
|
585
|
+
function validateTransition(timeline, transition) {
|
|
586
|
+
requireText(transition.id, "transition.id");
|
|
587
|
+
if (transition.kind !== "cross-dissolve")
|
|
588
|
+
throw new Error(`TIMELINE_IR_INVALID: transition ${transition.id}.kind is unsupported`);
|
|
589
|
+
requireText(transition.beforeOccurrenceId, `transition ${transition.id}.beforeOccurrenceId`);
|
|
590
|
+
requireText(transition.afterOccurrenceId, `transition ${transition.id}.afterOccurrenceId`);
|
|
591
|
+
validateRational(transition.durationTime, `transition ${transition.id}.durationTime`, true);
|
|
592
|
+
const occurrences = timeline.sequence.occurrences;
|
|
593
|
+
const before = occurrences.find(({ id }) => id === transition.beforeOccurrenceId);
|
|
594
|
+
const after = occurrences.find(({ id }) => id === transition.afterOccurrenceId);
|
|
595
|
+
if (!before || !after)
|
|
596
|
+
throw new Error(`TIMELINE_IR_INVALID: transition ${transition.id} participants must exist`);
|
|
597
|
+
const sameTrack = occurrences.filter(({ track }) => track === before.track);
|
|
598
|
+
const beforeIndex = sameTrack.findIndex(({ id }) => id === before.id);
|
|
599
|
+
const afterIndex = sameTrack.findIndex(({ id }) => id === after.id);
|
|
600
|
+
if (before.track !== after.track || beforeIndex < 0 || afterIndex !== beforeIndex + 1) {
|
|
601
|
+
throw new Error(`TIMELINE_IR_INVALID: transition ${transition.id} participants must be adjacent on one track`);
|
|
602
|
+
}
|
|
603
|
+
if (compareRational(addRationalTimes(before.startTime, before.durationTime), after.startTime) !== 0) {
|
|
604
|
+
throw new Error(`TIMELINE_IR_INVALID: transition ${transition.id} participants must meet at one boundary`);
|
|
605
|
+
}
|
|
606
|
+
if (compareRational(transition.durationTime, before.durationTime) > 0 || compareRational(transition.durationTime, after.durationTime) > 0) {
|
|
607
|
+
throw new Error(`TIMELINE_IR_INVALID: transition ${transition.id}.durationTime exceeds a participant duration`);
|
|
608
|
+
}
|
|
609
|
+
}
|
|
610
|
+
function validateTransform(transform, field) {
|
|
611
|
+
if (!transform || typeof transform !== "object")
|
|
612
|
+
throw new Error(`TIMELINE_IR_INVALID: ${field} must be an object`);
|
|
613
|
+
const allowedKeys = new Set(["scaleX", "scaleY", "positionX", "positionY", "rotationDegrees"]);
|
|
614
|
+
for (const key of Object.keys(transform)) {
|
|
615
|
+
if (!allowedKeys.has(key))
|
|
616
|
+
throw new Error(`TIMELINE_IR_INVALID: ${field}.${key} is not supported`);
|
|
617
|
+
}
|
|
618
|
+
if (!Number.isFinite(transform.scaleX) || transform.scaleX <= 0)
|
|
619
|
+
throw new Error(`TIMELINE_IR_INVALID: ${field}.scaleX must be positive`);
|
|
620
|
+
if (!Number.isFinite(transform.scaleY) || transform.scaleY <= 0)
|
|
621
|
+
throw new Error(`TIMELINE_IR_INVALID: ${field}.scaleY must be positive`);
|
|
622
|
+
for (const [name, value] of [
|
|
623
|
+
["positionX", transform.positionX],
|
|
624
|
+
["positionY", transform.positionY],
|
|
625
|
+
["rotationDegrees", transform.rotationDegrees],
|
|
626
|
+
]) {
|
|
627
|
+
if (value !== undefined && !Number.isFinite(value))
|
|
628
|
+
throw new Error(`TIMELINE_IR_INVALID: ${field}.${name} must be finite`);
|
|
629
|
+
}
|
|
630
|
+
}
|
|
387
631
|
function storyElementToIr(element, binding) {
|
|
388
632
|
return {
|
|
389
633
|
id: element.id,
|
|
@@ -409,6 +653,12 @@ function validateRational(value, field, requirePositive) {
|
|
|
409
653
|
if (requirePositive && parsed.value <= 0n)
|
|
410
654
|
throw new Error(`TIMELINE_IR_INVALID: ${field} must be positive`);
|
|
411
655
|
}
|
|
656
|
+
function compareRational(left, right) {
|
|
657
|
+
const leftParts = parseRational(left, "TIMELINE_IR_INVALID");
|
|
658
|
+
const rightParts = parseRational(right, "TIMELINE_IR_INVALID");
|
|
659
|
+
const difference = leftParts.value * rightParts.timescale - rightParts.value * leftParts.timescale;
|
|
660
|
+
return difference < 0n ? -1 : difference > 0n ? 1 : 0;
|
|
661
|
+
}
|
|
412
662
|
function validateRevision(revision) {
|
|
413
663
|
requireText(revision?.id, "revision.id");
|
|
414
664
|
if (!Number.isSafeInteger(revision.sequence) || revision.sequence < 0)
|
|
@@ -434,6 +684,11 @@ function requireText(value, field) {
|
|
|
434
684
|
if (typeof value !== "string" || !value.trim())
|
|
435
685
|
throw new Error(`TIMELINE_IR_INVALID: ${field} must be non-empty`);
|
|
436
686
|
}
|
|
687
|
+
function requirePositiveInteger(value, field) {
|
|
688
|
+
if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
|
|
689
|
+
throw new Error(`TIMELINE_IR_INVALID: ${field} must be a positive integer`);
|
|
690
|
+
}
|
|
691
|
+
}
|
|
437
692
|
function uniqueIds(values, label) {
|
|
438
693
|
const ids = new Set();
|
|
439
694
|
for (const value of values) {
|
|
@@ -476,13 +731,26 @@ function sameRevision(left, right) {
|
|
|
476
731
|
function changedIds(before, after) {
|
|
477
732
|
const occurrenceIds = new Set([...before.sequence.occurrences, ...after.sequence.occurrences].map(({ id }) => id));
|
|
478
733
|
const markerIds = new Set([...before.sequence.markers, ...after.sequence.markers].map(({ id }) => id));
|
|
734
|
+
const titleIds = new Set([
|
|
735
|
+
...(before.sequence.titles ?? []).map(({ id }) => id),
|
|
736
|
+
...(after.sequence.titles ?? []).map(({ id }) => id),
|
|
737
|
+
]);
|
|
738
|
+
const transitionIds = new Set([
|
|
739
|
+
...(before.sequence.transitions ?? []).map(({ id }) => id),
|
|
740
|
+
...(after.sequence.transitions ?? []).map(({ id }) => id),
|
|
741
|
+
]);
|
|
479
742
|
return {
|
|
480
743
|
changedOccurrenceIds: [...occurrenceIds].filter((id) => JSON.stringify(before.sequence.occurrences.find((item) => item.id === id)) !== JSON.stringify(after.sequence.occurrences.find((item) => item.id === id))),
|
|
481
744
|
changedMarkerIds: [...markerIds].filter((id) => JSON.stringify(before.sequence.markers.find((item) => item.id === id)) !== JSON.stringify(after.sequence.markers.find((item) => item.id === id))),
|
|
745
|
+
changedTitleIds: [...titleIds].filter((id) => JSON.stringify(before.sequence.titles?.find((item) => item.id === id)) !== JSON.stringify(after.sequence.titles?.find((item) => item.id === id))),
|
|
746
|
+
changedTransitionIds: [...transitionIds].filter((id) => JSON.stringify(before.sequence.transitions?.find((item) => item.id === id)) !== JSON.stringify(after.sequence.transitions?.find((item) => item.id === id))),
|
|
482
747
|
};
|
|
483
748
|
}
|
|
484
|
-
function
|
|
485
|
-
return changed.changedOccurrenceIds.length > 0
|
|
749
|
+
function changedTimelineElements(changed) {
|
|
750
|
+
return changed.changedOccurrenceIds.length > 0
|
|
751
|
+
|| changed.changedMarkerIds.length > 0
|
|
752
|
+
|| changed.changedTitleIds.length > 0
|
|
753
|
+
|| changed.changedTransitionIds.length > 0;
|
|
486
754
|
}
|
|
487
755
|
function editState(state) {
|
|
488
756
|
return state === "possibly_stale" || state === "conflicted" || state === "rebased" || state === "waiting_for_materialization" ? state : "dirty";
|
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
import { timelineIrDigest, validateTimelineIr, } from "./editing-session.js";
|
|
2
|
+
export const FAST_TIMELINE_OBSERVATION_SCHEMA_VERSION = 1;
|
|
3
|
+
/**
|
|
4
|
+
* Normalize an adapter-produced envelope at the runtime boundary.
|
|
5
|
+
* The runtime validates the optional Timeline IR but never invents unknown fields.
|
|
6
|
+
*/
|
|
7
|
+
export function normalizeFastTimelineObservation(input) {
|
|
8
|
+
const observation = structuredClone(input);
|
|
9
|
+
validateObservationEnvelope(observation);
|
|
10
|
+
if (observation.timeline) {
|
|
11
|
+
validateTimelineIr(observation.timeline);
|
|
12
|
+
if (!observation.timelineDigest)
|
|
13
|
+
observation.timelineDigest = timelineIrDigest(observation.timeline);
|
|
14
|
+
}
|
|
15
|
+
return observation;
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* Reconcile provider evidence through the real EditingSession state machine.
|
|
19
|
+
* Partial evidence never replaces the known canonical baseline.
|
|
20
|
+
*/
|
|
21
|
+
export function reconcileFastTimelineObservation(input) {
|
|
22
|
+
const { session, observation } = input;
|
|
23
|
+
const base = session.base();
|
|
24
|
+
const common = {
|
|
25
|
+
canonical: false,
|
|
26
|
+
provider: observation.provider,
|
|
27
|
+
sourceType: observation.sourceType,
|
|
28
|
+
revision: structuredClone(observation.revision),
|
|
29
|
+
coverage: structuredClone(observation.coverage),
|
|
30
|
+
unknowns: [...observation.unknowns],
|
|
31
|
+
};
|
|
32
|
+
const finish = (status, reason, reconciliation) => ({
|
|
33
|
+
...common,
|
|
34
|
+
status,
|
|
35
|
+
reason,
|
|
36
|
+
session: sessionEvidence(session),
|
|
37
|
+
...(reconciliation ? { reconciliation } : {}),
|
|
38
|
+
});
|
|
39
|
+
try {
|
|
40
|
+
validateObservationEnvelope(observation);
|
|
41
|
+
}
|
|
42
|
+
catch (error) {
|
|
43
|
+
session.markConflicted();
|
|
44
|
+
return finish("canonical-resync-required", errorMessage(error));
|
|
45
|
+
}
|
|
46
|
+
const expectedProvider = session.document().provider?.id;
|
|
47
|
+
if (expectedProvider && observation.provider !== expectedProvider) {
|
|
48
|
+
session.markConflicted();
|
|
49
|
+
return finish("provider-incompatible", `observation provider ${observation.provider} is incompatible with session provider ${expectedProvider}`);
|
|
50
|
+
}
|
|
51
|
+
if (!sameTarget(observation.target, { projectId: base.project.id, sequenceId: base.sequence.id })
|
|
52
|
+
|| !sameTarget(observation.provenance.target, observation.target)) {
|
|
53
|
+
session.markConflicted();
|
|
54
|
+
return finish("target-mismatch", "observation target or materialization provenance does not match the session");
|
|
55
|
+
}
|
|
56
|
+
if (!observation.timeline) {
|
|
57
|
+
session.markPossiblyStale();
|
|
58
|
+
return finish("possibly-stale", "observation has no normalized Timeline IR; known canonical fields are preserved");
|
|
59
|
+
}
|
|
60
|
+
if (!observation.timelineDigest || timelineIrDigest(observation.timeline) !== observation.timelineDigest) {
|
|
61
|
+
session.markConflicted();
|
|
62
|
+
return finish("canonical-resync-required", "observation timeline digest does not match normalized Timeline IR");
|
|
63
|
+
}
|
|
64
|
+
if (!sameRevision(observation.timeline.revision, observation.revision)) {
|
|
65
|
+
session.markConflicted();
|
|
66
|
+
return finish("canonical-resync-required", "observation revision does not match normalized Timeline IR revision");
|
|
67
|
+
}
|
|
68
|
+
if (!completeCoverage(observation.coverage) || observation.unknowns.length > 0) {
|
|
69
|
+
session.markPossiblyStale();
|
|
70
|
+
return finish("possibly-stale", "observation has incomplete coverage or explicit unknown fields");
|
|
71
|
+
}
|
|
72
|
+
if (observation.trust !== "normalized" || observation.freshness !== "editor-read") {
|
|
73
|
+
session.markPossiblyStale();
|
|
74
|
+
return finish("possibly-stale", "observation trust or freshness is insufficient for Timeline IR reconciliation");
|
|
75
|
+
}
|
|
76
|
+
const observedDigest = timelineIrDigest(observation.timeline);
|
|
77
|
+
const baseDigest = timelineIrDigest(base);
|
|
78
|
+
const desiredDigest = timelineIrDigest(session.desired());
|
|
79
|
+
if (observedDigest === baseDigest) {
|
|
80
|
+
if (!sameRevision(base.revision, observation.revision)) {
|
|
81
|
+
session.observeProviderRevision(observation.revision);
|
|
82
|
+
return finish("possibly-stale", "observation matches the baseline but changed provider revision");
|
|
83
|
+
}
|
|
84
|
+
return finish("unchanged", "observation matches the session baseline");
|
|
85
|
+
}
|
|
86
|
+
const reconciliation = session.reconcile(observation.timeline);
|
|
87
|
+
if (reconciliation.status === "conflicted") {
|
|
88
|
+
return finish("conflicted", "observation conflicts with the session desired state", reconciliation);
|
|
89
|
+
}
|
|
90
|
+
if (observedDigest === desiredDigest && desiredDigest !== baseDigest) {
|
|
91
|
+
return finish("advanced-by-framekit", "observation proves the expected Framekit desired timeline", reconciliation);
|
|
92
|
+
}
|
|
93
|
+
return finish("proven-structural-delta", "complete normalized evidence advanced the session baseline", reconciliation);
|
|
94
|
+
}
|
|
95
|
+
function sessionEvidence(session) {
|
|
96
|
+
return {
|
|
97
|
+
state: session.state(),
|
|
98
|
+
base: session.base(),
|
|
99
|
+
desired: session.desired(),
|
|
100
|
+
serialized: session.serialize(),
|
|
101
|
+
};
|
|
102
|
+
}
|
|
103
|
+
function validateObservationEnvelope(observation) {
|
|
104
|
+
if (!observation || observation.schemaVersion !== FAST_TIMELINE_OBSERVATION_SCHEMA_VERSION) {
|
|
105
|
+
throw new Error("FAST_TIMELINE_OBSERVATION_INVALID: unsupported schema version");
|
|
106
|
+
}
|
|
107
|
+
for (const [name, value] of Object.entries({
|
|
108
|
+
provider: observation.provider,
|
|
109
|
+
sourceType: observation.sourceType,
|
|
110
|
+
observedAt: observation.observedAt,
|
|
111
|
+
observationDigest: observation.observationDigest,
|
|
112
|
+
artifactDigest: observation.provenance?.artifactDigest,
|
|
113
|
+
})) {
|
|
114
|
+
if (typeof value !== "string" || !value.trim())
|
|
115
|
+
throw new Error(`FAST_TIMELINE_OBSERVATION_INVALID: ${name} is required`);
|
|
116
|
+
}
|
|
117
|
+
if (!observation.target?.projectId?.trim() || !observation.target.sequenceId?.trim()) {
|
|
118
|
+
throw new Error("FAST_TIMELINE_OBSERVATION_INVALID: target identity is required");
|
|
119
|
+
}
|
|
120
|
+
if (!sameTarget(observation.provenance.target, observation.target)) {
|
|
121
|
+
throw new Error("FAST_TIMELINE_OBSERVATION_INVALID: provenance target differs from observation target");
|
|
122
|
+
}
|
|
123
|
+
if (observation.canonical !== false || !Array.isArray(observation.unknowns)) {
|
|
124
|
+
throw new Error("FAST_TIMELINE_OBSERVATION_INVALID: evidence must remain non-canonical with explicit unknowns");
|
|
125
|
+
}
|
|
126
|
+
if (observation.timeline && observation.timelineDigest !== undefined && typeof observation.timelineDigest !== "string") {
|
|
127
|
+
throw new Error("FAST_TIMELINE_OBSERVATION_INVALID: timelineDigest must be a string");
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
function completeCoverage(coverage) {
|
|
131
|
+
return Object.values(coverage).every((state) => state === "complete");
|
|
132
|
+
}
|
|
133
|
+
function sameRevision(left, right) {
|
|
134
|
+
return left.id === right.id && left.sequence === right.sequence && left.timestamp === right.timestamp;
|
|
135
|
+
}
|
|
136
|
+
function sameTarget(left, right) {
|
|
137
|
+
return left?.projectId === right.projectId && left?.sequenceId === right.sequenceId;
|
|
138
|
+
}
|
|
139
|
+
function errorMessage(error) {
|
|
140
|
+
return error instanceof Error ? error.message : String(error);
|
|
141
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@morshoto/framekit",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.17",
|
|
4
4
|
"packageManager": "pnpm@12.5.1",
|
|
5
5
|
"private": false,
|
|
6
6
|
"type": "module",
|
|
@@ -36,6 +36,7 @@
|
|
|
36
36
|
"test:clean-mcp-clients": "node scripts/clean-mcp-client-smoke.mjs",
|
|
37
37
|
"evaluate": "tsx scripts/run-mcp-evaluation.ts",
|
|
38
38
|
"test:final-cut-headless": "tsx --test tests/integration/connection.test.ts tests/integration/finalcut-mcp.test.ts tests/integration/native.test.ts",
|
|
39
|
+
"probe:final-cut-read": "node scripts/final-cut-supported-read-probe.mjs",
|
|
39
40
|
"test:final-cut-overlay-headed": "node scripts/final-cut-overlay-headed-e2e.mjs",
|
|
40
41
|
"test:final-cut-canonical-read-headed": "node scripts/final-cut-canonical-read-headed-e2e.mjs",
|
|
41
42
|
"test:final-cut-incremental-sync-headed": "node --import tsx scripts/final-cut-incremental-sync-headed-e2e.mjs",
|