@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.
Files changed (36) hide show
  1. package/dist-package/adapters/final-cut/typescript/src/background-materialization.js +28 -0
  2. package/dist-package/adapters/final-cut/typescript/src/canonical.js +144 -35
  3. package/dist-package/adapters/final-cut/typescript/src/connection.js +8 -5
  4. package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +36 -7
  5. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +21 -7
  6. package/dist-package/adapters/final-cut/typescript/src/index.js +2 -0
  7. package/dist-package/adapters/final-cut/typescript/src/live.js +56 -1
  8. package/dist-package/adapters/final-cut/typescript/src/native.js +311 -20
  9. package/dist-package/adapters/final-cut/typescript/src/pasteboard-snapshot.js +312 -0
  10. package/dist-package/adapters/final-cut/typescript/src/publisher.js +68 -8
  11. package/dist-package/adapters/final-cut/typescript/src/sqlite-wal-observation.js +263 -0
  12. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +179 -25
  13. package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.js +62 -0
  14. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +551 -0
  15. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +181 -0
  16. package/dist-package/adapters/headless/typescript/src/index.js +3 -0
  17. package/dist-package/apps/mcp-server/src/headless-projects.js +370 -0
  18. package/dist-package/apps/mcp-server/src/headless-sessions.js +3 -0
  19. package/dist-package/apps/mcp-server/src/main.js +28 -4
  20. package/dist-package/apps/mcp-server/src/materialization-jobs.js +233 -4
  21. package/dist-package/apps/mcp-server/src/readback-policy.js +26 -0
  22. package/dist-package/apps/mcp-server/src/routing.js +134 -5
  23. package/dist-package/apps/mcp-server/src/server.js +311 -34
  24. package/dist-package/packages/runtime/src/application/local-media.js +157 -0
  25. package/dist-package/packages/runtime/src/application/media-analysis-service.js +347 -27
  26. package/dist-package/packages/runtime/src/application/project-store.js +234 -0
  27. package/dist-package/packages/runtime/src/application/project-transactions.js +227 -0
  28. package/dist-package/packages/runtime/src/application/semantic-media-index-store.js +86 -0
  29. package/dist-package/packages/runtime/src/index.js +7 -0
  30. package/dist-package/packages/runtime/src/planning/rough-cut.js +103 -7
  31. package/dist-package/packages/runtime/src/render/render-and-verify.js +126 -0
  32. package/dist-package/packages/runtime/src/render/render-contract.js +146 -0
  33. package/dist-package/packages/runtime/src/runtime.js +5 -2
  34. package/dist-package/packages/runtime/src/timeline/editing-session.js +277 -9
  35. package/dist-package/packages/runtime/src/timeline/fast-observation.js +141 -0
  36. 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: changedOccurrenceOrMarkers(changed) ? editState(this.value.state) : this.value.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 (changedOccurrenceOrMarkers(preview)) {
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 occurrence = operation.type === "add-marker" ? undefined : timeline.sequence.occurrences.find(({ id }) => id === operation.occurrenceId);
342
- if (operation.type !== "add-marker" && !occurrence)
343
- throw new Error(`TIMELINE_IR_OPERATION_INVALID: occurrence not found: ${operation.occurrenceId}`);
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
- timeline.sequence.durationTime = maxRational(timeline.sequence.durationTime, addRationalTimes(occurrence.startTime, occurrence.durationTime));
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
- timeline.sequence.durationTime = maxRational(timeline.sequence.durationTime, addRationalTimes(occurrence.startTime, occurrence.durationTime));
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 changedOccurrenceOrMarkers(changed) {
485
- return changed.changedOccurrenceIds.length > 0 || changed.changedMarkerIds.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.14",
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",