@cueframe/kernel 0.0.1 → 0.1.1

package/dist/_members/composition/timeline/plan.js

@@ -1,31 +0,0 @@
-export const entityKey = (e) => {
-    switch (e.kind) {
-        case "clip":
-            return `clip:${e.clipId}`;
-        case "keyframe":
-            return `kf:${e.clipId}:${e.param}:${e.index}`;
-        case "transition":
-            return `tr:${e.clipId}`;
-        case "marker":
-            return `mk:${e.markerId}`;
-    }
-};
-const REFUSAL_TEXT = {
-    "incompatible-track": "That track cannot hold this kind of clip",
-    "track-not-found": "That track is no longer on the timeline",
-    "no-compatible-track-kind": "Nothing on this timeline can hold this kind of clip",
-    "clip-not-found": "That clip is no longer on the timeline",
-    "occupied-and-unresolvable": "There is no room there, and nothing that can be moved aside",
-    "zero-duration": "A clip needs a duration greater than zero",
-};
-export function refusalText(reason) {
-    return REFUSAL_TEXT[reason];
-}
-export const emptyPlan = (label) => ({
-    ops: [],
-    resultingSelection: [],
-    refusals: [],
-    label,
-});
-/** A plan that changes nothing is not applied; the caller snaps the UI back. */
-export const planIsNoop = (plan) => plan.ops.length === 0;

package/dist/_members/composition/timeline/resolve.js

@@ -1,170 +0,0 @@
-import { classifyOverlap, collidingClips } from "./occupancy";
-import { retimeChannel } from "./keyframes";
-/** Timeline seconds below which a residue clip is not worth keeping. */
-export const MIN_RESIDUE_SECONDS = 0.04;
-/**
- * The source window for a sub-range of an existing clip.
- *
- * `newStartTime`/`newDuration` are TIMELINE values; the trim window is SOURCE
- * values, so the delta is scaled by playbackRate. A clip with no trim window
- * (overlays, cards, components) has nothing to carry and returns undefined.
- */
-export function trimForSubRange(clip, newStartTime, newDuration) {
-    const source = clip.source;
-    if (source.kind !== "media" || !source.trim)
-        return undefined;
-    const rate = source.playbackRate ?? 1;
-    const headDelta = (newStartTime - clip.startTime) * rate;
-    const start = source.trim.start + headDelta;
-    const end = start + newDuration * rate;
-    // Never widen past what the original window actually covered — a resolution
-    // must only ever remove frames, never invent them.
-    const clampedStart = Math.max(source.trim.start, start);
-    const clampedEnd = Math.min(source.trim.end, end);
-    if (!(clampedEnd > clampedStart))
-        return undefined;
-    return { ...source, trim: { ...source.trim, start: clampedStart, end: clampedEnd } };
-}
-/**
- * Channels re-timed for a clip whose window changed.
- *
- * Returns undefined when there is nothing to carry, so callers can spread it
- * without inventing an empty `animate` key on clips that never had one.
- */
-function animateForSubRange(clip, newStartTime, newDuration) {
-    if (!clip.animate)
-        return undefined;
-    const headDelta = newStartTime - clip.startTime;
-    const out = {};
-    for (const [param, channel] of Object.entries(clip.animate)) {
-        if (!channel)
-            continue;
-        const retimed = retimeChannel(channel, headDelta, newDuration);
-        // A channel with fewer than two points no longer varies; dropping it lets
-        // the clip's scalar value take over rather than leaving a dead key behind.
-        if (retimed.length >= 2)
-            out[param] = retimed;
-    }
-    // Every channel dropped → undefined, not `{}` — an empty record is a key
-    // that says "animated" about a clip that is not.
-    return Object.keys(out).length > 0 ? out : undefined;
-}
-/**
- * Ops that clear `span` on `track`. Emits nothing when the span already fits,
- * which is the common case — resolution is the exception, not the rule.
- */
-export function resolveOverlaps(args) {
-    const { track, trackKind, span, policy, clipsById, newClipId } = args;
-    const collisions = collidingClips(track, span);
-    if (collisions.length === 0)
-        return { ops: [], refusals: [] };
-    if (policy === "refuse") {
-        return {
-            ops: [],
-            refusals: [{ reason: "occupied-and-unresolvable" }],
-        };
-    }
-    const ops = [];
-    const refusals = [];
-    const spanEnd = span.startTime + span.duration;
-    for (const collision of collisions) {
-        const clip = clipsById.get(collision.id);
-        if (!clip) {
-            // The occupancy row exists but the full clip does not — a projection bug,
-            // not a user error. Refuse rather than guess at the edit.
-            refusals.push({ reason: "clip-not-found", entity: { kind: "clip", clipId: collision.id } });
-            continue;
-        }
-        const clipEnd = clip.startTime + clip.duration;
-        switch (classifyOverlap(span, clip)) {
-            case "covers":
-                ops.push({ op: "removeClip", clipId: clip.id });
-                break;
-            case "trims-head": {
-                const newStart = spanEnd;
-                const newDuration = clipEnd - newStart;
-                if (newDuration < MIN_RESIDUE_SECONDS) {
-                    ops.push({ op: "removeClip", clipId: clip.id });
-                    break;
-                }
-                ops.push({
-                    op: "updateClip",
-                    clipId: clip.id,
-                    trackKind,
-                    patch: {
-                        startTime: newStart,
-                        duration: newDuration,
-                        source: trimForSubRange(clip, newStart, newDuration),
-                        animate: animateForSubRange(clip, newStart, newDuration),
-                    },
-                });
-                break;
-            }
-            case "trims-tail": {
-                const newDuration = span.startTime - clip.startTime;
-                if (newDuration < MIN_RESIDUE_SECONDS) {
-                    ops.push({ op: "removeClip", clipId: clip.id });
-                    break;
-                }
-                ops.push({
-                    op: "updateClip",
-                    clipId: clip.id,
-                    trackKind,
-                    patch: {
-                        duration: newDuration,
-                        source: trimForSubRange(clip, clip.startTime, newDuration),
-                        animate: animateForSubRange(clip, clip.startTime, newDuration),
-                    },
-                });
-                break;
-            }
-            case "engulfed-by": {
-                // Head half stays in place and shortens; tail half becomes a new clip
-                // starting where the incoming span ends. Both carry their own window.
-                const headDuration = span.startTime - clip.startTime;
-                const tailStart = spanEnd;
-                const tailDuration = clipEnd - tailStart;
-                const keepHead = headDuration >= MIN_RESIDUE_SECONDS;
-                const keepTail = tailDuration >= MIN_RESIDUE_SECONDS;
-                if (!keepHead && !keepTail) {
-                    ops.push({ op: "removeClip", clipId: clip.id });
-                    break;
-                }
-                if (keepHead) {
-                    ops.push({
-                        op: "updateClip",
-                        clipId: clip.id,
-                        trackKind,
-                        patch: {
-                            duration: headDuration,
-                            source: trimForSubRange(clip, clip.startTime, headDuration),
-                            animate: animateForSubRange(clip, clip.startTime, headDuration),
-                        },
-                    });
-                }
-                else {
-                    ops.push({ op: "removeClip", clipId: clip.id });
-                }
-                if (keepTail) {
-                    const tailSource = trimForSubRange(clip, tailStart, tailDuration) ?? clip.source;
-                    ops.push({
-                        op: "insertClip",
-                        trackId: track.id,
-                        clip: {
-                            ...clip,
-                            id: newClipId(),
-                            startTime: tailStart,
-                            duration: tailDuration,
-                            source: tailSource,
-                            ...(animateForSubRange(clip, tailStart, tailDuration)
-                                ? { animate: animateForSubRange(clip, tailStart, tailDuration) }
-                                : {}),
-                        },
-                    });
-                }
-                break;
-            }
-        }
-    }
-    return { ops, refusals };
-}

package/dist/_members/composition/timeline/trims.js

@@ -1,278 +0,0 @@
-import { retimeChannel } from "./keyframes";
-import { emptyPlan } from "./plan";
-import { linkPartners } from "./link";
-/** Below this a residue clip is not worth keeping. Matches `resolve.ts`. */
-const MIN_SECONDS = 0.04;
-function contextFor(composition, clipId) {
-    for (const track of composition.tracks) {
-        const clips = track.contents.filter((c) => "source" in c);
-        const ordered = [...clips].sort((a, b) => a.startTime - b.startTime);
-        const index = ordered.findIndex((c) => c.id === clipId);
-        if (index >= 0) {
-            return { trackKind: track.kind, ordered, index, clip: ordered[index] };
-        }
-    }
-    return null;
-}
-/** Source window bounds, when the clip has one. */
-function trimOf(clip) {
-    const source = clip.source;
-    if (source.kind !== "media" || !source.trim)
-        return null;
-    return { start: source.trim.start, end: source.trim.end, rate: source.playbackRate ?? 1 };
-}
-/**
- * SLIP — shift the source window by `deltaSeconds` of TIMELINE time, leaving
- * the clip's position and duration untouched.
- *
- * Refused when the clip has no source window (an overlay has nothing to slip)
- * or when the shift would run off either end of the source. `sourceDuration`
- * is required to police the far end — without it the far bound is unknowable
- * and a "successful" slip could point past the end of the media.
- */
-export function planSlip(composition, clipId, deltaSeconds, sourceDuration) {
-    const ctx = contextFor(composition, clipId);
-    if (!ctx)
-        return null;
-    const trim = trimOf(ctx.clip);
-    if (!trim)
-        return null;
-    const shift = deltaSeconds * trim.rate;
-    const start = trim.start + shift;
-    const end = trim.end + shift;
-    if (start < 0 || end > sourceDuration)
-        return null;
-    if (Math.abs(shift) < 1e-6)
-        return null;
-    const plan = emptyPlan("Slip clip");
-    const source = ctx.clip.source;
-    plan.ops.push({
-        op: "updateClip",
-        clipId,
-        trackKind: ctx.trackKind,
-        patch: {
-            // startTime and duration are DELIBERATELY absent: that is what makes this
-            // a slip rather than a move.
-            source: { ...source, trim: { ...source.trim, start, end } },
-        },
-    });
-    // LINK PARTNERS SLIP TOO, by the same delta. Slipping the video of an A/V
-    // pair without its audio is a lipsync break wearing a feature's name — the
-    // link seam covers selection and moves, and the trims must honour it as
-    // well (review pass 2, 2026-08-24). A partner that cannot make the same
-    // shift (no window, or it would run off ITS source) refuses the WHOLE slip:
-    // half a slip is the desync this exists to prevent.
-    for (const partnerId of linkPartners(composition, clipId)) {
-        const partnerCtx = contextFor(composition, partnerId);
-        if (!partnerCtx)
-            return null;
-        const partnerTrim = trimOf(partnerCtx.clip);
-        if (!partnerTrim)
-            return null;
-        const pShift = deltaSeconds * partnerTrim.rate;
-        const pStart = partnerTrim.start + pShift;
-        const pEnd = partnerTrim.end + pShift;
-        if (pStart < 0 || pEnd > sourceDuration)
-            return null;
-        const pSource = partnerCtx.clip.source;
-        plan.ops.push({
-            op: "updateClip",
-            clipId: partnerId,
-            trackKind: partnerCtx.trackKind,
-            patch: {
-                source: {
-                    ...pSource,
-                    trim: { ...pSource.trim, start: pStart, end: pEnd },
-                },
-            },
-        });
-    }
-    plan.resultingSelection = [{ kind: "clip", clipId }];
-    return plan;
-}
-/**
- * ROLL — move the cut between `clipId` and the neighbour on the given side.
- *
- * Both clips change duration; the outer edges and everything downstream stay
- * put. Refused when either side would fall below the minimum, or when either
- * side lacks the source to cover its new length.
- */
-export function planRoll(composition, clipId, side, deltaSeconds, sourceDurations) {
-    const ctx = contextFor(composition, clipId);
-    if (!ctx)
-        return null;
-    // REFUSED on a linked clip. A roll moves this lane's cut and nothing else,
-    // which silently desyncs the pair on the other lane — and a paired roll (the
-    // multi-track edit that would keep them together) is not built. Refusal is
-    // honest; a desync wearing a roll's name is not (review pass 2, 2026-08-24).
-    if (linkPartners(composition, clipId).length > 0)
-        return null;
-    const neighbour = side === "left" ? ctx.ordered[ctx.index - 1] : ctx.ordered[ctx.index + 1];
-    if (!neighbour)
-        return null;
-    // Only a genuine seam rolls. Two clips with a gap between them have no shared
-    // cut to move, and pretending otherwise would silently close the gap.
-    const seamOk = side === "left"
-        ? Math.abs(neighbour.startTime + neighbour.duration - ctx.clip.startTime) < 1e-6
-        : Math.abs(ctx.clip.startTime + ctx.clip.duration - neighbour.startTime) < 1e-6;
-    if (!seamOk)
-        return null;
-    const ops = [];
-    const clipPatch = {};
-    const neighbourPatch = {};
-    if (side === "left") {
-        const clipStart = ctx.clip.startTime + deltaSeconds;
-        const clipDuration = ctx.clip.duration - deltaSeconds;
-        const neighbourDuration = neighbour.duration + deltaSeconds;
-        if (clipDuration < MIN_SECONDS || neighbourDuration < MIN_SECONDS)
-            return null;
-        if (!windowCovers(ctx.clip, deltaSeconds, clipDuration, sourceDurations, "head"))
-            return null;
-        if (!windowCovers(neighbour, 0, neighbourDuration, sourceDurations, "tail"))
-            return null;
-        Object.assign(clipPatch, {
-            startTime: clipStart,
-            duration: clipDuration,
-            ...subRange(ctx.clip, deltaSeconds, clipDuration),
-        });
-        Object.assign(neighbourPatch, {
-            duration: neighbourDuration,
-            ...subRange(neighbour, 0, neighbourDuration),
-        });
-    }
-    else {
-        const clipDuration = ctx.clip.duration + deltaSeconds;
-        const neighbourStart = neighbour.startTime + deltaSeconds;
-        const neighbourDuration = neighbour.duration - deltaSeconds;
-        if (clipDuration < MIN_SECONDS || neighbourDuration < MIN_SECONDS)
-            return null;
-        if (!windowCovers(ctx.clip, 0, clipDuration, sourceDurations, "tail"))
-            return null;
-        if (!windowCovers(neighbour, deltaSeconds, neighbourDuration, sourceDurations, "head"))
-            return null;
-        Object.assign(clipPatch, {
-            duration: clipDuration,
-            ...subRange(ctx.clip, 0, clipDuration),
-        });
-        Object.assign(neighbourPatch, {
-            startTime: neighbourStart,
-            duration: neighbourDuration,
-            ...subRange(neighbour, deltaSeconds, neighbourDuration),
-        });
-    }
-    ops.push({ op: "updateClip", clipId, trackKind: ctx.trackKind, patch: clipPatch });
-    ops.push({
-        op: "updateClip",
-        clipId: neighbour.id,
-        trackKind: ctx.trackKind,
-        patch: neighbourPatch,
-    });
-    const plan = emptyPlan("Roll edit");
-    plan.ops = ops;
-    plan.resultingSelection = [{ kind: "clip", clipId }];
-    return plan;
-}
-/**
- * SLIDE — move the clip in time; its neighbours absorb the difference.
- *
- * The clip's own content and duration are untouched; the previous clip grows
- * or shrinks and the next one does the opposite, so nothing beyond the pair
- * moves. Refused without neighbours on both sides — a slide with nothing to
- * absorb into is just a move, and the caller should ask for that instead.
- */
-export function planSlide(composition, clipId, deltaSeconds, sourceDurations) {
-    const ctx = contextFor(composition, clipId);
-    if (!ctx)
-        return null;
-    // Same refusal as roll, for the same reason — a slide re-times the clip and
-    // BOTH neighbours on this lane only.
-    if (linkPartners(composition, clipId).length > 0)
-        return null;
-    const before = ctx.ordered[ctx.index - 1];
-    const after = ctx.ordered[ctx.index + 1];
-    if (!before || !after)
-        return null;
-    if (Math.abs(deltaSeconds) < 1e-6)
-        return null;
-    const beforeDuration = before.duration + deltaSeconds;
-    const afterStart = after.startTime + deltaSeconds;
-    const afterDuration = after.duration - deltaSeconds;
-    if (beforeDuration < MIN_SECONDS || afterDuration < MIN_SECONDS)
-        return null;
-    if (!windowCovers(before, 0, beforeDuration, sourceDurations, "tail"))
-        return null;
-    if (!windowCovers(after, deltaSeconds, afterDuration, sourceDurations, "head"))
-        return null;
-    const plan = emptyPlan("Slide clip");
-    plan.ops = [
-        {
-            op: "updateClip",
-            clipId: before.id,
-            trackKind: ctx.trackKind,
-            patch: { duration: beforeDuration, ...subRange(before, 0, beforeDuration) },
-        },
-        {
-            op: "updateClip",
-            clipId,
-            trackKind: ctx.trackKind,
-            // Content untouched — only where it sits.
-            patch: { startTime: ctx.clip.startTime + deltaSeconds },
-        },
-        {
-            op: "updateClip",
-            clipId: after.id,
-            trackKind: ctx.trackKind,
-            patch: {
-                startTime: afterStart,
-                duration: afterDuration,
-                ...subRange(after, deltaSeconds, afterDuration),
-            },
-        },
-    ];
-    plan.resultingSelection = [{ kind: "clip", clipId }];
-    return plan;
-}
-/**
- * Does the clip's source cover `newDuration` after moving its head by
- * `headDelta`? A clip with no window (an overlay, a card) has nothing to run
- * out of and always passes.
- */
-function windowCovers(clip, headDelta, newDuration, sourceDurations, grow) {
-    const trim = trimOf(clip);
-    if (!trim)
-        return true;
-    const start = trim.start + headDelta * trim.rate;
-    const end = start + newDuration * trim.rate;
-    if (start < 0)
-        return false;
-    const source = clip.source;
-    const total = source.kind === "media" ? sourceDurations[source.mediaId] : undefined;
-    if (grow === "tail" && total !== undefined && end > total + 1e-6)
-        return false;
-    return end > start;
-}
-/** The patch fields carrying a clip's window + keyframes into a new sub-range. */
-function subRange(clip, headDelta, newDuration) {
-    const out = {};
-    const trim = trimOf(clip);
-    if (trim) {
-        const start = trim.start + headDelta * trim.rate;
-        out.source = {
-            ...clip.source,
-            trim: { start, end: start + newDuration * trim.rate },
-        };
-    }
-    if (clip.animate) {
-        const animate = {};
-        for (const [param, channel] of Object.entries(clip.animate)) {
-            if (!channel)
-                continue;
-            const retimed = retimeChannel(channel, headDelta, newDuration);
-            if (retimed.length >= 2)
-                animate[param] = retimed;
-        }
-        if (Object.keys(animate).length > 0)
-            out.animate = animate;
-    }
-    return out;
-}

package/dist/_members/composition/types/index.js

@@ -1 +0,0 @@
-export {};