aivee 0.0.0-stage → 0.1.0-dev.7025438

package/src/timeline/fingerprint.mjs

@@ -0,0 +1,6 @@
+import { createHash } from 'node:crypto';
+
+/** Return a SHA-256 digest of a timeline object's JSON encoding. */
+export function timelineFingerprint(timeline) {
+  return createHash('sha256').update(JSON.stringify(timeline)).digest('hex');
+}

package/src/timeline/from-edl.mjs

@@ -0,0 +1,31 @@
+import { assertEdlApproved, validateEdl } from '../edits/retime-transcript.mjs';
+import { validateTimeline } from './validate.mjs';
+
+export function timelineFromEdl(edl, assetId, project = {}) {
+  validateEdl(edl, edl?.sourceDurationSeconds);
+  assertEdlApproved(edl);
+  if (!/^[a-z][a-z0-9-]*$/.test(assetId ?? '')) throw new TypeError('assetId must be a kebab-case id.');
+  const cuts = edl.cuts;
+  const clips = [];
+  let source = 0, timeline = 0;
+  for (let i = 0; i <= cuts.length; i++) {
+    const end = cuts[i]?.sourceStart ?? edl.sourceDurationSeconds;
+    if (end > source) {
+      const durationSeconds = end - source;
+      clips.push({ id: `clip-${clips.length + 1}`, assetId, sourceIn: source, sourceOut: end, timelineStart: timeline, durationSeconds });
+      timeline += durationSeconds;
+    }
+    if (cuts[i]) source = cuts[i].sourceEnd;
+  }
+  const tracks = [{ id: 'video-main', kind: 'video', order: 0, clips }];
+  if (project.includeAudioTrack) {
+    tracks.push({
+      id: 'audio-main',
+      kind: 'audio',
+      order: 1,
+      clips: clips.map((clip, index) => ({ ...clip, id: `audio-clip-${index + 1}` })),
+    });
+  }
+  const result = { schemaVersion: 1, project: { id: project.id ?? 'edited-video', width: project.width ?? 1920, height: project.height ?? 1080, fps: project.fps ?? 30, durationSeconds: timeline, ...(project.sourceFit === undefined ? {} : { sourceFit: project.sourceFit }), ...(project.backgroundColor === undefined ? {} : { backgroundColor: project.backgroundColor }) }, assets: [{ id: assetId, path: project.assetPath ?? 'assets/source.mp4', ...(project.assetType ? { type: project.assetType } : {}), ...(project.assetHasAudio !== undefined ? { hasAudio: project.assetHasAudio } : {}), ...(project.assetVideoStreams !== undefined ? { videoStreams: project.assetVideoStreams } : {}), ...(project.assetAudioStreams !== undefined ? { audioStreams: project.assetAudioStreams } : {}), ...(project.assetDurationSeconds !== undefined ? { durationSeconds: project.assetDurationSeconds } : {}), ...(project.assetStreamTiming !== undefined ? { streamTiming: project.assetStreamTiming } : {}) }], tracks };
+  return validateTimeline(result);
+}

package/src/timeline/history-store.mjs

@@ -0,0 +1,281 @@
+import { randomUUID } from 'node:crypto';
+import { closeSync, existsSync, lstatSync, openSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { editTimeline, editTimelineBatch } from './edit.mjs';
+import { validateTimeline } from './validate.mjs';
+import { timelineFingerprint } from './fingerprint.mjs';
+
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 100;
+const MAX_HISTORY_BYTES = 64 * 1024 * 1024;
+
+export function editTimelineFile(timelinePath, operation, { limit } = {}) {
+  return withHistoryLock(timelinePath, () => {
+    const history = loadHistory(timelinePath, limit, { createIfMissing: true });
+    const next = Array.isArray(operation)
+      ? editTimelineBatch(history.timeline, operation)
+      : editTimeline(history.timeline, operation);
+    const undo = [...history.undo, history.timeline].slice(-history.limit);
+    return commitHistory(timelinePath, {
+      ...history,
+      timeline: next,
+      timelineHash: hashTimeline(next),
+      previousTimelineHash: history.timelineHash,
+      undo,
+      redo: [],
+    });
+  });
+}
+
+/** Apply an explicitly approved review plan if it was created from the current timeline. */
+export function applyTimelineReviewPlan(timelinePath, plan, { limit } = {}) {
+  validateReviewPlan(plan);
+  return withHistoryLock(timelinePath, () => {
+    const { path, timeline } = readTimeline(timelinePath);
+    const baseHash = hashTimeline(timeline);
+    if (baseHash !== plan.baseTimelineSha256) {
+      throw new Error('Review plan is stale because the timeline changed after the plan was created. Generate a new plan.');
+    }
+    const next = editTimelineBatch(timeline, plan.operations);
+    const history = loadHistory(path, limit);
+    if (history.timelineHash !== baseHash) {
+      throw new Error('Review plan is stale because the timeline history changed after the plan was created. Generate a new plan.');
+    }
+    const undo = [...history.undo, history.timeline].slice(-history.limit);
+    const result = commitHistory(path, {
+      ...history,
+      timeline: next,
+      timelineHash: hashTimeline(next),
+      previousTimelineHash: history.timelineHash,
+      undo,
+      redo: [],
+    });
+    return {
+      ...result,
+      appliedReviewPlan: plan.type,
+      appliedOperationCount: plan.operations.length,
+    };
+  });
+}
+
+export function undoTimelineFile(timelinePath) {
+  return withHistoryLock(timelinePath, () => {
+    const history = loadHistory(timelinePath);
+    if (history.undo.length === 0) return describeHistory(history);
+    const undo = [...history.undo];
+    const timeline = undo.pop();
+    return commitHistory(timelinePath, {
+      ...history,
+      timeline,
+      timelineHash: hashTimeline(timeline),
+      previousTimelineHash: history.timelineHash,
+      undo,
+      redo: [...history.redo, history.timeline].slice(-history.limit),
+    });
+  });
+}
+
+export function redoTimelineFile(timelinePath) {
+  return withHistoryLock(timelinePath, () => {
+    const history = loadHistory(timelinePath);
+    if (history.redo.length === 0) return describeHistory(history);
+    const redo = [...history.redo];
+    const timeline = redo.pop();
+    return commitHistory(timelinePath, {
+      ...history,
+      timeline,
+      timelineHash: hashTimeline(timeline),
+      previousTimelineHash: history.timelineHash,
+      undo: [...history.undo, history.timeline].slice(-history.limit),
+      redo,
+    });
+  });
+}
+
+export function getTimelineFileHistory(timelinePath) {
+  return withHistoryLock(timelinePath, () => describeHistory(loadHistory(timelinePath)));
+}
+
+export function resetTimelineFileHistory(timelinePath, { limit = DEFAULT_LIMIT } = {}) {
+  validateLimit(limit);
+  return withHistoryLock(timelinePath, () => {
+    const { timeline } = readTimeline(timelinePath);
+    return commitHistory(timelinePath, {
+      schemaVersion: 1,
+      limit,
+      timeline,
+      timelineHash: hashTimeline(timeline),
+      previousTimelineHash: null,
+      undo: [],
+      redo: [],
+    });
+  });
+}
+
+function loadHistory(timelinePath, requestedLimit, { createIfMissing = false } = {}) {
+  if (requestedLimit !== undefined) validateLimit(requestedLimit);
+  const { path, timeline } = readTimeline(timelinePath);
+  const historyPath = getHistoryPath(path);
+  if (!existsSync(historyPath)) {
+    const state = {
+      schemaVersion: 1,
+      limit: requestedLimit ?? DEFAULT_LIMIT,
+      timeline,
+      timelineHash: hashTimeline(timeline),
+      previousTimelineHash: null,
+      undo: [],
+      redo: [],
+    };
+    if (createIfMissing) writeHistoryFile(historyPath, state);
+    return state;
+  }
+  if (lstatSync(historyPath).isSymbolicLink()) throw new TypeError('Timeline history file cannot be a symbolic link.');
+  if (statSync(historyPath).size > MAX_HISTORY_BYTES) throw new RangeError(`Timeline history exceeds the ${MAX_HISTORY_BYTES / 1024 / 1024} MiB limit.`);
+  const state = JSON.parse(readFileSync(historyPath, 'utf8'));
+  validateHistory(state);
+  if (requestedLimit !== undefined && requestedLimit !== state.limit) {
+    throw new TypeError(`Timeline history already uses limit ${state.limit}; reset it to change the limit.`);
+  }
+
+  const diskHash = hashTimeline(timeline);
+  if (diskHash === state.timelineHash) return state;
+  if (state.previousTimelineHash !== null && diskHash === state.previousTimelineHash) {
+    writeTimelineFile(path, state.timeline);
+    return state;
+  }
+  throw new Error(`Timeline changed outside its history session: ${path}. Use timeline history reset to start a new session.`);
+}
+
+function readTimeline(timelinePath) {
+  const path = resolve(timelinePath);
+  if (!existsSync(path)) throw new Error(`Timeline file not found: ${path}`);
+  if (lstatSync(path).isSymbolicLink()) throw new TypeError('Timeline file cannot be a symbolic link when using persistent history.');
+  const timeline = JSON.parse(readFileSync(path, 'utf8'));
+  validateTimeline(timeline);
+  return { path, timeline };
+}
+
+function commitHistory(timelinePath, state) {
+  const { path } = readTimeline(timelinePath);
+  validateHistory(state);
+  writeHistoryFile(getHistoryPath(path), state);
+  writeTimelineFile(path, state.timeline);
+  return describeHistory(state);
+}
+
+function withHistoryLock(timelinePath, operation) {
+  const timeline = resolve(timelinePath);
+  const lockPath = join(dirname(timeline), `.${basename(timeline)}.history.lock`);
+  let descriptor;
+  try {
+    descriptor = openSync(lockPath, 'wx');
+  } catch (error) {
+    if (error.code === 'EEXIST' && removeStaleHistoryLock(lockPath)) descriptor = openSync(lockPath, 'wx');
+    else if (error.code === 'EEXIST') throw new Error(`Timeline history is locked by another operation: ${lockPath}`);
+    else throw error;
+  }
+  try {
+    writeFileSync(descriptor, JSON.stringify({ pid: process.pid, createdAt: Date.now() }));
+    return operation();
+  } finally {
+    closeSync(descriptor);
+    unlinkSync(lockPath);
+  }
+}
+
+function removeStaleHistoryLock(lockPath) {
+  try {
+    if (lstatSync(lockPath).isSymbolicLink()) throw new TypeError('Timeline history lock cannot be a symbolic link.');
+    const lock = JSON.parse(readFileSync(lockPath, 'utf8'));
+    if (!Number.isSafeInteger(lock.pid) || lock.pid <= 0) {
+      if (Date.now() - statSync(lockPath).mtimeMs < 30_000) return false;
+      unlinkSync(lockPath);
+      return true;
+    }
+    try {
+      process.kill(lock.pid, 0);
+      return false;
+    } catch (error) {
+      if (error.code !== 'ESRCH') return false;
+    }
+    unlinkSync(lockPath);
+    return true;
+  } catch (error) {
+    if (error.code === 'ENOENT') return true;
+    if (error instanceof SyntaxError && Date.now() - statSync(lockPath).mtimeMs >= 30_000) {
+      unlinkSync(lockPath);
+      return true;
+    }
+    return false;
+  }
+}
+
+function validateHistory(state) {
+  if (!state || state.schemaVersion !== 1 || !Number.isSafeInteger(state.limit)
+      || state.limit < 1 || state.limit > MAX_LIMIT || !Array.isArray(state.undo)
+      || !Array.isArray(state.redo) || state.undo.length > state.limit
+      || state.redo.length > state.limit || !/^[\da-f]{64}$/.test(state.timelineHash ?? '')
+      || (state.previousTimelineHash !== null && !/^[\da-f]{64}$/.test(state.previousTimelineHash ?? ''))) {
+    throw new TypeError('Persistent timeline history has an invalid schema.');
+  }
+  validateTimeline(state.timeline);
+  for (const snapshot of [...state.undo, ...state.redo]) validateTimeline(snapshot);
+  if (hashTimeline(state.timeline) !== state.timelineHash) throw new TypeError('Persistent timeline history snapshot does not match its fingerprint.');
+}
+
+function validateLimit(limit) {
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_LIMIT) {
+    throw new TypeError(`Timeline history limit must be an integer from 1 to ${MAX_LIMIT}.`);
+  }
+}
+
+function describeHistory(state) {
+  return {
+    schemaVersion: 1,
+    canUndo: state.undo.length > 0,
+    canRedo: state.redo.length > 0,
+    undoDepth: state.undo.length,
+    redoDepth: state.redo.length,
+    limit: state.limit,
+  };
+}
+
+function writeHistoryFile(path, state) {
+  const content = `${JSON.stringify(state, null, 2)}\n`;
+  if (Buffer.byteLength(content) > MAX_HISTORY_BYTES) {
+    throw new RangeError(`Timeline history exceeds the ${MAX_HISTORY_BYTES / 1024 / 1024} MiB limit.`);
+  }
+  writeAtomically(path, content);
+}
+
+function writeTimelineFile(path, timeline) {
+  writeAtomically(path, `${JSON.stringify(timeline, null, 2)}\n`);
+}
+
+function writeAtomically(path, content) {
+  const temporaryPath = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
+  try {
+    writeFileSync(temporaryPath, content, { flag: 'wx' });
+    renameSync(temporaryPath, path);
+  } finally {
+    rmSync(temporaryPath, { force: true });
+  }
+}
+
+function getHistoryPath(timelinePath) {
+  return join(dirname(timelinePath), `.${basename(timelinePath)}.history.json`);
+}
+
+function hashTimeline(timeline) {
+  return timelineFingerprint(timeline);
+}
+
+function validateReviewPlan(plan) {
+  if (!plan || typeof plan !== 'object' || Array.isArray(plan)
+      || plan.schemaVersion !== 1 || plan.reviewRequired !== true
+      || !/^[a-z][a-z0-9-]*$/.test(plan.type ?? '')
+      || !/^[a-f0-9]{64}$/.test(plan.baseTimelineSha256 ?? '')
+      || !Array.isArray(plan.operations) || plan.operations.length === 0 || plan.operations.length > 2000) {
+    throw new TypeError('Review plan must be a schemaVersion 1 review-required plan with a SHA-256 timeline base and 1–2000 operations.');
+  }
+}

package/src/timeline/history.mjs

@@ -0,0 +1,69 @@
+import { editTimeline, editTimelineBatch } from './edit.mjs';
+import { validateTimeline } from './validate.mjs';
+
+const DEFAULT_HISTORY_LIMIT = 100;
+
+/** Create an isolated, bounded undo/redo history for immutable timeline edits. */
+export function createTimelineHistory(timeline, { limit = DEFAULT_HISTORY_LIMIT } = {}) {
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > 10_000) {
+    throw new TypeError('Timeline history limit must be an integer from 1 to 10000.');
+  }
+
+  validateTimeline(timeline);
+  let current = structuredClone(timeline);
+  const undoStack = [];
+  const redoStack = [];
+
+  return Object.freeze({
+    get current() {
+      return structuredClone(current);
+    },
+    get canUndo() {
+      return undoStack.length > 0;
+    },
+    get canRedo() {
+      return redoStack.length > 0;
+    },
+    get undoDepth() {
+      return undoStack.length;
+    },
+    get redoDepth() {
+      return redoStack.length;
+    },
+    apply(operation) {
+      const next = editTimeline(current, operation);
+      undoStack.push(current);
+      if (undoStack.length > limit) undoStack.shift();
+      current = next;
+      redoStack.length = 0;
+      return structuredClone(current);
+    },
+    applyBatch(operations) {
+      const next = editTimelineBatch(current, operations);
+      undoStack.push(current);
+      if (undoStack.length > limit) undoStack.shift();
+      current = next;
+      redoStack.length = 0;
+      return structuredClone(current);
+    },
+    undo() {
+      if (undoStack.length === 0) return structuredClone(current);
+      redoStack.push(current);
+      current = undoStack.pop();
+      return structuredClone(current);
+    },
+    redo() {
+      if (redoStack.length === 0) return structuredClone(current);
+      undoStack.push(current);
+      current = redoStack.pop();
+      return structuredClone(current);
+    },
+    reset(nextTimeline) {
+      validateTimeline(nextTimeline);
+      current = structuredClone(nextTimeline);
+      undoStack.length = 0;
+      redoStack.length = 0;
+      return structuredClone(current);
+    },
+  });
+}

package/src/timeline/inspect.mjs

@@ -0,0 +1,117 @@
+import { validateTimeline } from './validate.mjs';
+
+/** Return a compact, deterministic editing overview for agents and review tools. */
+export function inspectTimeline(timeline) {
+  validateTimeline(timeline);
+  const assets = new Map(timeline.assets.map((asset) => [asset.id, asset]));
+  const tracks = [...timeline.tracks]
+    .sort((left, right) => left.order - right.order)
+    .map((track) => {
+      const clips = [...track.clips]
+        .sort((left, right) => left.timelineStart - right.timelineStart
+          || (left.id < right.id ? -1 : left.id > right.id ? 1 : 0))
+        .map((clip) => inspectClip(track, clip, assets.get(clip.assetId)));
+      return {
+        id: track.id,
+        kind: track.kind,
+        order: track.order,
+        ...(track.name === undefined ? {} : { name: track.name }),
+        ...(track.visible === undefined ? {} : { visible: track.visible }),
+        ...(track.muted === undefined ? {} : { muted: track.muted }),
+        ...(track.solo === undefined ? {} : { solo: track.solo }),
+        ...(track.locked === undefined ? {} : { locked: track.locked }),
+        ...(track.volume === undefined ? {} : { volume: track.volume }),
+        ...(track.volumeKeyframes === undefined ? {} : { volumeKeyframes: structuredClone(track.volumeKeyframes) }),
+        ...(track.audioEffects === undefined ? {} : { audioEffects: structuredClone(track.audioEffects) }),
+        ...(track.allowOverlap === undefined ? {} : { allowOverlap: track.allowOverlap }),
+        clipCount: clips.length,
+        clips,
+      };
+    });
+
+  const clipCounts = Object.fromEntries(['video', 'audio', 'overlay'].map((kind) => [
+    kind,
+    tracks.filter((track) => track.kind === kind).reduce((total, track) => total + track.clipCount, 0),
+  ]));
+  return {
+    schemaVersion: 1,
+    project: {
+      id: timeline.project.id,
+      width: timeline.project.width,
+      height: timeline.project.height,
+      fps: timeline.project.fps,
+      durationSeconds: timeline.project.durationSeconds,
+      ...(timeline.project.sourceFit === undefined ? {} : { sourceFit: timeline.project.sourceFit }),
+      ...(timeline.project.backgroundColor === undefined ? {} : { backgroundColor: timeline.project.backgroundColor }),
+    },
+    ...(timeline.audioMix === undefined ? {} : { audioMix: structuredClone(timeline.audioMix) }),
+    ...(timeline.audioMastering === undefined ? {} : { audioMastering: structuredClone(timeline.audioMastering) }),
+    ...(timeline.lineage === undefined ? {} : { lineage: structuredClone(timeline.lineage) }),
+    markers: [...(timeline.markers ?? [])]
+      .sort((left, right) => left.timeSeconds - right.timeSeconds || (left.id < right.id ? -1 : left.id > right.id ? 1 : 0))
+      .map((marker) => structuredClone(marker)),
+    summary: {
+      assetCount: timeline.assets.length,
+      trackCount: tracks.length,
+      clipCount: Object.values(clipCounts).reduce((total, count) => total + count, 0),
+      clipCounts,
+      markerCount: timeline.markers?.length ?? 0,
+    },
+    assets: timeline.assets.map((asset) => ({
+      id: asset.id,
+      path: asset.path,
+      ...(asset.type === undefined ? {} : { type: asset.type }),
+      ...(asset.durationSeconds === undefined ? {} : { durationSeconds: asset.durationSeconds }),
+      ...(asset.width === undefined ? {} : { width: asset.width }),
+      ...(asset.height === undefined ? {} : { height: asset.height }),
+      ...(asset.frameRate === undefined ? {} : { frameRate: asset.frameRate }),
+      ...(asset.hasAudio === undefined ? {} : { hasAudio: asset.hasAudio }),
+      ...(asset.videoStreams === undefined ? {} : { videoStreams: structuredClone(asset.videoStreams) }),
+      ...(asset.audioStreams === undefined ? {} : { audioStreams: structuredClone(asset.audioStreams) }),
+      ...(asset.streamTiming === undefined ? {} : { streamTiming: structuredClone(asset.streamTiming) }),
+      ...(asset.proxies === undefined ? {} : { proxies: structuredClone(asset.proxies) }),
+    })),
+    tracks,
+  };
+}
+
+function inspectClip(track, clip, asset) {
+  const result = {
+    id: clip.id,
+    assetId: clip.assetId ?? null,
+    ...(clip.enabled === undefined ? {} : { enabled: clip.enabled }),
+    mediaType: track.kind === 'overlay' ? (clip.text === undefined ? 'composition' : 'text') : asset?.type ?? track.kind,
+    timeline: {
+      startSeconds: clip.timelineStart,
+      endSeconds: roundInspectionSeconds(clip.timelineStart + clip.durationSeconds),
+      durationSeconds: clip.durationSeconds,
+    },
+  };
+  if (track.kind !== 'overlay') {
+    result.source = {
+      inSeconds: clip.sourceIn,
+      outSeconds: clip.sourceOut,
+      ...(clip.playbackRate === undefined ? {} : { playbackRate: clip.playbackRate }),
+      ...(clip.speedRamp === undefined ? {} : { speedRamp: clip.speedRamp }),
+      ...(clip.reverse === undefined ? {} : { reverse: clip.reverse }),
+      ...(clip.videoStreamIndex === undefined ? {} : { videoStreamIndex: clip.videoStreamIndex }),
+    };
+  }
+  for (const field of [
+    'text', 'x', 'y', 'width', 'height', 'fontFamily', 'fontSize', 'fontWeight',
+    'lineHeight', 'verticalAlign', 'paddingPixels', 'color', 'backgroundColor',
+    'textAlign', 'textOutline', 'textShadow', 'wordTimings', 'wordHighlightColor',
+    'wordHighlightAnimation', 'volume', 'fadeInSeconds', 'fadeOutSeconds',
+    'bubble',
+    'audioEffects', 'volumeKeyframes',
+    'transitionIn', 'transitionOut', 'blendMode', 'keyframes', 'effects', 'mask',
+    'sourceFit',
+  ]) {
+    if (clip[field] !== undefined) result[field] = structuredClone(clip[field]);
+  }
+  return result;
+}
+
+function roundInspectionSeconds(seconds) {
+  return Number(seconds.toFixed(6));
+}

package/src/timeline/keyframes.mjs

@@ -0,0 +1,158 @@
+import { gsap } from 'gsap';
+
+const PROPERTIES = new Set(['x', 'y', 'width', 'height', 'opacity', 'rotationDegrees', 'objectPositionX', 'objectPositionY', 'zoom', 'maskProgress', 'brightness', 'contrast', 'saturation', 'blurPixels', 'hueDegrees']);
+const EASES = new Set([
+  'none', 'power1.in', 'power1.out', 'power1.inOut', 'power2.in', 'power2.out', 'power2.inOut',
+  'power3.in', 'power3.out', 'power3.inOut', 'power4.in', 'power4.out', 'power4.inOut',
+  'sine.in', 'sine.out', 'sine.inOut', 'back.in', 'back.out', 'back.inOut',
+]);
+
+export function validateVisualKeyframes(track, clip) {
+  if (clip.keyframes === undefined) return;
+  if (track.kind !== 'video' && track.kind !== 'overlay') {
+    throw new TypeError(`Clip ${clip.id} keyframes are supported on video and overlay clips.`);
+  }
+  if (!Array.isArray(clip.keyframes) || clip.keyframes.length === 0) throw new TypeError(`Clip ${clip.id} keyframes must be a non-empty array.`);
+  if (clip.keyframes[0]?.time !== 0) throw new TypeError(`Clip ${clip.id} keyframes must start at time 0.`);
+  if (clip.keyframes.some((frame) => frame?.properties?.opacity !== undefined) && ((clip.fadeInSeconds ?? 0) > 0 || (clip.fadeOutSeconds ?? 0) > 0)) {
+    throw new TypeError(`Clip ${clip.id} cannot combine opacity keyframes with fadeInSeconds or fadeOutSeconds.`);
+  }
+  const hasMaskProgress = clip.keyframes.some((frame) => frame?.properties?.maskProgress !== undefined);
+  if (hasMaskProgress && clip.mask === undefined) throw new TypeError(`Clip ${clip.id} maskProgress keyframes require a static mask.`);
+  if (hasMaskProgress && clip.keyframes[0]?.properties?.maskProgress === undefined) throw new TypeError(`Clip ${clip.id} maskProgress keyframes must set a value at time 0.`);
+
+  const defaults = track.kind === 'video' || typeof clip.text !== 'string'
+    ? { x: clip.x ?? 0, y: clip.y ?? 0, width: clip.width ?? 1, height: clip.height ?? 1 }
+    : { x: clip.x ?? 0.08, y: clip.y ?? 0.76, width: clip.width ?? 0.84, height: clip.height ?? 0.16 };
+  let previousTime = -1;
+  const current = { ...defaults };
+  for (const [index, frame] of clip.keyframes.entries()) {
+    if (!frame || typeof frame !== 'object' || Array.isArray(frame) || !Number.isFinite(frame.time) || frame.time < 0 || frame.time > clip.durationSeconds) {
+      throw new TypeError(`Clip ${clip.id} keyframe ${index} time must be within the clip duration.`);
+    }
+    if (frame.time <= previousTime) throw new TypeError(`Clip ${clip.id} keyframe times must be strictly increasing.`);
+    if (!frame.properties || typeof frame.properties !== 'object' || Array.isArray(frame.properties) || Object.keys(frame.properties).length === 0) {
+      throw new TypeError(`Clip ${clip.id} keyframe ${index} needs at least one property.`);
+    }
+    for (const [property, value] of Object.entries(frame.properties)) {
+      if (!PROPERTIES.has(property) || !Number.isFinite(value)) throw new TypeError(`Clip ${clip.id} keyframe ${index} has an unsupported or non-finite property: ${property}.`);
+      if (property === 'opacity' && (value < 0 || value > 1)) throw new TypeError(`Clip ${clip.id} keyframe opacity must be between 0 and 1.`);
+      if (property === 'rotationDegrees' && Math.abs(value) > 3600) throw new TypeError(`Clip ${clip.id} keyframe rotationDegrees must be between -3600 and 3600.`);
+      if (['objectPositionX', 'objectPositionY'].includes(property) && (track.kind !== 'video' || value < 0 || value > 1)) {
+        throw new TypeError(`Clip ${clip.id} keyframe ${property} must be between 0 and 1 on a video track.`);
+      }
+      if (property === 'zoom' && (track.kind !== 'video' || value < 1 || value > 4)) {
+        throw new TypeError(`Clip ${clip.id} keyframe zoom must be between 1 and 4 on a video track.`);
+      }
+      if (property === 'maskProgress' && (clip.mask === undefined || value < 0 || value > 1)) {
+        throw new TypeError(`Clip ${clip.id} keyframe maskProgress must be between 0 and 1 and requires a static mask.`);
+      }
+      if (['brightness', 'contrast', 'saturation'].includes(property) && (value < 0 || value > 5)) throw new TypeError(`Clip ${clip.id} keyframe ${property} must be between 0 and 5.`);
+      if (property === 'blurPixels' && (value < 0 || value > 100)) throw new TypeError(`Clip ${clip.id} keyframe blurPixels must be between 0 and 100.`);
+      if (property === 'hueDegrees' && Math.abs(value) > 360) throw new TypeError(`Clip ${clip.id} keyframe hueDegrees must be between -360 and 360.`);
+      if (['width', 'height'].includes(property) && value <= 0) throw new TypeError(`Clip ${clip.id} keyframe ${property} must be positive.`);
+      current[property] = value;
+    }
+    if (![current.x, current.y, current.width, current.height].every(Number.isFinite) || current.x < 0 || current.y < 0 || current.width <= 0 || current.height <= 0 || current.x + current.width > 1 || current.y + current.height > 1) {
+      throw new TypeError(`Clip ${clip.id} keyframe placement must fit within normalized canvas bounds.`);
+    }
+    if (frame.ease !== undefined) validateEase(frame.ease, `Clip ${clip.id} keyframe ease`);
+    if (frame.eases !== undefined) {
+      if (!frame.eases || typeof frame.eases !== 'object' || Array.isArray(frame.eases)) throw new TypeError(`Clip ${clip.id} keyframe eases must be an object.`);
+      for (const [property, ease] of Object.entries(frame.eases)) {
+        if (!Object.hasOwn(frame.properties, property)) throw new TypeError(`Clip ${clip.id} keyframe ease ${property} needs a matching property.`);
+        validateEase(ease, `Clip ${clip.id} keyframe ease ${property}`);
+      }
+    }
+    previousTime = frame.time;
+  }
+}
+
+export function sliceVisualKeyframes(keyframes, start, end) {
+  if (!keyframes) return undefined;
+  const properties = new Set(keyframes.flatMap((frame) => Object.keys(frame.properties)));
+  const frames = new Map();
+  const add = (time, property, value, ease) => {
+    const frame = frames.get(time) ?? { time, properties: {}, eases: {} };
+    frame.properties[property] = value;
+    if (ease !== undefined) frame.eases[property] = ease;
+    frames.set(time, frame);
+  };
+
+  for (const property of properties) {
+    const points = keyframes.filter((frame) => Object.hasOwn(frame.properties, property));
+    const initial = sampleProperty(points, property, start);
+    if (initial !== undefined) add(0, property, initial);
+
+    for (let index = 0; index < points.length; index++) {
+      const point = points[index];
+      if (point.time <= start || point.time > end) continue;
+      const prior = points[index - 1];
+      const ease = prior && point.time > start
+        ? sliceEase(point.eases?.[property] ?? point.ease ?? 'none', Math.max(0, (start - prior.time) / (point.time - prior.time)), 1)
+        : point.eases?.[property] ?? point.ease;
+      add(point.time - start, property, point.properties[property], ease);
+    }
+
+    const ending = sampleProperty(points, property, end);
+    if (ending !== undefined && !points.some((point) => point.time === end)) {
+      const priorIndex = points.findLastIndex((point) => point.time < end);
+      const prior = points[priorIndex];
+      const next = points[priorIndex + 1];
+      if (prior && next) {
+        const ease = next.eases?.[property] ?? next.ease ?? 'none';
+        const from = Math.max(start, prior.time);
+        const to = end;
+        add(end - start, property, ending, sliceEase(ease, (from - prior.time) / (next.time - prior.time), (to - prior.time) / (next.time - prior.time)));
+      }
+    }
+  }
+
+  return [...frames.values()]
+    .sort((left, right) => left.time - right.time)
+    .map((frame) => {
+      if (Object.keys(frame.eases).length === 0) delete frame.eases;
+      return frame;
+    });
+}
+
+function sampleProperty(points, property, time) {
+  const priorIndex = points.findLastIndex((point) => point.time <= time);
+  if (priorIndex < 0) return undefined;
+  const prior = points[priorIndex];
+  const next = points[priorIndex + 1];
+  if (!next) return prior.properties[property];
+  const progress = (time - prior.time) / (next.time - prior.time);
+  const ease = next.eases?.[property] ?? next.ease ?? 'none';
+  return prior.properties[property] + (next.properties[property] - prior.properties[property]) * easeProgress(ease, progress);
+}
+
+function sliceEase(ease, from, to) {
+  if (typeof ease === 'string') {
+    if (from === 0 && to === 1) return ease;
+    return { type: 'range', name: ease, from, to };
+  }
+  return {
+    type: 'range', name: ease.name,
+    from: ease.from + (ease.to - ease.from) * from,
+    to: ease.from + (ease.to - ease.from) * to,
+  };
+}
+
+function easeProgress(ease, progress) {
+  if (typeof ease === 'string') return gsap.parseEase(ease)(progress);
+  const fn = gsap.parseEase(ease.name);
+  const from = fn(ease.from), to = fn(ease.to);
+  return (fn(ease.from + (ease.to - ease.from) * progress) - from) / (to - from);
+}
+
+function validateEase(ease, label) {
+  if (typeof ease === 'string' && EASES.has(ease)) return;
+  if (!ease || typeof ease !== 'object' || Array.isArray(ease) || ease.type !== 'range' || !EASES.has(ease.name)
+      || Object.keys(ease).some((key) => !['type', 'name', 'from', 'to'].includes(key))
+      || !Number.isFinite(ease.from) || !Number.isFinite(ease.to) || ease.from < 0 || ease.to > 1 || ease.from >= ease.to) {
+    throw new TypeError(`${label} is unsupported.`);
+  }
+  const fn = gsap.parseEase(ease.name);
+  if (Math.abs(fn(ease.to) - fn(ease.from)) < 1e-9) throw new TypeError(`${label} has no progress across its range.`);
+}