@cueframe/kernel 0.1.0 → 0.1.1

package/dist/_members/composition/invariants/tracks.js

@@ -1,304 +0,0 @@
-function isTimelineClip(c) {
-    return "source" in c;
-}
-function end(c) {
-    return c.startTime + c.duration;
-}
-/**
- * Clips and Gaps on a single Track cannot overlap.
- * track_clips_overlap { trackId, clipAId, clipBId, overlapRange }
- */
-export function checkTrackContentsNoOverlap(track) {
-    const violations = [];
-    const sorted = [...track.contents].sort((a, b) => a.startTime - b.startTime);
-    for (let i = 1; i < sorted.length; i++) {
-        const prev = sorted[i - 1];
-        const cur = sorted[i];
-        if (cur.startTime < end(prev)) {
-            violations.push({
-                code: "track_clips_overlap",
-                message: `Track ${track.id}: items ${prev.id} and ${cur.id} overlap at [${cur.startTime}, ${Math.min(end(prev), end(cur))})`,
-                details: {
-                    trackId: track.id,
-                    clipAId: prev.id,
-                    clipBId: cur.id,
-                    overlapRange: [cur.startTime, Math.min(end(prev), end(cur))],
-                },
-            });
-        }
-    }
-    return violations;
-}
-/**
- * A TimelineClip.source.kind must match Track.kind per the compatibility table.
- * clip_source_track_kind_mismatch { trackId, clipId, sourceKind, trackKind }
- */
-export function checkClipSourceTrackKind(track) {
-    const violations = [];
-    for (const content of track.contents) {
-        if (!isTimelineClip(content))
-            continue;
-        const ok = isSourceKindCompatible(track.kind, content.source.kind);
-        if (!ok) {
-            violations.push({
-                code: "clip_source_track_kind_mismatch",
-                message: `Track ${track.id} (kind=${track.kind}) cannot hold TimelineClip ${content.id} (source.kind=${content.source.kind})`,
-                details: {
-                    trackId: track.id,
-                    clipId: content.id,
-                    sourceKind: content.source.kind,
-                    trackKind: track.kind,
-                },
-            });
-        }
-    }
-    return violations;
-}
-export function isSourceKindCompatible(trackKind, sourceKind) {
-    switch (trackKind) {
-        case "video":
-            // `composition` = a compound clip; its content is video-family by
-            // definition (it flattens to the child's tracks at projection).
-            return sourceKind === "media" || sourceKind === "component" || sourceKind === "composition";
-        case "audio":
-            return sourceKind === "media" || sourceKind === "component";
-        case "image":
-            // Image tracks carry stills via `kind: "media"`. The renderer
-            // resolves them via <StillFrame>, distinct from <Video>. Component
-            // sources are also allowed for parity with video/audio (e.g. a
-            // future "synthetic still" primitive).
-            return sourceKind === "media" || sourceKind === "component";
-        case "overlay":
-            // alpha-layer (a baked-alpha component) and card (authored static graphic)
-            // composite on the overlay track too — keep in lockstep with the server's
-            // clipTrackFamilyIssue (services/convex/composition/projection.ts) and
-            // AUTHORED_GRAPHIC_KINDS (validators/composition.ts).
-            return (sourceKind === "overlay" ||
-                sourceKind === "component" ||
-                sourceKind === "alpha-layer" ||
-                sourceKind === "card");
-        case "effect":
-            return sourceKind === "effect";
-    }
-}
-/**
- * A TimelineClip with transitionIn must have a contiguous TimelineClip predecessor on the
- * same Track (no Gap, not first element).
- *
- * transition_no_predecessor { trackId, clipId }
- * transition_too_long       { trackId, clipId, transitionDuration, available }
- */
-export function checkTransitions(track) {
-    const violations = [];
-    const sorted = [...track.contents].sort((a, b) => a.startTime - b.startTime);
-    for (let i = 0; i < sorted.length; i++) {
-        const cur = sorted[i];
-        if (!isTimelineClip(cur) || !cur.transitionIn)
-            continue;
-        const prev = sorted[i - 1];
-        if (!prev || !isTimelineClip(prev)) {
-            violations.push({
-                code: "transition_no_predecessor",
-                message: `Track ${track.id}: TimelineClip ${cur.id} has transitionIn but no TimelineClip predecessor`,
-                details: { trackId: track.id, clipId: cur.id },
-            });
-            continue;
-        }
-        const d = cur.transitionIn.duration;
-        const headroom = Math.min(prev.duration, cur.duration);
-        if (d > headroom) {
-            violations.push({
-                code: "transition_too_long",
-                message: `Track ${track.id}: TimelineClip ${cur.id} transitionIn.duration (${d}) exceeds available headroom (${headroom})`,
-                details: {
-                    trackId: track.id,
-                    clipId: cur.id,
-                    transitionDuration: d,
-                    available: headroom,
-                },
-            });
-        }
-    }
-    return violations;
-}
-/**
- * For each TimelineClip with a media source carrying excludedRanges, verify:
- *   - each range has end > start
- *   - every range is within the source trim window (or [0, duration] when trim absent)
- *   - ranges are sorted and non-overlapping
- *   - clip.duration === (trimEnd - trimStart) - Σ excluded, within float tolerance (1e-3)
- *
- * Coordinate space: source coordinates (same as `trim`).
- *
- * excluded_range_invalid             { trackId, clipId, index, start, end }
- * excluded_range_out_of_bounds       { trackId, clipId, index, start, end, trimStart, trimEnd }
- * excluded_range_overlap             { trackId, clipId, index, start, prevEnd }
- * excluded_range_duration_mismatch   { trackId, clipId, expected, actual, trimSpan, totalExcluded }
- */
-export function checkExcludedRanges(track) {
-    const violations = [];
-    for (const content of track.contents) {
-        if (!isTimelineClip(content))
-            continue;
-        if (content.source.kind !== "media")
-            continue;
-        const ranges = content.source.excludedRanges;
-        if (!ranges || ranges.length === 0)
-            continue;
-        const trim = content.source.trim;
-        const trimStart = trim?.start ?? 0;
-        // When trim is absent, source coordinates collapse to [0, duration] (1:1).
-        const trimEnd = trim?.end ?? trimStart + content.duration;
-        let prevEnd = -Infinity;
-        let total = 0;
-        let earlyExit = false;
-        for (let i = 0; i < ranges.length; i++) {
-            const r = ranges[i];
-            if (r.end <= r.start) {
-                violations.push({
-                    code: "excluded_range_invalid",
-                    message: `Track ${track.id}: TimelineClip ${content.id} excludedRanges[${i}] end (${r.end}) must be > start (${r.start})`,
-                    details: {
-                        trackId: track.id,
-                        clipId: content.id,
-                        index: i,
-                        start: r.start,
-                        end: r.end,
-                    },
-                });
-                earlyExit = true;
-                break;
-            }
-            if (r.start < trimStart || r.end > trimEnd) {
-                violations.push({
-                    code: "excluded_range_out_of_bounds",
-                    message: `Track ${track.id}: TimelineClip ${content.id} excludedRanges[${i}] [${r.start}, ${r.end}] outside trim [${trimStart}, ${trimEnd}]`,
-                    details: {
-                        trackId: track.id,
-                        clipId: content.id,
-                        index: i,
-                        start: r.start,
-                        end: r.end,
-                        trimStart,
-                        trimEnd,
-                    },
-                });
-                earlyExit = true;
-                break;
-            }
-            if (r.start < prevEnd) {
-                violations.push({
-                    code: "excluded_range_overlap",
-                    message: `Track ${track.id}: TimelineClip ${content.id} excludedRanges[${i}] overlaps preceding range (start ${r.start} < prevEnd ${prevEnd})`,
-                    details: {
-                        trackId: track.id,
-                        clipId: content.id,
-                        index: i,
-                        start: r.start,
-                        prevEnd,
-                    },
-                });
-                earlyExit = true;
-                break;
-            }
-            prevEnd = r.end;
-            total += r.end - r.start;
-        }
-        if (earlyExit)
-            continue;
-        const trimSpan = trimEnd - trimStart;
-        const expectedDuration = trimSpan - total;
-        // Tolerate float-roundoff at the millisecond level — wire is in seconds and
-        // editor / agent ops compute these with float math.
-        if (Math.abs(expectedDuration - content.duration) > 1e-3) {
-            violations.push({
-                code: "excluded_range_duration_mismatch",
-                message: `Track ${track.id}: TimelineClip ${content.id} duration (${content.duration}) ≠ trimSpan (${trimSpan}) − Σexcluded (${total}) = ${expectedDuration}`,
-                details: {
-                    trackId: track.id,
-                    clipId: content.id,
-                    expected: expectedDuration,
-                    actual: content.duration,
-                    trimSpan,
-                    totalExcluded: total,
-                },
-            });
-        }
-    }
-    return violations;
-}
-/** Combined per-track invariants. */
-/**
- * A media clip's `duration` must equal its trimmed source span divided by its
- * playback rate — for clips that have NO excluded ranges.
- *
- * `checkExcludedRanges` computes exactly this relationship, but returns early on
- * `if (!ranges || ranges.length === 0) continue`, so it only ever runs for clips
- * that HAVE excluded ranges. A plainly-trimmed clip whose duration disagrees
- * with its trim is therefore unchecked. This closes that gap; the two together
- * cover every media clip.
- *
- * HONEST PROVENANCE: found while chasing a suspected corruption that turned out
- * not to be one. A project showed `duration 2.4` against `trim {0, 3.4}`, which
- * looked inconsistent until the clip's `excludedRanges` ([1.9, 2.9]) accounted
- * for exactly the difference. The composition was fine and the existing check
- * passed it correctly. No known production case violates THIS rule — it is here
- * because the coverage hole is real, not because a bug was seen through it.
- */
-export function checkClipDurationMatchesTrim(track) {
-    const violations = [];
-    for (const content of track.contents) {
-        if (!isTimelineClip(content))
-            continue;
-        if (content.source.kind !== "media")
-            continue;
-        const trim = content.source.trim;
-        // No trim ⇒ source coordinates collapse to [0, duration] and the identity is
-        // vacuous; there is nothing to disagree with.
-        if (!trim)
-            continue;
-        const rate = content.source.playbackRate ?? 1;
-        if (!(rate > 0))
-            continue; // `playbackRate` is validated positive elsewhere
-        // Excluded ranges legitimately shorten the clip below its trim span, and
-        // `checkExcludedRanges` already owns that arithmetic. Do not double-report.
-        const excluded = content.source.excludedRanges;
-        if (excluded && excluded.length > 0)
-            continue;
-        const trimSpan = trim.end - trim.start;
-        const expected = trimSpan / rate;
-        if (Math.abs(expected - content.duration) > 1e-3) {
-            violations.push({
-                code: "clip_duration_trim_mismatch",
-                message: `Track ${track.id}: TimelineClip ${content.id} duration (${content.duration}) ≠ ` +
-                    `trimSpan (${trimSpan}) ÷ playbackRate (${rate}) = ${expected}`,
-                details: {
-                    trackId: track.id,
-                    clipId: content.id,
-                    expected,
-                    actual: content.duration,
-                    trimSpan,
-                    playbackRate: rate,
-                },
-            });
-        }
-    }
-    return violations;
-}
-export function checkTrack(track) {
-    return [
-        ...checkTrackContentsNoOverlap(track),
-        ...checkClipSourceTrackKind(track),
-        ...checkTransitions(track),
-        ...checkExcludedRanges(track),
-        ...checkClipDurationMatchesTrim(track),
-    ];
-}
-/** Combined per-composition invariants that live at the Track level. */
-export function checkTracks(composition) {
-    const out = [];
-    for (const track of composition.tracks) {
-        out.push(...checkTrack(track));
-    }
-    return out;
-}