@cueframe/kernel 0.0.1

package/dist/_members/composition/timeline/resolve.d.ts

@@ -0,0 +1,55 @@
+/**
+ * MAKING ROOM.
+ *
+ * When something lands on top of something else, an editor has to do one of
+ * four things, and the difference between them is the whole difference between
+ * "the app is a video editor" and "the app is a rectangle arranger":
+ *
+ *   covers      → the buried clip is gone; delete it
+ *   trims-head  → the buried clip loses its head; advance it, advance its trim
+ *   trims-tail  → the buried clip loses its tail; shorten it
+ *   engulfed-by → the buried clip is cut in two; the incoming clip sits between
+ *
+ * The first version of the gate REFUSED an overlapping move instead. That kills
+ * the defect but ships a worse experience than the defect did: a drag that does
+ * nothing reads as broken software. Refusal survives only as the last branch —
+ * when there is genuinely no legal resolution.
+ *
+ * TRIM IS THE PART THAT IS EASY TO GET WRONG. Shortening a media clip's timeline
+ * span without moving its source window makes the picture jump: the frames that
+ * play are no longer the frames the editor saw. Every edit here carries the
+ * source window with it, playback-rate aware.
+ */
+import type { TimelineClip } from "../validators/composition.js";
+import type { PlacementSpan, PlacementTrack, TrackKind } from "./occupancy.js";
+import type { RefusedPlacement, TimelinePlanOp } from "./plan.js";
+/** Timeline seconds below which a residue clip is not worth keeping. */
+export declare const MIN_RESIDUE_SECONDS = 0.04;
+export type OverlapPolicy = "resolve" | "refuse";
+/**
+ * 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 declare function trimForSubRange(clip: Pick<TimelineClip, "startTime" | "source">, newStartTime: number, newDuration: number): TimelineClip["source"] | undefined;
+export interface ResolveArgs {
+    track: PlacementTrack;
+    trackKind: TrackKind;
+    span: PlacementSpan;
+    policy: OverlapPolicy;
+    /** Full clip rows for the track, so trims can carry their source window. */
+    clipsById: ReadonlyMap<string, TimelineClip>;
+    /** Mints ids for the tail half of a split. Injected so the kernel stays pure. */
+    newClipId: () => string;
+}
+export interface ResolveResult {
+    ops: TimelinePlanOp[];
+    refusals: RefusedPlacement[];
+}
+/**
+ * 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 declare function resolveOverlaps(args: ResolveArgs): ResolveResult;

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

@@ -0,0 +1,170 @@
+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.d.ts

@@ -0,0 +1,54 @@
+/**
+ * SLIP, ROLL and SLIDE — the three trims that are not "drag an edge".
+ *
+ * The trim classifier knew move / left-trim / right-trim and nothing else, so
+ * every correction that keeps something else fixed was impossible:
+ *
+ *   SLIP   the clip stays exactly where it is; the SOURCE WINDOW moves inside
+ *          it. "Right beat, wrong framing" — the single most common correction
+ *          in content-aware editing, and the one this timeline could not make.
+ *
+ *   ROLL   the CUT between two neighbours moves; both durations change and
+ *          nothing after it shifts. Pacing, without re-timing the whole lane.
+ *
+ *   SLIDE  the clip MOVES and its neighbours absorb the difference; the clip's
+ *          own content is untouched and total duration is unchanged.
+ *
+ * All three are computed here, as pure functions returning plan ops, for the
+ * same reason placement is: the cloud director edits compositions too, and a
+ * trim rule that lives in the desktop is a rule the cloud does not have.
+ *
+ * Each returns `null` when the gesture is not legal rather than clamping to
+ * something almost-right — a slip past the end of the source is not "a smaller
+ * slip", it is a slip that cannot happen, and silently doing something else is
+ * how an editor stops trusting the tool.
+ */
+import type { Composition } from "../validators/composition.js";
+import type { TimelinePlan } from "./plan.js";
+/**
+ * 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 declare function planSlip(composition: Pick<Composition, "tracks">, clipId: string, deltaSeconds: number, sourceDuration: number): TimelinePlan | null;
+/**
+ * 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 declare function planRoll(composition: Pick<Composition, "tracks">, clipId: string, side: "left" | "right", deltaSeconds: number, sourceDurations: Readonly<Record<string, number>>): TimelinePlan | null;
+/**
+ * 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 declare function planSlide(composition: Pick<Composition, "tracks">, clipId: string, deltaSeconds: number, sourceDurations: Readonly<Record<string, number>>): TimelinePlan | null;

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

@@ -0,0 +1,278 @@
+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.d.ts

@@ -0,0 +1,8 @@
+export type { Composition, CompositionVersion, CompositionAuthorKind, Track, TimelineClip, Gap, Marker, Transition, ClipSource, Format, } from "../validators/composition.js";
+export type { BrandKit, FontRef, EasingValue } from "../validators/brandKit.js";
+export type { Font, FontVariant, FontStatus } from "../validators/font.js";
+export type { RenderJob, RenderSnapshot, RenderStatus, RenderPriority, RenderIntent, RenderMode, RenderCancelReason, RenderProgress, RenderProgressPhase, RegistryPin, Destination, DestinationResult, DestinationDeliveryStatus, } from "../validators/render.js";
+export type { PrimitiveRegistryEntry, PrimitiveOriginClass, PrimitiveMode, } from "../validators/registry.js";
+export type { Project } from "../validators/project.js";
+export type { Session, SessionMember, SessionMux, SessionMediaRole, } from "../validators/session.js";
+export type { Webhook, SubstrateWebhookEvent, WebhookDelivery, WebhookDeliveryStatus, } from "../validators/webhook.js";

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

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