@cueframe/kernel 0.0.1

package/dist/_members/composition/reframe/trajectory.js

@@ -0,0 +1,124 @@
+/** Clamp to [0,1]. */
+export function clip01(v) {
+    return Math.max(0, Math.min(1, v));
+}
+/**
+ * Cubic ease-out `1 - (1-t)^3` for t∈[0,1] — matches the legacy StillFrame's
+ * `Easing.out(Easing.cubic)` so motion decelerates ("settled").
+ */
+export function easeOutCubic(t) {
+    const x = Math.max(0, Math.min(1, t));
+    return 1 - (1 - x) * (1 - x) * (1 - x);
+}
+/**
+ * Per-frame crop-window zoom for an EASED segment. Holds at `targetZoom` through
+ * the body; ramps to/from full-frame (1.0) at the eased edges:
+ *   - `easeInSec` at the HEAD: 1.0 → targetZoom.
+ *   - `easeOutSec` at the TAIL: targetZoom → 1.0.
+ * Frame times are `frameIdx / srcFps` (segment-local). Edges clamp to the span.
+ */
+export function buildEasedZooms(frameCount, srcFps, targetZoom, easeInSec, easeOutSec) {
+    const segSec = frameCount / srcFps;
+    const inDur = Math.max(0, Math.min(easeInSec, segSec));
+    const outDur = Math.max(0, Math.min(easeOutSec, segSec));
+    const zooms = new Array(frameCount);
+    for (let i = 0; i < frameCount; i++) {
+        const tSec = i / srcFps;
+        let z = targetZoom;
+        if (inDur > 0 && tSec < inDur) {
+            const p = easeOutCubic(tSec / inDur);
+            z = 1.0 + (targetZoom - 1.0) * p;
+        }
+        else if (outDur > 0 && tSec > segSec - outDur) {
+            const p = easeOutCubic((tSec - (segSec - outDur)) / outDur);
+            z = targetZoom + (1.0 - targetZoom) * p;
+        }
+        zooms[i] = z;
+    }
+    return zooms;
+}
+/**
+ * Ramp per-frame CENTERS for a `point`-focus pan: from an ORIGIN
+ * (`point + biasOffset`) to the authored `point`, eased over `easeInSec` at the
+ * head (then held). Used by Ken-Burns `pan-l` / `pan-r`.
+ */
+export function buildPannedCenters(frameCount, srcFps, point, biasOffset, easeInSec) {
+    const segSec = frameCount / srcFps;
+    const inDur = Math.max(0, Math.min(easeInSec, segSec));
+    const origin = [point[0] + biasOffset[0], point[1] + biasOffset[1]];
+    const out = new Array(frameCount);
+    for (let i = 0; i < frameCount; i++) {
+        const tSec = i / srcFps;
+        const p = inDur > 0 ? easeOutCubic(Math.min(tSec / inDur, 1)) : 1;
+        out[i] = [
+            clip01(origin[0] + (point[0] - origin[0]) * p),
+            clip01(origin[1] + (point[1] - origin[1]) * p),
+        ];
+    }
+    return out;
+}
+/** Per-aspect caption keep-out band (fraction of output height). SSOT — the
+ *  execution derive imports this rather than re-declaring it. */
+export const CAPTION_BAND_RESERVE = {
+    "9:16": 0.15,
+    "4:5": 0.12,
+    "1:1": 0.1,
+    "16:9": 0.0,
+};
+/**
+ * Derive a FACELESS still-image trajectory from a `Reframe` (typically the one
+ * `kenBurnsToReframe` produced). A still has no detection, so every focus reduces
+ * to a constant authored center (`point` → `[x,y]`; everything else → frame-center
+ * `[0.5,0.5]`), and the only motion is the eased zoom (`buildEasedZooms`) / center
+ * pan (`buildPannedCenters`). Output is the SAME `TrajectoryData` shape the video
+ * path produces, so the renderer (CropFromTrajectory) consumes both identically.
+ *
+ * `srcW`/`srcH` are the IMAGE pixel dims (used by the renderer's crop-window math).
+ * Each segment's `[startSec, endSec)` × `fps` sets its per-frame series length.
+ * `fps` is the OUTPUT fps (the trajectory is sampled at this rate — `src_fps = fps`
+ * for a still, since the "source" is one frozen image with no native timeline).
+ */
+export function deriveStillTrajectory(reframe, srcW, srcH, fps, aspect, bakeVersion) {
+    const segments = [];
+    let cursorSec = 0;
+    for (const seg of reframe.segments) {
+        const startSec = seg.startSec;
+        const endSec = seg.endSec;
+        const frameCount = Math.max(1, Math.round((endSec - startSec) * fps));
+        // Faceless center: `point` → authored location; anything else → frame-center.
+        const point = seg.focus.mode === "point" ? [seg.focus.x, seg.focus.y] : [0.5, 0.5];
+        const isPan = seg.focus.mode === "point" && !!seg.ease && !!seg.bias;
+        const targetZoom = seg.zoom ?? 1;
+        const centers = isPan
+            ? buildPannedCenters(frameCount, fps, point, [seg.bias?.x ?? 0, seg.bias?.y ?? 0], seg.ease?.in ?? 0)
+            : new Array(frameCount).fill(null).map(() => [point[0], point[1]]);
+        // A pan expresses its motion via centers → zero the crop bias (mirror of the
+        // director's isEasedPan handling). Otherwise pass the authored bias through.
+        const verticalBias = isPan ? 0 : seg.bias?.y ?? 0;
+        const lateralBias = isPan ? 0 : seg.bias?.x ?? 0;
+        const zooms = seg.ease
+            ? buildEasedZooms(frameCount, fps, targetZoom, seg.ease.in, seg.ease.out)
+            : undefined;
+        segments.push({
+            idx: segments.length,
+            start_sec: cursorSec,
+            end_sec: cursorSec + frameCount / fps,
+            zoom_scale: targetZoom,
+            vertical_bias: verticalBias,
+            lateral_bias: lateralBias,
+            centers,
+            subjects: [],
+            caption_band_reserve: CAPTION_BAND_RESERVE[aspect] ?? 0,
+            ...(zooms ? { zooms } : {}),
+        });
+        cursorSec += frameCount / fps;
+    }
+    return {
+        bake_version: bakeVersion,
+        aspect,
+        src_w: srcW,
+        src_h: srcH,
+        src_fps: fps,
+        segments,
+    };
+}

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

@@ -0,0 +1,36 @@
+/**
+ * FLATTENING COMPOUND CLIPS.
+ *
+ * A `{kind:'composition'}` source is a reference; nothing downstream — the
+ * renderer, the evaluator, the still lane — knows how to draw a reference.
+ * Flattening resolves each compound clip into the child composition's own
+ * clips, shifted into the host's time and clipped to the compound's window,
+ * producing a composition with no compound sources left. It runs at the ONE
+ * translator every render lane already flows through, so a composition that
+ * embeds another renders identically on desktop, cloud and still lanes.
+ *
+ * Semantics, stated because each was a decision:
+ *
+ *   - The child's tracks come in as NEW tracks directly after the host track
+ *     carrying the compound clip (precomp semantics). Merging child clips into
+ *     the HOST's lanes would collide with whatever else the host has there,
+ *     and "my intro overwrote my b-roll" is not a bug anyone should meet.
+ *   - `trim` selects a window of the child's own timeline; the compound's
+ *     `duration` clips the result. Content beyond either is dropped, exactly
+ *     as a media trim drops frames.
+ *   - Child clip ids are prefixed with the compound clip's id, so two
+ *     instances of the same child in one host cannot collide.
+ *   - Child MARKERS are dropped. The host's marker lane is the host's.
+ *
+ * CYCLES AND DEPTH FAIL LOUD. A composition that embeds itself — directly or
+ * through a chain — has no finite flattening; and unbounded nesting is a
+ * stack-shaped denial of service. Both throw `InvariantError` rather than
+ * rendering something partial: a render that silently dropped an embedded
+ * sequence is a corrupted deliverable with a green checkmark.
+ */
+import type { Composition } from "../validators/composition.js";
+export declare const MAX_COMPOUND_DEPTH = 4;
+export type ResolveComposition = (compositionId: string) => Composition | undefined;
+/** Does this composition contain any compound clip at all? Cheap gate. */
+export declare function hasCompoundClips(composition: Pick<Composition, "tracks">): boolean;
+export declare function flattenCompoundClips(composition: Composition, resolve: ResolveComposition): Composition;

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

@@ -0,0 +1,134 @@
+import { InvariantError } from "../invariants/errors";
+import { retimeChannel } from "./keyframes";
+export const MAX_COMPOUND_DEPTH = 4;
+/** Does this composition contain any compound clip at all? Cheap gate. */
+export function hasCompoundClips(composition) {
+    for (const track of composition.tracks) {
+        for (const item of track.contents) {
+            if ("source" in item && item.source.kind === "composition")
+                return true;
+        }
+    }
+    return false;
+}
+export function flattenCompoundClips(composition, resolve) {
+    return flatten(composition, resolve, [], 0);
+}
+function flatten(composition, resolve, path, depth) {
+    if (!hasCompoundClips(composition))
+        return composition;
+    if (depth >= MAX_COMPOUND_DEPTH) {
+        throw new InvariantError({
+            code: "compound_depth_exceeded",
+            message: `compound clips nest deeper than ${MAX_COMPOUND_DEPTH} ` +
+                `(path: ${path.join(" → ") || "(root)"}) — flattening refused`,
+            details: { path, maxDepth: MAX_COMPOUND_DEPTH },
+        });
+    }
+    const outTracks = [];
+    for (const track of composition.tracks) {
+        const kept = [];
+        /** Tracks minted from compound children on this host track, in order. */
+        const minted = [];
+        for (const item of track.contents) {
+            if (!("source" in item) || item.source.kind !== "composition") {
+                kept.push(item);
+                continue;
+            }
+            const compound = item;
+            const source = compound.source;
+            if (path.includes(source.compositionId)) {
+                throw new InvariantError({
+                    code: "compound_cycle",
+                    message: `composition "${source.compositionId}" embeds itself ` +
+                        `(${[...path, source.compositionId].join(" → ")}) — there is no finite flattening`,
+                    details: { cycle: [...path, source.compositionId] },
+                });
+            }
+            const child = resolve(source.compositionId);
+            if (!child) {
+                throw new InvariantError({
+                    code: "compound_unresolved",
+                    message: `clip "${compound.id}" embeds composition "${source.compositionId}", ` +
+                        `which the caller could not resolve — rendering without it would ship a ` +
+                        `deliverable missing a sequence`,
+                    details: { clipId: compound.id, compositionId: source.compositionId },
+                });
+            }
+            const flatChild = flatten(child, resolve, [...path, source.compositionId], depth + 1);
+            // Minted tracks inherit the HOST track's disabled state — a compound clip
+            // on a muted track must vanish with it, not outlive it on lanes of its
+            // own (review finding 2026-08-24).
+            const projected = projectChild(flatChild, compound, source);
+            minted.push(...(track.enabled === false
+                ? projected.map((t) => ({ ...t, enabled: false }))
+                : projected));
+        }
+        outTracks.push({ ...track, contents: kept });
+        outTracks.push(...minted);
+    }
+    return { ...composition, tracks: outTracks };
+}
+/** The child's tracks, windowed and shifted into the host's time. */
+function projectChild(child, compound, source) {
+    const windowStart = source.trim?.start ?? 0;
+    const windowEnd = Math.min(source.trim?.end ?? Number.POSITIVE_INFINITY, windowStart + compound.duration);
+    const out = [];
+    for (const track of child.tracks) {
+        const contents = [];
+        for (const item of track.contents) {
+            if (!("source" in item))
+                continue;
+            const clip = item;
+            const clipEnd = clip.startTime + clip.duration;
+            const start = Math.max(clip.startTime, windowStart);
+            const end = Math.min(clipEnd, windowEnd);
+            if (end - start <= 1e-6)
+                continue; // outside the window
+            const headDelta = start - clip.startTime;
+            const duration = end - start;
+            const projected = {
+                ...clip,
+                id: `${compound.id}:${clip.id}`,
+                startTime: compound.startTime + (start - windowStart),
+                duration,
+                source: windowedSource(clip, headDelta, duration),
+                ...(clip.animate ? { animate: windowedAnimate(clip, headDelta, duration) } : {}),
+                // A child's link group must not merge with an identically-named one in
+                // the host or a sibling instance — scope it like the ids.
+                ...(clip.linkGroupId ? { linkGroupId: `${compound.id}:${clip.linkGroupId}` } : {}),
+            };
+            contents.push(projected);
+        }
+        if (contents.length > 0) {
+            out.push({
+                ...track,
+                id: `${compound.id}:${track.id}`,
+                contents,
+            });
+        }
+    }
+    return out;
+}
+/** The clip's source with its own window advanced by the flatten cut. */
+function windowedSource(clip, headDelta, duration) {
+    const source = clip.source;
+    if (source.kind !== "media" || !source.trim)
+        return source;
+    const rate = source.playbackRate ?? 1;
+    const start = source.trim.start + headDelta * rate;
+    return { ...source, trim: { start, end: start + duration * rate } };
+}
+function windowedAnimate(clip, headDelta, duration) {
+    if (!clip.animate)
+        return undefined;
+    const out = {};
+    for (const [param, channel] of Object.entries(clip.animate)) {
+        if (!channel)
+            continue;
+        const retimed = retimeChannel(channel, headDelta, duration);
+        if (retimed.length >= 2)
+            out[param] = retimed;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}

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

@@ -0,0 +1,9 @@
+export * from "./occupancy.js";
+export * from "./plan.js";
+export * from "./placement.js";
+export * from "./resolve.js";
+export * from "./keyframes.js";
+export * from "./compound.js";
+export * from "./trims.js";
+export * from "./link.js";
+export * from "./intent.js";

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

@@ -0,0 +1,9 @@
+export * from "./occupancy";
+export * from "./plan";
+export * from "./placement";
+export * from "./resolve";
+export * from "./keyframes";
+export * from "./compound";
+export * from "./trims";
+export * from "./link";
+export * from "./intent";

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

@@ -0,0 +1,54 @@
+/**
+ * INTENT → PLAN.
+ *
+ * The single entry point every gesture goes through. A caller says what it
+ * wants in timeline terms — "these clips, to this track, starting here" — and
+ * gets back a plan it can apply or a set of named refusals it can render. It
+ * never gets back a mutation.
+ *
+ * WHY THIS EXISTS AT ALL. The drag path used to do its own placement inline:
+ * hit-test a Y coordinate, look up the track, check kind compatibility, commit.
+ * It had no occupancy test (so two clips could be stacked at identical times on
+ * one track), no way to mint a lane, and no way to say why a drag was refused —
+ * the user just got a silent snap-back. Meanwhile the occupancy test, the
+ * placement resolver and TWO separate overlap invariant checkers all existed and
+ * none of them ran in production.
+ *
+ * The fix is not to add a call to the drag path. It is to make a drag path that
+ * skips placement unrepresentable, by giving the applier nothing to accept
+ * except the value this module produces.
+ */
+import type { Composition } from "../validators/composition.js";
+import type { OverlapPolicy } from "./resolve.js";
+import type { TimelinePlan } from "./plan.js";
+/** One clip's requested destination. */
+export interface ClipMove {
+    clipId: string;
+    /** Target lane. Same as the clip's current track for an in-lane slide. */
+    toTrackId: string;
+    startTime: number;
+    /** Timeline duration after the gesture — unchanged for a pure move. */
+    duration: number;
+}
+export interface MoveIntent {
+    type: "moveClips";
+    moves: readonly ClipMove[];
+    /** Default `resolve`; `refuse` is for callers that want a dry-run answer. */
+    policy?: OverlapPolicy;
+    label?: string;
+}
+export interface ResolveIntentArgs {
+    composition: Pick<Composition, "tracks">;
+    intent: MoveIntent;
+    newClipId: () => string;
+}
+export declare function resolveMoveIntent(args: ResolveIntentArgs): TimelinePlan;
+/**
+ * The gate's read-only half: does this composition still satisfy the one rule
+ * the move path exists to protect? Kept next to the resolver so a resolution
+ * bug fails here rather than reaching the document.
+ */
+export declare function planLeavesOverlaps(composition: Pick<Composition, "tracks">): Array<{
+    trackId: string;
+    clipIds: [string, string];
+}>;

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

@@ -0,0 +1,228 @@
+import { collidingClips } from "./occupancy";
+import { resolvePlacement } from "./placement";
+import { resolveOverlaps } from "./resolve";
+import { emptyPlan } from "./plan";
+import { expandClipIdsToLinkGroups } from "./link";
+/** Occupancy rows only — the full clip rows come from `clipsById`. */
+function projectTracks(composition) {
+    return composition.tracks.map((t) => ({
+        id: t.id,
+        kind: t.kind,
+        contents: t.contents
+            .filter((c) => "source" in c && !!c.id)
+            .map((c) => ({ id: c.id, startTime: c.startTime, duration: c.duration })),
+    }));
+}
+function indexClips(composition) {
+    const clipsById = new Map();
+    const trackIdByClipId = new Map();
+    for (const track of composition.tracks) {
+        for (const item of track.contents) {
+            if (!("source" in item))
+                continue;
+            const clip = item;
+            clipsById.set(clip.id, clip);
+            trackIdByClipId.set(clip.id, track.id);
+        }
+    }
+    return { clipsById, trackIdByClipId };
+}
+/** `source.kind` is what compatibility is judged on, not the track family. */
+const sourceKindOf = (clip) => clip.source.kind;
+/** Keep the mutable occupancy in step with the ops we just emitted. */
+function applyOpsToOccupancy(track, ops) {
+    for (const op of ops) {
+        switch (op.op) {
+            case "removeClip":
+                track.contents = track.contents.filter((c) => c.id !== op.clipId);
+                break;
+            case "updateClip": {
+                const row = track.contents.find((c) => c.id === op.clipId);
+                if (!row)
+                    break;
+                if (op.patch.startTime != null)
+                    row.startTime = op.patch.startTime;
+                if (op.patch.duration != null)
+                    row.duration = op.patch.duration;
+                break;
+            }
+            case "insertClip":
+                track.contents.push({
+                    id: op.clip.id,
+                    startTime: op.clip.startTime,
+                    duration: op.clip.duration,
+                });
+                break;
+            default:
+                break;
+        }
+    }
+}
+/**
+ * Every requested move, plus one per unrequested link partner shifted by the
+ * same delta. A partner already named explicitly is not duplicated.
+ */
+function expandMovesToLinkGroups(composition, moves, clipsById) {
+    const named = new Set(moves.map((m) => m.clipId));
+    const out = [...moves];
+    for (const move of moves) {
+        const clip = clipsById.get(move.clipId);
+        if (!clip?.linkGroupId)
+            continue;
+        const delta = move.startTime - clip.startTime;
+        for (const partnerId of expandClipIdsToLinkGroups(composition, [move.clipId])) {
+            if (named.has(partnerId))
+                continue;
+            const partner = clipsById.get(partnerId);
+            if (!partner)
+                continue;
+            named.add(partnerId);
+            out.push({
+                clipId: partnerId,
+                // The partner keeps its own lane — linking couples TIME, not track.
+                toTrackId: trackIdOf(composition, partnerId) ?? move.toTrackId,
+                startTime: Math.max(0, partner.startTime + delta),
+                duration: partner.duration,
+            });
+        }
+    }
+    return out;
+}
+function trackIdOf(composition, clipId) {
+    for (const track of composition.tracks) {
+        for (const item of track.contents) {
+            if ("source" in item && item.id === clipId)
+                return track.id;
+        }
+    }
+    return null;
+}
+export function resolveMoveIntent(args) {
+    const { composition, intent, newClipId } = args;
+    const policy = intent.policy ?? "resolve";
+    const plan = emptyPlan(intent.label ?? (intent.moves.length > 1 ? "Move clips" : "Move clip"));
+    const { clipsById, trackIdByClipId } = indexClips(composition);
+    const tracks = projectTracks(composition);
+    // A move that names one member of a link group moves the whole group, by the
+    // same delta. Selection expansion already covers the UI path; this covers the
+    // agent's, which names clip ids directly and never went through a selection.
+    const withPartners = expandMovesToLinkGroups(composition, intent.moves, clipsById);
+    const movingIds = withPartners.map((m) => m.clipId);
+    // Every moving clip leaves its lane before anything is placed, so a clip
+    // never collides with where it used to be — including the whole group, which
+    // is why this is done up front rather than per move.
+    for (const track of tracks) {
+        track.contents = track.contents.filter((c) => !movingIds.includes(c.id));
+    }
+    const selection = [];
+    for (const move of withPartners) {
+        const clip = clipsById.get(move.clipId);
+        if (!clip) {
+            plan.refusals.push({ reason: "clip-not-found", entity: { kind: "clip", clipId: move.clipId } });
+            continue;
+        }
+        if (!(move.duration > 0)) {
+            plan.refusals.push({ reason: "zero-duration", entity: { kind: "clip", clipId: move.clipId } });
+            continue;
+        }
+        const startTime = Math.max(0, move.startTime);
+        const span = { startTime, duration: move.duration, excludeClipIds: movingIds };
+        // `allowOccupied` — a user dragging a clip onto a busy lane means "put it
+        // there and deal with what is in the way", not "find me somewhere near it".
+        const placement = resolvePlacement({
+            tracks,
+            sourceKind: sourceKindOf(clip),
+            spans: [span],
+            strategy: { type: "explicit", trackId: move.toTrackId },
+            allowOccupied: true,
+        });
+        if (placement.kind === "refused") {
+            plan.refusals.push({
+                reason: placement.reason,
+                entity: { kind: "clip", clipId: move.clipId },
+            });
+            continue;
+        }
+        if (placement.kind === "newTrack") {
+            // `explicit` + `allowOccupied` never mints a lane; a newTrack result here
+            // would mean the resolver changed under us. Refuse rather than invent one.
+            plan.refusals.push({
+                reason: "track-not-found",
+                entity: { kind: "clip", clipId: move.clipId },
+            });
+            continue;
+        }
+        const target = tracks[placement.trackIndex];
+        const trackKind = placement.trackKind;
+        const resolution = resolveOverlaps({
+            track: target,
+            trackKind,
+            span,
+            policy,
+            clipsById,
+            newClipId,
+        });
+        if (resolution.refusals.length > 0) {
+            plan.refusals.push(...resolution.refusals);
+            // A move that cannot clear its landing zone is not applied at all — a
+            // partial group move is worse than none, because half a gesture is a
+            // state the user did not ask for and cannot name in undo.
+            continue;
+        }
+        plan.ops.push(...resolution.ops);
+        applyOpsToOccupancy(target, resolution.ops);
+        const fromTrackId = trackIdByClipId.get(move.clipId);
+        if (fromTrackId !== placement.trackId) {
+            plan.ops.push({
+                op: "moveToTrack",
+                clipId: move.clipId,
+                toTrackId: placement.trackId,
+                startTime,
+            });
+            // `moveClipToTrack` preserves duration, so a gesture that also resized
+            // needs the geometry patch after the move.
+            if (Math.abs(move.duration - clip.duration) > 1e-6) {
+                plan.ops.push({
+                    op: "updateClip",
+                    clipId: move.clipId,
+                    trackKind,
+                    patch: { duration: move.duration },
+                });
+            }
+        }
+        else {
+            plan.ops.push({
+                op: "updateClip",
+                clipId: move.clipId,
+                trackKind,
+                patch: { startTime, duration: move.duration },
+            });
+        }
+        target.contents.push({ id: move.clipId, startTime, duration: move.duration });
+        selection.push({ kind: "clip", clipId: move.clipId });
+    }
+    plan.resultingSelection = selection;
+    return plan;
+}
+/**
+ * The gate's read-only half: does this composition still satisfy the one rule
+ * the move path exists to protect? Kept next to the resolver so a resolution
+ * bug fails here rather than reaching the document.
+ */
+export function planLeavesOverlaps(composition) {
+    const found = [];
+    for (const track of projectTracks(composition)) {
+        for (const row of track.contents) {
+            const others = collidingClips(track, {
+                startTime: row.startTime,
+                duration: row.duration,
+                excludeClipIds: [row.id],
+            });
+            for (const other of others) {
+                if (row.id < other.id)
+                    found.push({ trackId: track.id, clipIds: [row.id, other.id] });
+            }
+        }
+    }
+    return found;
+}

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

@@ -0,0 +1,50 @@
+/**
+ * READING A KEYFRAME CHANNEL.
+ *
+ * One interpolator, in the kernel, because three consumers need the same
+ * answer and any disagreement between them is visible as motion that differs
+ * between the editor preview, the still lane and the final render:
+ *
+ *   - the editor, drawing a value at the playhead;
+ *   - `render-entry`, computing the value for a frame;
+ *   - the evaluator, which grades stills and must grade what ships.
+ *
+ * Everything here is pure: given a channel and a clip-relative time, produce a
+ * number. No clip lookup, no composition, no React.
+ */
+import type { Keyframe, KeyframeChannel } from "../validators/composition.js";
+/** Named easings, as cubic-bezier control points. EXPORTED so the curve
+ *  editor draws exactly what the interpolator evaluates — a UI restating these
+ *  numbers is a curve that lies about the motion. */
+export declare const EASING_CONTROL_POINTS: Record<string, readonly [number, number, number, number]>;
+/**
+ * y at x for a cubic-bezier easing curve, x ∈ [0,1].
+ *
+ * Newton-Raphson with a bisection fallback — the standard approach, and the
+ * fallback matters: Newton diverges on the near-vertical segments that the
+ * overshoot presets (a "pop") deliberately have.
+ */
+export declare function bezierEasing(t: number, [x1, y1, x2, y2]: readonly [number, number, number, number]): number;
+/** Channel sorted by time. Authoring order is not guaranteed to be time order. */
+export declare function sortedChannel(channel: KeyframeChannel): Keyframe[];
+/**
+ * The channel's value at `clipTime` (seconds from the clip's start).
+ *
+ * Holds flat outside the channel's range rather than extrapolating — a value
+ * invented beyond the last keyframe is a value nobody authored, and for
+ * opacity or scale it is the difference between a clean hold and a fade to
+ * something absurd.
+ */
+export declare function valueAt(channel: KeyframeChannel, clipTime: number): number;
+/** True when this param is animated on this clip. */
+export declare function isAnimated(animate: Record<string, KeyframeChannel> | undefined, param: string): boolean;
+/**
+ * Re-time a channel for a clip whose window moved.
+ *
+ * The ONE case clip-relative time does not survive for free: trimming the head
+ * shifts every keyframe's origin. Keyframes that fall outside the new window
+ * are dropped rather than clamped — clamping would silently stack several onto
+ * the same instant, which is exactly the `varying_keyframe_duplicate_time`
+ * violation the invariants refuse.
+ */
+export declare function retimeChannel(channel: KeyframeChannel, headDelta: number, newDuration: number): Keyframe[];