@aicut/core 0.5.0 → 0.6.0

package/dist/index.js

@@ -1,5 +1,7 @@
-import { mergeLocale, applyTheme, formatLabel } from './chunk-CCDON7CU.js';
-export { formatLabel, localeEn, localeZh, mergeLocale } from './chunk-CCDON7CU.js';
+import { getEffectiveTransform, interpolateProp, upsertKeyframe, hasKeyframesForProp } from './chunk-WTCK3XQ6.js';
+export { IDENTITY_TRANSFORM, getEffectiveTransform, getTransformAtTimelineTime, isIdentityTransform } from './chunk-WTCK3XQ6.js';
+import { mergeLocale, applyTheme, formatLabel } from './chunk-H6AY6NW4.js';
+export { formatLabel, localeEn, localeZh, mergeLocale } from './chunk-H6AY6NW4.js';
 
 // src/events.ts
 var EventBus = class {
@@ -82,6 +84,19 @@ function createId(prefix = "id") {
 }
 
 // src/model.ts
+var KEYFRAME_PROPS = ["panX", "panY", "scale"];
+var DEFAULT_FPS = 30;
+var BIG_FRAME_STEP = 10;
+function projectFps(project) {
+  const f = project.fps;
+  return f != null && f > 0 ? f : DEFAULT_FPS;
+}
+function frameStepMs(project) {
+  return Math.max(1, Math.round(1e3 / projectFps(project)));
+}
+function bigFrameStepMs(project) {
+  return Math.max(1, Math.round(BIG_FRAME_STEP * 1e3 / projectFps(project)));
+}
 function createEmptyProject() {
   return {
     version: 1,
@@ -118,11 +133,58 @@ function findTrackOfClip(project, clipId) {
 function normalizeProject(project) {
   const sources = project.sources.map((s) => ({ ...s }));
   const tracks = project.tracks.map((t) => {
-    const clips = t.clips.filter((c) => c.out > c.in).map((c) => ({ ...c, id: c.id || createId("clip") })).sort((a, b) => a.start - b.start);
+    const clips = t.clips.filter((c) => c.out > c.in).map((c) => {
+      const out = { ...c, id: c.id || createId("clip") };
+      if (c.keyframes && c.keyframes.length > 0) {
+        const duration = c.out - c.in;
+        out.keyframes = migrateKeyframes(c.keyframes).filter((kf) => kf.time >= 0 && kf.time <= duration).map((kf) => ({ ...kf, id: kf.id || createId("kf") })).sort((a, b) => {
+          if (a.prop !== b.prop) return a.prop.localeCompare(b.prop);
+          return a.time - b.time;
+        });
+      }
+      return out;
+    }).sort((a, b) => a.start - b.start);
     return { ...t, id: t.id || createId("track"), clips };
   });
   return { version: 1, sources, tracks };
 }
+function migrateKeyframes(raw) {
+  const out = [];
+  for (const kf of raw) {
+    if ("prop" in kf && "value" in kf) {
+      out.push(kf);
+      continue;
+    }
+    const tuple = kf;
+    const id = tuple.id;
+    const t = tuple.time;
+    if (typeof tuple.x === "number") {
+      out.push({
+        id: id ? `${id}-px` : createId("kf"),
+        prop: "panX",
+        time: t,
+        value: tuple.x
+      });
+    }
+    if (typeof tuple.y === "number") {
+      out.push({
+        id: id ? `${id}-py` : createId("kf"),
+        prop: "panY",
+        time: t,
+        value: tuple.y
+      });
+    }
+    if (typeof tuple.scale === "number") {
+      out.push({
+        id: id ? `${id}-s` : createId("kf"),
+        prop: "scale",
+        time: t,
+        value: tuple.scale
+      });
+    }
+  }
+  return out;
+}
 function splitClipAt(clip, localOffset) {
   const sourceLen = clip.out - clip.in;
   if (localOffset <= 0 || localOffset >= sourceLen) return null;
@@ -133,6 +195,47 @@ function splitClipAt(clip, localOffset) {
     in: clip.in + localOffset,
     start: clip.start + localOffset
   };
+  if (clip.keyframes && clip.keyframes.length > 0) {
+    const leftKf = [];
+    const rightKf = [];
+    for (const prop of KEYFRAME_PROPS) {
+      const propKfs = clip.keyframes.filter((k) => k.prop === prop);
+      if (propKfs.length === 0) continue;
+      const boundaryValue = interpolateProp(clip, prop, localOffset);
+      let leftSeamPresent = false;
+      let rightSeamPresent = false;
+      for (const kf of propKfs) {
+        if (kf.time < localOffset) {
+          leftKf.push(kf);
+        } else if (kf.time > localOffset) {
+          rightKf.push({ ...kf, id: createId("kf"), time: kf.time - localOffset });
+        } else {
+          leftKf.push(kf);
+          leftSeamPresent = true;
+          rightKf.push({ ...kf, id: createId("kf"), time: 0 });
+          rightSeamPresent = true;
+        }
+      }
+      if (!leftSeamPresent) {
+        leftKf.push({
+          id: createId("kf"),
+          prop,
+          time: localOffset,
+          value: boundaryValue
+        });
+      }
+      if (!rightSeamPresent) {
+        rightKf.push({
+          id: createId("kf"),
+          prop,
+          time: 0,
+          value: boundaryValue
+        });
+      }
+    }
+    left.keyframes = leftKf.length > 0 ? leftKf : void 0;
+    right.keyframes = rightKf.length > 0 ? rightKf : void 0;
+  }
   return [left, right];
 }
 function projectDuration(project) {
@@ -152,6 +255,11 @@ var HANDLE_PX = 8;
 var CLIP_INSET = 6;
 var SCALE_MIN = 10;
 var SCALE_MAX = 400;
+var TIMELINE_PAD_LEFT = 12;
+var TIMELINE_PAD_RIGHT = 12;
+function contentLeftX(showHeader) {
+  return (showHeader ? HEADER_WIDTH : 0) + TIMELINE_PAD_LEFT;
+}
 function setTimelineMetrics(opts) {
   if (opts.trackHeight != null && opts.trackHeight > 0) {
     TRACK_HEIGHT = Math.round(opts.trackHeight);
@@ -187,8 +295,10 @@ function trackIndexAt(y, trackCount, scrollTop = 0) {
   return idx;
 }
 function xToMs(x, pxPerSec, scrollLeft, showHeader) {
-  const base = showHeader ? HEADER_WIDTH : 0;
-  return Math.max(0, (x - base + scrollLeft) / pxPerSec * 1e3);
+  return Math.max(
+    0,
+    (x - contentLeftX(showHeader) + scrollLeft) / pxPerSec * 1e3
+  );
 }
 function niceTickSeconds(targetSec) {
   if (targetSec <= 0) return 1;
@@ -216,6 +326,9 @@ function snapTargets(project, playheadMs, ignoreClipId) {
     for (const c of t.clips) {
       if (c.id === ignoreClipId) continue;
       arr.push(c.start, c.start + (c.out - c.in));
+      if (c.keyframes) {
+        for (const kf of c.keyframes) arr.push(c.start + kf.time);
+      }
     }
   }
   return arr;
@@ -266,13 +379,16 @@ function uncoveredIntervals(project) {
 var HtmlVideoEngine = class {
   host;
   mount;
-  videos = /* @__PURE__ */ new Map();
+  sources = /* @__PURE__ */ new Map();
   project;
   currentClipId = null;
   playing = false;
   timeMs = 0;
   rafHandle = null;
   lastFrameTs = 0;
+  /** Permanent rAF that positions the active wrapper at the output
+   *  rect + pushes keyframe transform onto the inner video via CSS. */
+  transformRaf = null;
   /** Public event hooks — set by Editor. */
   onTimeUpdate;
   onEnded;
@@ -284,8 +400,15 @@ var HtmlVideoEngine = class {
     this.project = opts.project;
     this.mount = document.createElement("div");
     this.mount.className = "aicut-preview";
+    Object.assign(this.mount.style, {
+      position: "absolute",
+      inset: "0",
+      width: "100%",
+      height: "100%"
+    });
     this.host.appendChild(this.mount);
     this.syncSources();
+    this.startTransformLoop();
   }
   setProject(next) {
     this.project = next;
@@ -308,9 +431,9 @@ var HtmlVideoEngine = class {
     if (this.timeMs < clip.start) this.timeMs = clip.start;
     this.activate(clip);
     this.seekVideoToClipOffset(clip, this.timeMs - clip.start);
-    const v = this.videos.get(clip.sourceId);
-    if (!v) return;
-    void v.play().catch((err) => this.onError?.(err));
+    const s = this.sources.get(clip.sourceId);
+    if (!s) return;
+    void s.video.play().catch((err) => this.onError?.(err));
     this.playing = true;
     this.startTickLoop();
   }
@@ -321,8 +444,7 @@ var HtmlVideoEngine = class {
     if (this.currentClipId) {
       const clip = this.clipById(this.currentClipId);
       if (clip) {
-        const v = this.videos.get(clip.sourceId);
-        v?.pause();
+        this.sources.get(clip.sourceId)?.video.pause();
       }
     }
   }
@@ -349,41 +471,137 @@ var HtmlVideoEngine = class {
     }
     this.onTimeUpdate?.(clamped);
   }
+  /**
+   * The OUTPUT frame — the fixed stage the rendered video is clipped
+   * to. Independent of the keyframe transform. Used by the overlay to
+   * draw the dashed border at a stable position.
+   */
+  getOutputFrameRect() {
+    return this.baseFrameRect();
+  }
+  /**
+   * The CONTENT frame — where the transformed video pixels actually
+   * land. Equal to the output frame when transform is identity; may
+   * extend outside (zoom in) or fit inside (zoom out) when not.
+   */
+  getFrameRect() {
+    const base = this.baseFrameRect();
+    if (!base) return null;
+    const clip = this.clipById(this.currentClipId);
+    if (!clip) return base;
+    const t = getEffectiveTransform(clip, this.timeMs - clip.start);
+    const cx = base.x + base.w / 2 + t.panX;
+    const cy = base.y + base.h / 2 + t.panY;
+    const w = base.w * t.scale;
+    const h = base.h * t.scale;
+    return { x: cx - w / 2, y: cy - h / 2, w, h };
+  }
+  /** Untransformed contain-letterbox rect — the OUTPUT frame. */
+  baseFrameRect() {
+    if (!this.currentClipId) return null;
+    const clip = this.clipById(this.currentClipId);
+    if (!clip) return null;
+    const s = this.sources.get(clip.sourceId);
+    if (!s) return null;
+    const v = s.video;
+    if (v.videoWidth === 0 || v.videoHeight === 0) return null;
+    const hostRect = this.host.getBoundingClientRect();
+    const cw = hostRect.width;
+    const ch = hostRect.height;
+    if (cw === 0 || ch === 0) return null;
+    const scale = Math.min(cw / v.videoWidth, ch / v.videoHeight);
+    const w = v.videoWidth * scale;
+    const h = v.videoHeight * scale;
+    return { x: (cw - w) / 2, y: (ch - h) / 2, w, h };
+  }
+  /**
+   * Permanent rAF that (a) sizes + positions the active wrapper to
+   * the output frame, and (b) writes the keyframe transform onto the
+   * inner video. Negligible cost — three style writes per frame max.
+   */
+  startTransformLoop() {
+    const tick = () => {
+      this.applyTransforms();
+      this.transformRaf = requestAnimationFrame(tick);
+    };
+    this.transformRaf = requestAnimationFrame(tick);
+  }
+  applyTransforms() {
+    const clip = this.currentClipId ? this.clipById(this.currentClipId) : null;
+    const outRect = this.baseFrameRect();
+    if (clip && outRect) {
+      const s = this.sources.get(clip.sourceId);
+      if (s) {
+        Object.assign(s.wrapper.style, {
+          left: `${outRect.x}px`,
+          top: `${outRect.y}px`,
+          width: `${outRect.w}px`,
+          height: `${outRect.h}px`
+        });
+        const t = getEffectiveTransform(clip, this.timeMs - clip.start);
+        s.video.style.transform = `translate(${t.panX.toFixed(2)}px, ${t.panY.toFixed(2)}px) scale(${t.scale.toFixed(4)})`;
+      }
+    }
+    for (const [id, s] of this.sources) {
+      if (clip && id === clip.sourceId) continue;
+      if (s.video.style.transform) s.video.style.transform = "";
+    }
+  }
   destroy() {
     this.stopTickLoop();
-    for (const v of this.videos.values()) {
-      v.pause();
-      v.removeAttribute("src");
-      v.load();
-      v.remove();
+    if (this.transformRaf != null) {
+      cancelAnimationFrame(this.transformRaf);
+      this.transformRaf = null;
     }
-    this.videos.clear();
+    for (const s of this.sources.values()) {
+      s.video.pause();
+      s.video.removeAttribute("src");
+      s.video.load();
+      s.wrapper.remove();
+    }
+    this.sources.clear();
     this.mount.remove();
   }
   // --- internals -------------------------------------------------------
   syncSources() {
     const wanted = new Set(this.project.sources.map((s) => s.id));
-    for (const [id, v] of this.videos) {
+    for (const [id, s] of this.sources) {
       if (!wanted.has(id)) {
-        v.pause();
-        v.remove();
-        this.videos.delete(id);
+        s.video.pause();
+        s.wrapper.remove();
+        this.sources.delete(id);
       }
     }
     for (const src of this.project.sources) {
       if (src.kind !== "video") continue;
-      if (this.videos.has(src.id)) continue;
+      if (this.sources.has(src.id)) continue;
+      const wrapper = document.createElement("div");
+      wrapper.className = "aicut-preview-clip";
+      Object.assign(wrapper.style, {
+        position: "absolute",
+        overflow: "hidden",
+        visibility: "hidden",
+        // Initial bounds — applyTransforms overrides each frame.
+        left: "0",
+        top: "0",
+        width: "0",
+        height: "0"
+      });
       const v = document.createElement("video");
       v.preload = "auto";
       v.playsInline = true;
       v.muted = false;
       v.src = src.url;
-      v.style.position = "absolute";
-      v.style.inset = "0";
-      v.style.width = "100%";
-      v.style.height = "100%";
-      v.style.objectFit = "contain";
-      v.style.visibility = "hidden";
+      Object.assign(v.style, {
+        position: "absolute",
+        inset: "0",
+        width: "100%",
+        height: "100%",
+        objectFit: "fill",
+        // Transform origin at center so scale() scales around the
+        // video's centroid, not its top-left corner.
+        transformOrigin: "50% 50%"
+      });
       const sourceId = src.id;
       v.addEventListener(
         "error",
@@ -396,8 +614,9 @@ var HtmlVideoEngine = class {
           this.onSourceMetadata?.(sourceId, durMs);
         }
       });
-      this.mount.appendChild(v);
-      this.videos.set(src.id, v);
+      wrapper.appendChild(v);
+      this.mount.appendChild(wrapper);
+      this.sources.set(src.id, { wrapper, video: v });
     }
   }
   activate(clip) {
@@ -405,25 +624,25 @@ var HtmlVideoEngine = class {
     if (this.currentClipId) {
       const prev = this.clipById(this.currentClipId);
       if (prev) {
-        const v = this.videos.get(prev.sourceId);
-        if (v) {
-          v.pause();
-          v.style.visibility = "hidden";
+        const s = this.sources.get(prev.sourceId);
+        if (s) {
+          s.video.pause();
+          s.wrapper.style.visibility = "hidden";
         }
       }
     }
     this.currentClipId = clip ? clip.id : null;
     if (clip) {
-      const v = this.videos.get(clip.sourceId);
-      if (v) v.style.visibility = "visible";
+      const s = this.sources.get(clip.sourceId);
+      if (s) s.wrapper.style.visibility = "visible";
     }
   }
   seekVideoToClipOffset(clip, offsetMs) {
-    const v = this.videos.get(clip.sourceId);
-    if (!v) return;
+    const s = this.sources.get(clip.sourceId);
+    if (!s) return;
     const target = (clip.in + Math.max(0, offsetMs)) / 1e3;
-    if (Math.abs(v.currentTime - target) > 0.05) {
-      v.currentTime = target;
+    if (Math.abs(s.video.currentTime - target) > 0.05) {
+      s.video.currentTime = target;
     }
   }
   clipById(id) {
@@ -435,10 +654,7 @@ var HtmlVideoEngine = class {
   /**
    * Find the clip whose timeline range contains `timeMs`, searching
    * across ALL video tracks. If multiple tracks have a clip at this
-   * moment, the lowest-index track wins (matches the "Track 1 is
-   * background" convention used in the auto-split UX — overlapping
-   * placements would have created a new track on top, but here we
-   * fall back to the underlying clip).
+   * moment, the lowest-index track wins.
    */
   clipAtTime(timeMs) {
     for (const t of this.project.tracks) {
@@ -507,8 +723,8 @@ var HtmlVideoEngine = class {
         this.timeMs = next.start;
         this.activate(next);
         this.seekVideoToClipOffset(next, 0);
-        const v = this.videos.get(next.sourceId);
-        if (v) void v.play().catch((err) => this.onError?.(err));
+        const s = this.sources.get(next.sourceId);
+        if (s) void s.video.play().catch((err) => this.onError?.(err));
       } else {
         this.pause();
         this.onEnded?.();
@@ -517,8 +733,8 @@ var HtmlVideoEngine = class {
     } else if (clip.id !== this.currentClipId) {
       this.activate(clip);
       this.seekVideoToClipOffset(clip, this.timeMs - clip.start);
-      const v = this.videos.get(clip.sourceId);
-      if (v) void v.play().catch((err) => this.onError?.(err));
+      const s = this.sources.get(clip.sourceId);
+      if (s) void s.video.play().catch((err) => this.onError?.(err));
     }
     this.onTimeUpdate?.(this.timeMs);
   }
@@ -541,6 +757,10 @@ var CanvasCompositorEngine = class {
   rafHandle = null;
   lastFrameTs = 0;
   paintedFrames = 0;
+  /** Output frame rect (no transform) — fixed bounds. */
+  lastOutputRect = null;
+  /** Post-transform content rect. */
+  lastFrameRect = null;
   onTimeUpdate;
   onEnded;
   onError;
@@ -825,19 +1045,55 @@ var CanvasCompositorEngine = class {
     this.ctx.clearRect(0, 0, cw, ch);
     const clip = this.currentClipId ? this.clipById(this.currentClipId) : null;
     const v = clip ? this.videos.get(clip.sourceId) : null;
-    if (v && v.videoWidth > 0 && v.videoHeight > 0) {
+    if (v && v.videoWidth > 0 && v.videoHeight > 0 && clip) {
       const vw = v.videoWidth;
       const vh = v.videoHeight;
-      const scale = Math.min(cw / vw, ch / vh);
-      const dw = vw * scale;
-      const dh = vh * scale;
-      const dx = (cw - dw) / 2;
-      const dy = (ch - dh) / 2;
-      this.ctx.drawImage(v, dx, dy, dw, dh);
+      const baseScale = Math.min(cw / vw, ch / vh);
+      const dw = vw * baseScale;
+      const dh = vh * baseScale;
+      const cx = cw / 2;
+      const cy = ch / 2;
+      const dpr = window.devicePixelRatio || 1;
+      const t = getEffectiveTransform(clip, this.timeMs - clip.start);
+      const outX = (cw - dw) / 2;
+      const outY = (ch - dh) / 2;
+      this.ctx.save();
+      this.ctx.beginPath();
+      this.ctx.rect(outX, outY, dw, dh);
+      this.ctx.clip();
+      this.ctx.translate(cx + t.panX * dpr, cy + t.panY * dpr);
+      this.ctx.scale(t.scale, t.scale);
+      this.ctx.drawImage(v, -dw / 2, -dh / 2, dw, dh);
+      this.ctx.restore();
       this.paintedFrames += 1;
+      this.lastOutputRect = {
+        x: outX / dpr,
+        y: outY / dpr,
+        w: dw / dpr,
+        h: dh / dpr
+      };
+      const cssCx = cw / (2 * dpr) + t.panX;
+      const cssCy = ch / (2 * dpr) + t.panY;
+      const cssW = dw * t.scale / dpr;
+      const cssH = dh * t.scale / dpr;
+      this.lastFrameRect = {
+        x: cssCx - cssW / 2,
+        y: cssCy - cssH / 2,
+        w: cssW,
+        h: cssH
+      };
+    } else {
+      this.lastFrameRect = null;
+      this.lastOutputRect = null;
     }
     this.updateBadge();
   }
+  getOutputFrameRect() {
+    return this.lastOutputRect;
+  }
+  getFrameRect() {
+    return this.lastFrameRect;
+  }
   updateBadge() {
     if (!this.badge) return;
     const sec = (this.timeMs / 1e3).toFixed(2);
@@ -1023,7 +1279,7 @@ function drawAll(ctx, state, style, thumbs) {
   const { viewportWidth: W, viewportHeight: H } = state;
   ctx.fillStyle = style.bg;
   ctx.fillRect(0, 0, W, H);
-  const baseX = state.showHeader ? HEADER_WIDTH : 0;
+  const baseX = contentLeftX(state.showHeader);
   const trackAreaW = W - baseX - SCROLLBAR_THICKNESS;
   const trackAreaH = H - RULER_HEIGHT - SCROLLBAR_THICKNESS;
   ctx.save();
@@ -1063,15 +1319,21 @@ function drawAll(ctx, state, style, thumbs) {
   ctx.rect(baseX, 0, trackAreaW, H - SCROLLBAR_THICKNESS);
   ctx.clip();
   drawSnapGuide(ctx, state, style);
-  drawPlayhead(ctx, state, style);
   ctx.restore();
   drawScrollbarV(ctx, state, style);
   drawScrollbarH(ctx, state, style);
+  const playheadLeft = state.showHeader ? HEADER_WIDTH : 0;
+  ctx.save();
+  ctx.beginPath();
+  ctx.rect(playheadLeft, 0, W - playheadLeft, H);
+  ctx.clip();
+  drawPlayhead(ctx, state, style);
+  ctx.restore();
 }
 function drawCoverageGaps(ctx, state, style) {
   const gaps = uncoveredIntervals(state.project);
   if (gaps.length === 0) return;
-  const baseX = state.showHeader ? HEADER_WIDTH : 0;
+  const baseX = contentLeftX(state.showHeader);
   const trackStackH = state.viewportHeight - RULER_HEIGHT - SCROLLBAR_THICKNESS;
   for (const [s, e] of gaps) {
     const x1 = Math.max(
@@ -1110,7 +1372,7 @@ function drawDragGhost(ctx, state, style, thumbs) {
     }
   }
   if (!real) return;
-  const baseX = state.showHeader ? HEADER_WIDTH : 0;
+  const baseX = contentLeftX(state.showHeader);
   const widthPx = Math.max(2, (real.out - real.in) / 1e3 * state.pxPerSec);
   const startX = baseX + ghost.ghostStart / 1e3 * state.pxPerSec - state.scrollLeft;
   const overlap = ghost.wouldOverlap;
@@ -1180,7 +1442,7 @@ function drawPhantomRow(ctx, trackIndex, baseX, state, style) {
 }
 function drawRuler(ctx, state, style) {
   const { pxPerSec, scrollLeft, viewportWidth: W } = state;
-  const baseX = state.showHeader ? HEADER_WIDTH : 0;
+  const baseX = contentLeftX(state.showHeader);
   const rulerW = W - baseX;
   ctx.fillStyle = style.bg;
   ctx.fillRect(baseX, 0, rulerW, RULER_HEIGHT);
@@ -1226,7 +1488,7 @@ function drawTracks(ctx, state, style, thumbs) {
 }
 function drawTrackRow(ctx, trackIndex, track, sources, state, style, thumbs) {
   const { viewportWidth: W } = state;
-  const baseX = state.showHeader ? HEADER_WIDTH : 0;
+  const baseX = contentLeftX(state.showHeader);
   const y = trackY(trackIndex);
   ctx.fillStyle = style.trackBg;
   ctx.fillRect(baseX, y, W - baseX, TRACK_HEIGHT);
@@ -1264,7 +1526,7 @@ function drawTrackRow(ctx, trackIndex, track, sources, state, style, thumbs) {
 }
 function drawClipAt(ctx, clip, trackIndex, startMs, sources, state, style, thumbs, dim, warn) {
   const { pxPerSec, scrollLeft } = state;
-  const baseX = state.showHeader ? HEADER_WIDTH : 0;
+  const baseX = contentLeftX(state.showHeader);
   const startX = baseX + startMs / 1e3 * pxPerSec - scrollLeft;
   const widthPx = Math.max(2, (clip.out - clip.in) / 1e3 * pxPerSec);
   const y = trackY(trackIndex) + CLIP_INSET;
@@ -1313,6 +1575,34 @@ function drawClipAt(ctx, clip, trackIndex, startMs, sources, state, style, thumb
     ctx.fillRect(startX + 2, y + 12, 2, h - 24);
     ctx.fillRect(startX + widthPx - 4, y + 12, 2, h - 24);
   }
+  if (!dim && state.keyframesEnabled && clip.keyframes && clip.keyframes.length > 0) {
+    const diamondY = y + h / 2;
+    const halfSize = 5;
+    const moments = groupKeyframesByTime(clip.keyframes, 16);
+    const ghost = state.keyframeDragGhost;
+    for (const moment of moments) {
+      const draggedHere = ghost ? moment.kfs.find(
+        (k) => ghost.clipId === clip.id && ghost.keyframeId === k.id
+      ) : void 0;
+      const effectiveTime = draggedHere ? ghost.ghostTimeMs : moment.time;
+      const kfX = startX + effectiveTime / 1e3 * pxPerSec;
+      if (kfX < baseX - halfSize || kfX > state.viewportWidth + halfSize) continue;
+      const isSelected = state.selectedKeyframe?.clipId === clip.id && moment.kfs.some((k) => k.id === state.selectedKeyframe?.keyframeId);
+      const isHovered = state.hoveredKeyframe?.clipId === clip.id && moment.kfs.some((k) => k.id === state.hoveredKeyframe?.keyframeId);
+      const drawSize = isHovered ? halfSize + 1.5 : halfSize;
+      ctx.beginPath();
+      ctx.moveTo(kfX, diamondY - drawSize);
+      ctx.lineTo(kfX + drawSize, diamondY);
+      ctx.lineTo(kfX, diamondY + drawSize);
+      ctx.lineTo(kfX - drawSize, diamondY);
+      ctx.closePath();
+      ctx.fillStyle = isSelected ? style.selectedRing : isHovered ? "#ffffff" : withAlpha(style.text, 0.85);
+      ctx.fill();
+      ctx.strokeStyle = isHovered ? style.selectedRing : "rgba(0, 0, 0, 0.65)";
+      ctx.lineWidth = isHovered ? 1.5 : 1;
+      ctx.stroke();
+    }
+  }
   ctx.restore();
 }
 function drawHeaders(ctx, state, style) {
@@ -1363,7 +1653,7 @@ function drawHeaders(ctx, state, style) {
   }
 }
 function drawPlayhead(ctx, state, style) {
-  const baseX = state.showHeader ? HEADER_WIDTH : 0;
+  const baseX = contentLeftX(state.showHeader);
   const x = baseX + state.timeMs / 1e3 * state.pxPerSec - state.scrollLeft;
   if (x < baseX - 2 || x > state.viewportWidth + 2) return;
   ctx.strokeStyle = style.playhead;
@@ -1377,7 +1667,9 @@ function drawPlayhead(ctx, state, style) {
   const padX = 6;
   const w = ctx.measureText(label).width + padX * 2;
   const h = 14;
-  const bx = x - w / 2;
+  const contentRight = state.viewportWidth - SCROLLBAR_THICKNESS;
+  const rawBx = x - w / 2;
+  const bx = Math.max(baseX, Math.min(contentRight - w, rawBx));
   const by = 2;
   ctx.fillStyle = style.playhead;
   roundRect(ctx, bx, by, w, h, 4);
@@ -1433,7 +1725,7 @@ function drawScrollbarV(ctx, state, style) {
 }
 function drawScrollbarH(ctx, state, style) {
   if (state.scrollbarOpacityX <= 0.01) return;
-  const baseX = state.showHeader ? HEADER_WIDTH : 0;
+  const baseX = contentLeftX(state.showHeader);
   const visibleW = state.viewportWidth - baseX - SCROLLBAR_THICKNESS;
   const contentW = contentWidth(state.project, state.pxPerSec);
   if (contentW <= visibleW) return;
@@ -1516,11 +1808,25 @@ function parseColor(s) {
   if (m) return [Number(m[1]), Number(m[2]), Number(m[3])];
   return null;
 }
+function groupKeyframesByTime(kfs, epsilonMs) {
+  const sorted = [...kfs].sort((a, b) => a.time - b.time);
+  const out = [];
+  for (const k of sorted) {
+    const last = out[out.length - 1];
+    if (last && Math.abs(k.time - last.time) < epsilonMs) {
+      last.kfs.push(k);
+    } else {
+      out.push({ time: k.time, kfs: [k] });
+    }
+  }
+  return out;
+}
 
 // src/timeline/hit.ts
+var KEYFRAME_HIT_RADIUS = 8;
 function hitTest(x, y, ctx) {
   if (y < 0 || x < 0) return { kind: "outside" };
-  const baseX = ctx.showHeader ? HEADER_WIDTH : 0;
+  const baseX = contentLeftX(ctx.showHeader);
   const visibleH = ctx.viewportHeight - RULER_HEIGHT - SCROLLBAR_THICKNESS;
   const contentH = contentHeight(ctx.project.tracks, ctx.isDragging);
   if (contentH > visibleH && x >= ctx.viewportWidth - SCROLLBAR_THICKNESS && x < ctx.viewportWidth && y >= RULER_HEIGHT && y < ctx.viewportHeight - SCROLLBAR_THICKNESS) {
@@ -1572,6 +1878,23 @@ function hitTest(x, y, ctx) {
   if (ti < 0) return { kind: "outside" };
   const track = ctx.project.tracks[ti];
   const ms = xToMs(x, ctx.pxPerSec, ctx.scrollLeft, ctx.showHeader);
+  if (ctx.keyframesEnabled) {
+    for (const clip of track.clips) {
+      if (!clip.keyframes || clip.keyframes.length === 0) continue;
+      const startX = msToXLocal(clip.start, ctx);
+      for (const kf of clip.keyframes) {
+        const kfX = startX + kf.time / 1e3 * ctx.pxPerSec;
+        if (Math.abs(x - kfX) <= KEYFRAME_HIT_RADIUS) {
+          return {
+            kind: "keyframe",
+            trackIndex: ti,
+            clipId: clip.id,
+            keyframeId: kf.id
+          };
+        }
+      }
+    }
+  }
   for (const clip of track.clips) {
     const start = clip.start;
     const end = clip.start + (clip.out - clip.in);
@@ -1590,8 +1913,7 @@ function hitTest(x, y, ctx) {
   return { kind: "track-empty", trackIndex: ti };
 }
 function msToXLocal(ms, ctx) {
-  const base = ctx.showHeader ? HEADER_WIDTH : 0;
-  return base + ms / 1e3 * ctx.pxPerSec - ctx.scrollLeft;
+  return contentLeftX(ctx.showHeader) + ms / 1e3 * ctx.pxPerSec - ctx.scrollLeft;
 }
 
 // src/timeline/index.ts
@@ -1625,6 +1947,8 @@ var Timeline = class _Timeline {
   readOnly;
   autoFitEnabled;
   locale;
+  keyframesEnabled = false;
+  selectedKeyframe = null;
   scrollLeft = 0;
   scrollTop = 0;
   viewportWidth = 0;
@@ -1643,6 +1967,7 @@ var Timeline = class _Timeline {
   scrollbarDrag = null;
   hoveredClipId = null;
   hoveredTrackIndex = null;
+  hoveredKeyframe = null;
   hoverCursor = "default";
   dropTargetTrackIndex = null;
   snapX = null;
@@ -1681,6 +2006,8 @@ var Timeline = class _Timeline {
     this.readOnly = opts.readOnly === true;
     this.autoFitEnabled = opts.autoFit !== false;
     this.locale = mergeLocale(opts.locale);
+    this.keyframesEnabled = opts.keyframesEnabled === true;
+    this.selectedKeyframe = opts.selectedKeyframe ?? null;
     this.root.classList.add("aicut-timeline-canvas");
     this.root.innerHTML = "";
     this.root.style.position = this.root.style.position || "relative";
@@ -1728,6 +2055,7 @@ var Timeline = class _Timeline {
     this.thumbs.syncSources(this.project.sources);
     this.attachPointer();
     this.attachWheel();
+    this.attachKeyboard();
     this.attachResize();
     this.resizeCanvas();
     this.scheduleRender();
@@ -1808,7 +2136,7 @@ var Timeline = class _Timeline {
    * Exposed publicly so React/Vue wrappers can forward it to a ref.
    */
   getDebugInfo() {
-    const baseX = this.showHeader ? HEADER_WIDTH : 0;
+    const baseX = contentLeftX(this.showHeader);
     const clips = [];
     for (let ti = 0; ti < this.project.tracks.length; ti++) {
       const t = this.project.tracks[ti];
@@ -1861,17 +2189,17 @@ var Timeline = class _Timeline {
     this.ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
   }
   computeFitScale() {
-    const baseX = this.showHeader ? HEADER_WIDTH : 0;
+    const baseX = contentLeftX(this.showHeader);
     const w = this.viewportWidth - baseX - 24;
     const dur = projectDuration(this.project);
     if (w <= 0 || dur <= 0) return null;
     return clampScale(w / (dur / 1e3));
   }
   maxScrollLeft() {
-    const baseX = this.showHeader ? HEADER_WIDTH : 0;
+    const baseX = contentLeftX(this.showHeader);
     const visibleW = this.viewportWidth - baseX - SCROLLBAR_THICKNESS;
     const cw = contentWidth(this.project, this.pxPerSec);
-    return Math.max(0, cw - visibleW + 24);
+    return Math.max(0, cw - visibleW + TIMELINE_PAD_RIGHT);
   }
   maxScrollTop() {
     const visibleH = this.viewportHeight - RULER_HEIGHT - SCROLLBAR_THICKNESS;
@@ -1973,9 +2301,36 @@ var Timeline = class _Timeline {
       scrollbarOpacityX: this.scrollbarOpacity("h"),
       scrollbarActiveY: this.scrollbarDrag?.axis === "v",
       scrollbarActiveX: this.scrollbarDrag?.axis === "h",
-      locale: this.locale
+      locale: this.locale,
+      keyframesEnabled: this.keyframesEnabled,
+      selectedKeyframe: this.selectedKeyframe,
+      hoveredKeyframe: this.hoveredKeyframe,
+      keyframeDragGhost: this.drag?.kind === "keyframe-drag" ? {
+        clipId: this.drag.clipId,
+        keyframeId: this.drag.keyframeId,
+        ghostTimeMs: this.drag.ghostTimeMs
+      } : null
     };
   }
+  /** Host-pushed state — Editor calls this when its keyframe mode
+   *  changes or when a keyframe is selected/deselected externally. */
+  setKeyframeState(state) {
+    let dirty = false;
+    if (state.enabled !== void 0 && state.enabled !== this.keyframesEnabled) {
+      this.keyframesEnabled = state.enabled;
+      dirty = true;
+    }
+    if (state.selected !== void 0) {
+      const a = this.selectedKeyframe;
+      const b = state.selected;
+      const same = a?.clipId === b?.clipId && a?.keyframeId === b?.keyframeId;
+      if (!same) {
+        this.selectedKeyframe = b;
+        dirty = true;
+      }
+    }
+    if (dirty) this.scheduleRender();
+  }
   readStyle() {
     const cs = getComputedStyle(this.root);
     const v = (name, fallback) => cs.getPropertyValue(name).trim() || fallback;
@@ -2004,6 +2359,7 @@ var Timeline = class _Timeline {
     this.canvas.addEventListener("pointerleave", () => {
       if (!this.drag && !this.scrollbarDrag) {
         this.hoveredClipId = null;
+        this.hoveredKeyframe = null;
         this.hoverCursor = "default";
         this.hoverScrollbarY = false;
         this.hoverScrollbarX = false;
@@ -2044,7 +2400,7 @@ var Timeline = class _Timeline {
       return;
     }
     if (target.kind === "scrollbar-track-h") {
-      const baseX = this.showHeader ? HEADER_WIDTH : 0;
+      const baseX = contentLeftX(this.showHeader);
       const page = Math.max(
         80,
         this.viewportWidth - baseX - SCROLLBAR_THICKNESS
@@ -2084,6 +2440,33 @@ var Timeline = class _Timeline {
       this.scheduleRender();
       return;
     }
+    if (target.kind === "keyframe") {
+      const found = findClip(this.project, target.clipId);
+      const kf = found?.clip.keyframes?.find((k) => k.id === target.keyframeId);
+      if (!found || !kf) return;
+      this.selectedKeyframe = {
+        clipId: target.clipId,
+        keyframeId: target.keyframeId
+      };
+      this.opts.onSelectKeyframe?.({
+        clipId: target.clipId,
+        keyframeId: target.keyframeId
+      });
+      const absMs = found.clip.start + kf.time;
+      this.timeMs = absMs;
+      this.opts.onSeek?.(absMs);
+      this.drag = {
+        kind: "keyframe-drag",
+        clipId: target.clipId,
+        keyframeId: target.keyframeId,
+        trackIndex: target.trackIndex,
+        pointerStartX: x,
+        originalTimeMs: kf.time,
+        ghostTimeMs: kf.time
+      };
+      this.scheduleRender();
+      return;
+    }
     if (target.kind === "clip") {
       const found = findClip(this.project, target.clipId);
       if (!found) return;
@@ -2150,7 +2533,7 @@ var Timeline = class _Timeline {
         const ratio = maxScroll / free;
         this.scrollTop = this.scrollbarDrag.scrollStart + (y - this.scrollbarDrag.pointerStart) * ratio;
       } else {
-        const baseX = this.showHeader ? HEADER_WIDTH : 0;
+        const baseX = contentLeftX(this.showHeader);
         const visibleW = this.viewportWidth - baseX - SCROLLBAR_THICKNESS;
         const contentW = contentWidth(this.project, this.pxPerSec);
         const trackLen = visibleW - SCROLLBAR_INSET * 2;
@@ -2174,10 +2557,19 @@ var Timeline = class _Timeline {
       let cursor = "default";
       let onScrollbarV = false;
       let onScrollbarH = false;
+      let nextHoverKeyframe = null;
       if (target.kind === "clip") {
         nextHover = target.clipId;
         nextHoverTrack = target.trackIndex;
         cursor = this.readOnly ? "pointer" : "grab";
+      } else if (target.kind === "keyframe") {
+        nextHover = target.clipId;
+        nextHoverTrack = target.trackIndex;
+        nextHoverKeyframe = {
+          clipId: target.clipId,
+          keyframeId: target.keyframeId
+        };
+        cursor = "pointer";
       } else if (target.kind === "clip-handle-left" || target.kind === "clip-handle-right") {
         nextHover = target.clipId;
         nextHoverTrack = target.trackIndex;
@@ -2201,12 +2593,14 @@ var Timeline = class _Timeline {
         cursor = "default";
       }
       const hoverChanged = onScrollbarV !== this.hoverScrollbarY || onScrollbarH !== this.hoverScrollbarX;
-      if (nextHover !== this.hoveredClipId || nextHoverTrack !== this.hoveredTrackIndex || cursor !== this.hoverCursor || hoverChanged) {
+      const kfHoverChanged = (nextHoverKeyframe?.clipId ?? null) !== (this.hoveredKeyframe?.clipId ?? null) || (nextHoverKeyframe?.keyframeId ?? null) !== (this.hoveredKeyframe?.keyframeId ?? null);
+      if (nextHover !== this.hoveredClipId || nextHoverTrack !== this.hoveredTrackIndex || cursor !== this.hoverCursor || hoverChanged || kfHoverChanged) {
         this.hoveredClipId = nextHover;
         this.hoveredTrackIndex = nextHoverTrack;
         this.hoverCursor = cursor;
         this.hoverScrollbarY = onScrollbarV;
         this.hoverScrollbarX = onScrollbarH;
+        this.hoveredKeyframe = nextHoverKeyframe;
         this.scheduleRender();
       }
       return;
@@ -2229,6 +2623,26 @@ var Timeline = class _Timeline {
       this.maybeStartDragAutoScroll();
       return;
     }
+    if (this.drag.kind === "keyframe-drag") {
+      const found = findClip(this.project, this.drag.clipId);
+      if (!found) return;
+      const clip = found.clip;
+      const duration = clip.out - clip.in;
+      const dxPx = x - this.drag.pointerStartX;
+      const dxMs = dxPx / this.pxPerSec * 1e3;
+      const nextLocal = Math.max(
+        0,
+        Math.min(duration, this.drag.originalTimeMs + dxMs)
+      );
+      const snappedAbs = this.applySnap(clip.start + nextLocal, null);
+      const snappedLocal = Math.max(
+        0,
+        Math.min(duration, snappedAbs - clip.start)
+      );
+      this.drag.ghostTimeMs = Math.round(snappedLocal);
+      this.scheduleRender();
+      return;
+    }
     if (this.drag.kind === "trim-left" || this.drag.kind === "trim-right") {
       const dxPx = x - this.drag.pointerStartX;
       const dxMs = dxPx / this.pxPerSec * 1e3;
@@ -2381,6 +2795,14 @@ var Timeline = class _Timeline {
         });
         this.opts.onChange?.(this.getProject());
       }
+    } else if (drag.kind === "keyframe-drag") {
+      if (drag.ghostTimeMs !== drag.originalTimeMs) {
+        this.opts.onMoveKeyframe?.(
+          drag.clipId,
+          drag.keyframeId,
+          drag.ghostTimeMs
+        );
+      }
     } else if (drag.kind === "trim-left" || drag.kind === "trim-right") {
       const found = findClip(this.project, drag.clipId);
       if (found) {
@@ -2394,6 +2816,25 @@ var Timeline = class _Timeline {
     }
     this.scheduleRender();
   }
+  attachKeyboard() {
+    this.canvas.tabIndex = -1;
+    this.canvas.style.outline = "none";
+    this.canvas.addEventListener("keydown", (e) => {
+      if (e.code !== "ArrowLeft" && e.code !== "ArrowRight") return;
+      e.preventDefault();
+      const step = e.shiftKey ? bigFrameStepMs(this.project) : frameStepMs(this.project);
+      const dir = e.code === "ArrowLeft" ? -1 : 1;
+      const dur = projectDuration(this.project);
+      const next = Math.max(0, Math.min(dur, this.timeMs + dir * step));
+      if (next === this.timeMs) return;
+      this.timeMs = next;
+      this.opts.onSeek?.(next);
+      this.scheduleRender();
+    });
+    this.canvas.addEventListener("pointerdown", () => {
+      if (document.activeElement !== this.canvas) this.canvas.focus();
+    });
+  }
   attachWheel() {
     this.canvas.addEventListener(
       "wheel",
@@ -2414,7 +2855,7 @@ var Timeline = class _Timeline {
           if (Math.abs(next - this.pxPerSec) < 0.01) return;
           this.pxPerSec = next;
           this.hasAutoFitted = true;
-          const baseX = this.showHeader ? HEADER_WIDTH : 0;
+          const baseX = contentLeftX(this.showHeader);
           this.scrollLeft = anchorMs / 1e3 * this.pxPerSec - (cursorX - baseX);
           this.clampScroll();
           this.touchScrollbar("h");
@@ -2477,7 +2918,8 @@ var Timeline = class _Timeline {
       showHeader: this.showHeader,
       viewportWidth: this.viewportWidth,
       viewportHeight: this.viewportHeight,
-      isDragging: this.drag?.kind === "move"
+      isDragging: this.drag?.kind === "move",
+      keyframesEnabled: this.keyframesEnabled
     });
   }
   trackIndexAtY(y) {
@@ -2500,7 +2942,7 @@ var Timeline = class _Timeline {
       }
     }
     if (best !== ms) {
-      const baseX = this.showHeader ? HEADER_WIDTH : 0;
+      const baseX = contentLeftX(this.showHeader);
       this.snapX = baseX + best / 1e3 * this.pxPerSec - this.scrollLeft;
     } else {
       this.snapX = null;
@@ -2509,6 +2951,709 @@ var Timeline = class _Timeline {
   }
 };
 
+// src/ui/keyframe-overlay.ts
+var KeyframeOverlay = class _KeyframeOverlay {
+  editor;
+  host;
+  root;
+  frameBody;
+  handles;
+  rafHandle = null;
+  destroyed = false;
+  drag = null;
+  capturedPointerId = null;
+  /** Timer handle for the wheel-burst → interaction commit. */
+  wheelInteractionTimer = null;
+  /** Snap-target threshold in CSS px — the same feel as the timeline. */
+  static SNAP_PX = 8;
+  constructor(host, editor) {
+    this.host = host;
+    this.editor = editor;
+    this.root = document.createElement("div");
+    this.root.className = "aicut-keyframe-overlay";
+    this.root.setAttribute("data-testid", "aicut-keyframe-overlay");
+    this.root.style.display = "none";
+    this.frameBody = document.createElement("div");
+    this.frameBody.className = "aicut-keyframe-overlay__frame";
+    this.frameBody.setAttribute("data-testid", "aicut-keyframe-frame");
+    this.frameBody.addEventListener("pointerdown", (e) => this.onTransStart(e));
+    this.frameBody.addEventListener(
+      "wheel",
+      (e) => this.onPinchScale(e),
+      { passive: false }
+    );
+    this.root.appendChild(this.frameBody);
+    this.handles = {
+      tl: this.makeHandle("tl"),
+      tr: this.makeHandle("tr"),
+      bl: this.makeHandle("bl"),
+      br: this.makeHandle("br")
+    };
+    host.appendChild(this.root);
+    this.startTick();
+  }
+  destroy() {
+    this.destroyed = true;
+    if (this.rafHandle != null) cancelAnimationFrame(this.rafHandle);
+    if (this.wheelInteractionTimer != null) {
+      clearTimeout(this.wheelInteractionTimer);
+      this.wheelInteractionTimer = null;
+      this.editor.endInteraction();
+    }
+    this.root.remove();
+  }
+  // ---- frame body drag (translate) -------------------------------------
+  onTransStart(e) {
+    if (e.button !== 0) return;
+    const ctx = this.ensureSelectedClip();
+    if (!ctx) return;
+    e.preventDefault();
+    e.stopPropagation();
+    this.frameBody.setPointerCapture(e.pointerId);
+    this.capturedPointerId = e.pointerId;
+    this.drag = {
+      kind: "translate",
+      clipId: ctx.clip.id,
+      pointerStartX: e.clientX,
+      pointerStartY: e.clientY,
+      startPanX: ctx.transform.panX,
+      startPanY: ctx.transform.panY
+    };
+    this.editor.beginInteraction();
+    this.frameBody.addEventListener("pointermove", this.onPointerMove);
+    this.frameBody.addEventListener("pointerup", this.onPointerUp);
+    this.frameBody.addEventListener("pointercancel", this.onPointerUp);
+  }
+  // ---- pinch-to-scale --------------------------------------------------
+  onPinchScale(e) {
+    if (!e.ctrlKey) return;
+    const ctx = this.ensureSelectedClip();
+    if (!ctx) return;
+    e.preventDefault();
+    e.stopPropagation();
+    const step = Math.max(-50, Math.min(50, -e.deltaY));
+    const factor = Math.exp(step * 0.01);
+    const next = Math.max(
+      0.05,
+      Math.min(16, ctx.transform.scale * factor)
+    );
+    if (this.wheelInteractionTimer == null) {
+      this.editor.beginInteraction();
+    } else {
+      clearTimeout(this.wheelInteractionTimer);
+    }
+    this.wheelInteractionTimer = window.setTimeout(() => {
+      this.wheelInteractionTimer = null;
+      this.editor.endInteraction();
+    }, 200);
+    this.editor.setValueAtPlayhead(
+      ctx.clip.id,
+      "scale",
+      Math.round(next * 100) / 100
+    );
+  }
+  // ---- corner-handle drag (scale) --------------------------------------
+  onScaleStart(corner, e) {
+    if (e.button !== 0) return;
+    const ctx = this.ensureSelectedClip();
+    if (!ctx) return;
+    e.preventDefault();
+    e.stopPropagation();
+    const rect = this.editor.getActiveOutputFrameRect() ?? this.editor.getActiveFrameRect();
+    if (!rect) return;
+    const hostRect = this.host.getBoundingClientRect();
+    const cx = hostRect.left + rect.x + rect.w / 2;
+    const cy = hostRect.top + rect.y + rect.h / 2;
+    const startDist = Math.hypot(e.clientX - cx, e.clientY - cy);
+    if (startDist < 1) return;
+    const target = this.handles[corner];
+    target.setPointerCapture(e.pointerId);
+    this.capturedPointerId = e.pointerId;
+    this.drag = {
+      kind: "scale",
+      clipId: ctx.clip.id,
+      centerX: cx,
+      centerY: cy,
+      startDistance: startDist,
+      startScale: ctx.transform.scale
+    };
+    this.editor.beginInteraction();
+    target.addEventListener("pointermove", this.onPointerMove);
+    target.addEventListener("pointerup", this.onPointerUp);
+    target.addEventListener("pointercancel", this.onPointerUp);
+  }
+  onPointerMove = (e) => {
+    if (!this.drag) return;
+    if (this.drag.kind === "translate") {
+      const dx = e.clientX - this.drag.pointerStartX;
+      const dy = e.clientY - this.drag.pointerStartY;
+      const rawPanX = this.drag.startPanX + dx;
+      const rawPanY = this.drag.startPanY + dy;
+      const snapped = this.applySnap(this.drag.clipId, rawPanX, rawPanY);
+      this.editor.setValueAtPlayhead(
+        this.drag.clipId,
+        "panX",
+        Math.round(snapped.panX)
+      );
+      this.editor.setValueAtPlayhead(
+        this.drag.clipId,
+        "panY",
+        Math.round(snapped.panY)
+      );
+    } else {
+      const dist = Math.hypot(
+        e.clientX - this.drag.centerX,
+        e.clientY - this.drag.centerY
+      );
+      const ratio = dist / this.drag.startDistance;
+      const next = Math.max(
+        0.05,
+        Math.min(16, this.drag.startScale * ratio)
+      );
+      this.editor.setValueAtPlayhead(
+        this.drag.clipId,
+        "scale",
+        Math.round(next * 100) / 100
+      );
+    }
+  };
+  /**
+   * Snap raw pan to: centered (panX/Y = 0) and the four edge-alignment
+   * stops (content's L/R/T/B edge flush with the output's matching
+   * edge). When content is smaller than output, the edge stops collapse
+   * to the same point as 0 — harmless dup. Threshold = 8 CSS px.
+   */
+  applySnap(clipId, rawPanX, rawPanY) {
+    const out = this.editor.getActiveOutputFrameRect();
+    if (!out) return { panX: rawPanX, panY: rawPanY };
+    const clip = this.findClip(clipId);
+    if (!clip) return { panX: rawPanX, panY: rawPanY };
+    const t = (() => {
+      try {
+        const transformer = this.editor.getActiveFrameRect();
+        if (!transformer) return null;
+        return { w: transformer.w, h: transformer.h };
+      } catch {
+        return null;
+      }
+    })();
+    const contentW = t?.w ?? out.w;
+    const contentH = t?.h ?? out.h;
+    const edgeX = (contentW - out.w) / 2;
+    const edgeY = (contentH - out.h) / 2;
+    const xTargets = [0, edgeX, -edgeX];
+    const yTargets = [0, edgeY, -edgeY];
+    const px = nearestSnap(rawPanX, xTargets, _KeyframeOverlay.SNAP_PX);
+    const py = nearestSnap(rawPanY, yTargets, _KeyframeOverlay.SNAP_PX);
+    return { panX: px, panY: py };
+  }
+  findClip(clipId) {
+    const project = this.editor.getProject();
+    for (const t of project.tracks) {
+      const c = t.clips.find((cl) => cl.id === clipId);
+      if (c) return c;
+    }
+    return null;
+  }
+  onPointerUp = (e) => {
+    if (!this.drag) return;
+    const targetEl = e.currentTarget;
+    if (targetEl && this.capturedPointerId === e.pointerId) {
+      try {
+        targetEl.releasePointerCapture(e.pointerId);
+      } catch {
+      }
+    }
+    targetEl?.removeEventListener("pointermove", this.onPointerMove);
+    targetEl?.removeEventListener("pointerup", this.onPointerUp);
+    targetEl?.removeEventListener("pointercancel", this.onPointerUp);
+    this.drag = null;
+    this.capturedPointerId = null;
+    this.editor.endInteraction();
+  };
+  // ---- per-frame layout ------------------------------------------------
+  startTick() {
+    const tick = () => {
+      if (this.destroyed) return;
+      this.layout();
+      this.rafHandle = requestAnimationFrame(tick);
+    };
+    this.rafHandle = requestAnimationFrame(tick);
+  }
+  layout() {
+    const enabled = this.editor.isKeyframesEnabled();
+    if (!enabled) {
+      this.root.style.display = "none";
+      return;
+    }
+    const outRect = this.editor.getActiveOutputFrameRect();
+    const contentRect = this.editor.getActiveFrameRect() ?? outRect;
+    if (!outRect) {
+      this.root.style.display = "none";
+      return;
+    }
+    this.root.style.display = "block";
+    Object.assign(this.frameBody.style, {
+      left: `${outRect.x}px`,
+      top: `${outRect.y}px`,
+      width: `${outRect.w}px`,
+      height: `${outRect.h}px`
+    });
+    const fullyCovered = contentRect ? contentRect.x <= outRect.x + 0.5 && contentRect.x + contentRect.w >= outRect.x + outRect.w - 0.5 && contentRect.y <= outRect.y + 0.5 && contentRect.y + contentRect.h >= outRect.y + outRect.h - 0.5 : true;
+    this.frameBody.classList.toggle(
+      "aicut-keyframe-overlay__frame--warn",
+      !fullyCovered
+    );
+    const halfHandle = 6;
+    const r = contentRect ?? outRect;
+    const fbLeft = r.x;
+    const fbTop = r.y;
+    const fbRight = r.x + r.w;
+    const fbBottom = r.y + r.h;
+    const place = (el, cx, cy) => {
+      el.style.left = `${cx - halfHandle}px`;
+      el.style.top = `${cy - halfHandle}px`;
+    };
+    place(this.handles.tl, fbLeft, fbTop);
+    place(this.handles.tr, fbRight, fbTop);
+    place(this.handles.bl, fbLeft, fbBottom);
+    place(this.handles.br, fbRight, fbBottom);
+  }
+  // ---- helpers ---------------------------------------------------------
+  makeHandle(name) {
+    const el = document.createElement("div");
+    el.className = `aicut-keyframe-overlay__handle aicut-keyframe-overlay__handle--${name}`;
+    el.setAttribute("data-testid", `aicut-keyframe-handle-${name}`);
+    el.addEventListener("pointerdown", (e) => this.onScaleStart(name, e));
+    this.root.appendChild(el);
+    return el;
+  }
+  /**
+   * Resolve the currently selected clip + its current effective
+   * transform (so drag baselines are correct). Returns null when no
+   * clip is selected or the playhead isn't over it.
+   */
+  ensureSelectedClip() {
+    const selectedClipId = this.editor.getSelection();
+    if (!selectedClipId) return null;
+    const project = this.editor.getProject();
+    let clip = null;
+    for (const t of project.tracks) {
+      const c = t.clips.find((cl) => cl.id === selectedClipId);
+      if (c) {
+        clip = c;
+        break;
+      }
+    }
+    if (!clip) return null;
+    const playheadLocal = this.editor.getTime() - clip.start;
+    if (playheadLocal < 0 || playheadLocal > clip.out - clip.in) {
+      return null;
+    }
+    const transform = getEffectiveTransform(clip, playheadLocal);
+    return { clip, transform };
+  }
+};
+function nearestSnap(raw, targets, threshold) {
+  let best = raw;
+  let bestDist = threshold;
+  for (const t of targets) {
+    const d = Math.abs(raw - t);
+    if (d < bestDist) {
+      bestDist = d;
+      best = t;
+    }
+  }
+  return best;
+}
+
+// src/ui/keyframe-panel.ts
+var EASING_VALUES = [
+  "linear",
+  "easeIn",
+  "easeOut",
+  "easeInOut"
+];
+function easingLabel(value, locale) {
+  switch (value) {
+    case "linear":
+      return locale.keyframeEasingLinear;
+    case "easeIn":
+      return locale.keyframeEasingEaseIn;
+    case "easeOut":
+      return locale.keyframeEasingEaseOut;
+    case "easeInOut":
+      return locale.keyframeEasingEaseInOut;
+  }
+}
+var TIME_EPS_MS = 16;
+var KeyframePanel = class {
+  editor;
+  locale;
+  root;
+  inputs;
+  kfBadges;
+  timeLabel;
+  titleLabel;
+  resetBtn;
+  easingTrigger;
+  easingTriggerLabel;
+  easingMenu;
+  easingItems;
+  easingValue = "linear";
+  easingDisabled = false;
+  easingOpen = false;
+  easingLabelEl;
+  rowLabels;
+  lastSyncKey = "";
+  // Bound once so add/remove listener pairs reference the same fn.
+  boundOutsideClick = null;
+  boundDocKeydown = null;
+  constructor(host, editor, locale) {
+    this.editor = editor;
+    this.locale = locale;
+    this.root = document.createElement("div");
+    this.root.className = "aicut-keyframe-panel";
+    this.root.setAttribute("data-testid", "aicut-keyframe-panel");
+    this.root.style.display = "none";
+    this.root.addEventListener("pointerdown", (e) => e.stopPropagation());
+    this.root.addEventListener("wheel", (e) => e.stopPropagation());
+    const title = document.createElement("div");
+    title.className = "aicut-keyframe-panel__title";
+    this.titleLabel = document.createElement("span");
+    this.timeLabel = document.createElement("span");
+    this.timeLabel.className = "aicut-keyframe-panel__time";
+    title.append(this.titleLabel, this.timeLabel);
+    this.root.appendChild(title);
+    const xRow = this.makeRow("kf-x", "panX", 1);
+    const yRow = this.makeRow("kf-y", "panY", 1);
+    const scaleRow = this.makeRow("kf-scale", "scale", 0.05);
+    this.inputs = {
+      panX: xRow.input,
+      panY: yRow.input,
+      scale: scaleRow.input
+    };
+    this.rowLabels = {
+      panX: xRow.label,
+      panY: yRow.label,
+      scale: scaleRow.label
+    };
+    this.kfBadges = {
+      panX: this.makeBadge(this.inputs.panX),
+      panY: this.makeBadge(this.inputs.panY),
+      scale: this.makeBadge(this.inputs.scale)
+    };
+    const easingRow = document.createElement("div");
+    easingRow.className = "aicut-keyframe-panel__row aicut-keyframe-panel__row--easing";
+    this.easingLabelEl = document.createElement("label");
+    const dd = document.createElement("div");
+    dd.className = "aicut-keyframe-panel__dropdown";
+    dd.setAttribute("data-testid", "aicut-kf-easing");
+    this.easingTrigger = document.createElement("button");
+    this.easingTrigger.type = "button";
+    this.easingTrigger.className = "aicut-keyframe-panel__dropdown-trigger";
+    this.easingTrigger.setAttribute("aria-haspopup", "listbox");
+    this.easingTrigger.setAttribute("aria-expanded", "false");
+    this.easingTriggerLabel = document.createElement("span");
+    this.easingTriggerLabel.className = "aicut-keyframe-panel__dropdown-trigger-label";
+    const chevron = document.createElement("span");
+    chevron.className = "aicut-keyframe-panel__dropdown-chevron";
+    chevron.setAttribute("aria-hidden", "true");
+    this.easingTrigger.append(this.easingTriggerLabel, chevron);
+    this.easingTrigger.addEventListener("click", (e) => {
+      e.stopPropagation();
+      if (this.easingDisabled) return;
+      this.toggleEasingMenu();
+    });
+    this.easingTrigger.addEventListener("keydown", (e) => {
+      if (this.easingDisabled) return;
+      if (e.key === "Enter" || e.key === " " || e.key === "ArrowDown") {
+        e.preventDefault();
+        if (!this.easingOpen) this.openEasingMenu();
+        this.easingItems.get(this.easingValue)?.focus();
+      }
+    });
+    this.easingMenu = document.createElement("ul");
+    this.easingMenu.className = "aicut-keyframe-panel__dropdown-menu";
+    this.easingMenu.setAttribute("role", "listbox");
+    this.easingMenu.style.display = "none";
+    this.easingItems = /* @__PURE__ */ new Map();
+    for (const value of EASING_VALUES) {
+      const li = document.createElement("li");
+      li.className = "aicut-keyframe-panel__dropdown-item";
+      li.setAttribute("role", "option");
+      li.setAttribute("data-value", value);
+      li.setAttribute("tabindex", "-1");
+      li.addEventListener("click", (e) => {
+        e.stopPropagation();
+        this.selectEasing(value);
+      });
+      li.addEventListener("keydown", (e) => this.onMenuKeydown(e, value));
+      this.easingItems.set(value, li);
+      this.easingMenu.appendChild(li);
+    }
+    dd.append(this.easingTrigger, this.easingMenu);
+    easingRow.append(this.easingLabelEl, dd);
+    this.root.appendChild(easingRow);
+    const actions = document.createElement("div");
+    actions.className = "aicut-keyframe-panel__actions";
+    this.resetBtn = document.createElement("button");
+    this.resetBtn.type = "button";
+    this.resetBtn.className = "aicut-keyframe-panel__reset";
+    this.resetBtn.setAttribute("data-testid", "aicut-keyframe-reset");
+    this.resetBtn.addEventListener("click", () => this.onReset());
+    actions.appendChild(this.resetBtn);
+    this.root.appendChild(actions);
+    this.applyLocaleText();
+    host.appendChild(this.root);
+  }
+  setLocale(locale) {
+    this.locale = locale;
+    this.applyLocaleText();
+    this.lastSyncKey = "";
+    this.render();
+  }
+  applyLocaleText() {
+    this.titleLabel.textContent = this.locale.keyframePanelTitle;
+    this.rowLabels.panX.textContent = this.locale.keyframePanelLabelX;
+    this.rowLabels.panY.textContent = this.locale.keyframePanelLabelY;
+    this.rowLabels.scale.textContent = this.locale.keyframePanelLabelScale;
+    this.easingLabelEl.textContent = this.locale.keyframePanelLabelEasing;
+    this.resetBtn.textContent = this.locale.keyframePanelReset;
+    this.resetBtn.title = this.locale.keyframePanelResetTitle;
+    for (const [value, li] of this.easingItems) {
+      li.textContent = easingLabel(value, this.locale);
+    }
+    this.easingTriggerLabel.textContent = easingLabel(
+      this.easingValue,
+      this.locale
+    );
+  }
+  destroy() {
+    this.closeEasingMenu();
+    this.root.remove();
+  }
+  render() {
+    const enabled = this.editor.isKeyframesEnabled();
+    const sel = this.editor.getSelectedKeyframe();
+    if (!enabled || !sel) {
+      this.root.style.display = "none";
+      this.lastSyncKey = "";
+      return;
+    }
+    const clip = this.findClip(sel.clipId);
+    const anchorKf = clip?.keyframes?.find((k) => k.id === sel.keyframeId);
+    if (!clip || !anchorKf) {
+      this.root.style.display = "none";
+      this.lastSyncKey = "";
+      return;
+    }
+    const time = anchorKf.time;
+    const moment = (clip.keyframes ?? []).filter(
+      (k) => Math.abs(k.time - time) < TIME_EPS_MS
+    );
+    const interp = getEffectiveTransform(clip, time);
+    const valueOf = (prop) => {
+      const m = moment.find((k) => k.prop === prop);
+      if (m) return m.value;
+      return interp[prop];
+    };
+    const v = {
+      panX: valueOf("panX"),
+      panY: valueOf("panY"),
+      scale: valueOf("scale")
+    };
+    const sharedEasing = (() => {
+      if (moment.length === 0) return "linear";
+      const anchor = moment.find((k) => k.id === sel.keyframeId) ?? moment[0];
+      return anchor.easing ?? "linear";
+    })();
+    const syncKey = `${clip.id}|${time}|${v.panX.toFixed(2)}|${v.panY.toFixed(2)}|${v.scale.toFixed(4)}|${moment.map((m) => m.prop).join(",")}|${sharedEasing}`;
+    this.root.style.display = "flex";
+    if (syncKey === this.lastSyncKey) return;
+    this.lastSyncKey = syncKey;
+    this.setIfBlur(this.inputs.panX, String(Math.round(v.panX)));
+    this.setIfBlur(this.inputs.panY, String(Math.round(v.panY)));
+    this.setIfBlur(this.inputs.scale, v.scale.toFixed(2));
+    this.timeLabel.textContent = `${(time / 1e3).toFixed(2)}${this.locale.keyframePanelTimeSuffix}`;
+    this.setEasingValue(sharedEasing);
+    this.setEasingDisabled(moment.length === 0);
+    for (const p of ["panX", "panY", "scale"]) {
+      const animated = moment.some((k) => k.prop === p) || hasKeyframesForProp(clip, p);
+      const pinned = moment.some((k) => k.prop === p);
+      this.kfBadges[p].classList.toggle(
+        "aicut-keyframe-panel__badge--on",
+        pinned
+      );
+      this.kfBadges[p].title = pinned ? this.locale.keyframePanelBadgePinned : animated ? this.locale.keyframePanelBadgeAnimated : this.locale.keyframePanelBadgeStatic;
+    }
+    this.resetBtn.disabled = false;
+  }
+  // ---- internals ------------------------------------------------------
+  makeRow(testId, prop, step) {
+    const row = document.createElement("div");
+    row.className = "aicut-keyframe-panel__row";
+    const lab = document.createElement("label");
+    const input = document.createElement("input");
+    input.type = "number";
+    input.step = String(step);
+    input.setAttribute("data-testid", `aicut-${testId}`);
+    input.addEventListener("blur", () => this.commit(prop, input.value));
+    input.addEventListener("keydown", (e) => {
+      if (e.key === "Enter") input.blur();
+    });
+    row.append(lab, input);
+    this.root.appendChild(row);
+    return { input, label: lab };
+  }
+  makeBadge(input) {
+    const dot = document.createElement("span");
+    dot.className = "aicut-keyframe-panel__badge";
+    input.parentElement?.appendChild(dot);
+    return dot;
+  }
+  commit(prop, raw) {
+    const num = Number(raw);
+    if (!Number.isFinite(num)) return;
+    const sel = this.editor.getSelectedKeyframe();
+    if (!sel) return;
+    const clip = this.findClip(sel.clipId);
+    const anchorKf = clip?.keyframes?.find((k) => k.id === sel.keyframeId);
+    if (!clip || !anchorKf) return;
+    this.editor.addKeyframe(sel.clipId, prop, {
+      time: anchorKf.time,
+      value: num
+    });
+    if (anchorKf.prop !== prop) {
+      const refreshedClip = this.findClip(sel.clipId);
+      const created = (refreshedClip?.keyframes ?? []).find(
+        (k) => k.prop === prop && Math.abs(k.time - anchorKf.time) < TIME_EPS_MS
+      );
+      if (created) {
+        this.editor.setSelectedKeyframe({
+          clipId: sel.clipId,
+          keyframeId: created.id
+        });
+      }
+    }
+  }
+  // ---- custom dropdown -------------------------------------------------
+  setEasingValue(value) {
+    if (this.easingValue === value) return;
+    this.easingValue = value;
+    this.easingTriggerLabel.textContent = easingLabel(value, this.locale);
+    for (const [v, li] of this.easingItems) {
+      li.classList.toggle(
+        "aicut-keyframe-panel__dropdown-item--selected",
+        v === value
+      );
+      li.setAttribute("aria-selected", v === value ? "true" : "false");
+    }
+  }
+  setEasingDisabled(disabled) {
+    if (this.easingDisabled === disabled) return;
+    this.easingDisabled = disabled;
+    this.easingTrigger.disabled = disabled;
+    this.easingTrigger.classList.toggle(
+      "aicut-keyframe-panel__dropdown-trigger--disabled",
+      disabled
+    );
+    if (disabled && this.easingOpen) this.closeEasingMenu();
+  }
+  toggleEasingMenu() {
+    if (this.easingOpen) this.closeEasingMenu();
+    else this.openEasingMenu();
+  }
+  openEasingMenu() {
+    if (this.easingOpen || this.easingDisabled) return;
+    this.easingOpen = true;
+    this.easingMenu.style.display = "";
+    this.easingTrigger.setAttribute("aria-expanded", "true");
+    this.easingTrigger.classList.add(
+      "aicut-keyframe-panel__dropdown-trigger--open"
+    );
+    requestAnimationFrame(() => {
+      if (!this.easingOpen) return;
+      this.boundOutsideClick = (e) => {
+        if (!this.easingMenu.contains(e.target) && !this.easingTrigger.contains(e.target)) {
+          this.closeEasingMenu();
+        }
+      };
+      this.boundDocKeydown = (e) => {
+        if (e.key === "Escape") {
+          e.stopPropagation();
+          this.closeEasingMenu();
+          this.easingTrigger.focus();
+        } else if (e.key === "Tab") {
+          this.closeEasingMenu();
+        }
+      };
+      document.addEventListener("click", this.boundOutsideClick, true);
+      document.addEventListener("keydown", this.boundDocKeydown);
+    });
+  }
+  closeEasingMenu() {
+    if (!this.easingOpen) return;
+    this.easingOpen = false;
+    this.easingMenu.style.display = "none";
+    this.easingTrigger.setAttribute("aria-expanded", "false");
+    this.easingTrigger.classList.remove(
+      "aicut-keyframe-panel__dropdown-trigger--open"
+    );
+    if (this.boundOutsideClick) {
+      document.removeEventListener("click", this.boundOutsideClick, true);
+      this.boundOutsideClick = null;
+    }
+    if (this.boundDocKeydown) {
+      document.removeEventListener("keydown", this.boundDocKeydown);
+      this.boundDocKeydown = null;
+    }
+  }
+  selectEasing(value) {
+    this.closeEasingMenu();
+    this.easingTrigger.focus();
+    const sel = this.editor.getSelectedKeyframe();
+    if (!sel) return;
+    const clip = this.findClip(sel.clipId);
+    const anchorKf = clip?.keyframes?.find((k) => k.id === sel.keyframeId);
+    if (!clip || !anchorKf) return;
+    this.editor.setKeyframesEasingAtTime(sel.clipId, anchorKf.time, value);
+  }
+  onMenuKeydown(e, value) {
+    if (e.key === "Enter" || e.key === " ") {
+      e.preventDefault();
+      this.selectEasing(value);
+      return;
+    }
+    if (e.key === "ArrowDown" || e.key === "ArrowUp") {
+      e.preventDefault();
+      const idx = EASING_VALUES.indexOf(value);
+      const next = e.key === "ArrowDown" ? EASING_VALUES[(idx + 1) % EASING_VALUES.length] : EASING_VALUES[(idx - 1 + EASING_VALUES.length) % EASING_VALUES.length];
+      this.easingItems.get(next)?.focus();
+    }
+  }
+  onReset() {
+    const sel = this.editor.getSelectedKeyframe();
+    if (!sel) return;
+    const clip = this.findClip(sel.clipId);
+    const anchorKf = clip?.keyframes?.find((k) => k.id === sel.keyframeId);
+    if (!clip || !anchorKf) return;
+    this.editor.resetKeyframesAtTime(sel.clipId, anchorKf.time);
+  }
+  setIfBlur(input, value) {
+    if (document.activeElement === input) return;
+    if (input.value !== value) input.value = value;
+  }
+  findClip(clipId) {
+    const project = this.editor.getProject();
+    for (const t of project.tracks) {
+      const c = t.clips.find((cl) => cl.id === clipId);
+      if (c) return c;
+    }
+    return null;
+  }
+};
+
 // src/ui/icons.ts
 var wrap = (path) => `<svg width="14" height="14" viewBox="0 0 16 16" fill="none" aria-hidden="true">${path}</svg>`;
 var ICONS = {
@@ -2552,6 +3697,24 @@ var ICONS = {
   trash: wrap(
     `<g transform="translate(1 1)" fill="currentColor"><path d="M5 1.25h4v.9H13v1.05H1V2.15h4v-.9zM2.4 4.1h9.2l-.65 8.9c-.04.55-.5.96-1.05.96H4.1c-.55 0-1.01-.41-1.05-.96L2.4 4.1zm2.3 1.7l.35 7.1h1l-.35-7.1h-1zm2.65 0v7.1h1V5.8h-1zm2.3 0l-.35 7.1h1l.35-7.1h-1z"/></g>`
   ),
+  /** "Skip to start" — vertical bar + left-pointing triangle. Sits to
+   *  the left of the keyframe diamond so the clip-edge nav cluster
+   *  reads as [|◀ ◇ ▶|] = "go to clip start / add kf / go to clip end". */
+  seekClipStart: wrap(
+    `<g transform="translate(2 3)" fill="currentColor"><rect x="0" y="0" width="1.6" height="10" rx="0.4"/><path d="M11 0.6c0-0.5-0.55-0.78-0.95-0.48l-6.5 4.4c-0.34 0.23-0.34 0.73 0 0.96l6.5 4.4c0.4 0.3 0.95 0.02 0.95-0.48z"/></g>`
+  ),
+  /** "Skip to end" — mirror of seekClipStart. */
+  seekClipEnd: wrap(
+    `<g transform="translate(1 3)" fill="currentColor"><path d="M0 0.6c0-0.5 0.55-0.78 0.95-0.48l6.5 4.4c0.34 0.23 0.34 0.73 0 0.96l-6.5 4.4c-0.4 0.3-0.95 0.02-0.95-0.48z"/><rect x="10.4" y="0" width="1.6" height="10" rx="0.4"/></g>`
+  ),
+  /** Outlined diamond (rotated square) — "add keyframe" affordance. */
+  keyframeOutline: wrap(
+    `<g transform="translate(8 8) rotate(45) translate(-4 -4)" fill="none" stroke="currentColor" stroke-width="1.5"><rect x="0.5" y="0.5" width="7" height="7" rx="0.5"/></g>`
+  ),
+  /** Filled diamond — shown when a keyframe already exists at playhead. */
+  keyframeFilled: wrap(
+    `<g transform="translate(8 8) rotate(45) translate(-4 -4)" fill="currentColor"><rect x="0" y="0" width="8" height="8" rx="0.8"/></g>`
+  ),
   /** Counter-clockwise circular arrow — "reset to initial layout". */
   reset: `<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><polyline points="1 4 1 10 7 10"/><path d="M3.51 15a9 9 0 1 0 2.13-9.36L1 10"/></svg>`
 };
@@ -2578,6 +3741,9 @@ var Toolbar = class {
   splitBtn;
   trimLeftBtn;
   trimRightBtn;
+  seekClipStartBtn;
+  seekClipEndBtn;
+  keyframeBtn;
   playBtn;
   playIcon;
   timeLabel;
@@ -2603,9 +3769,37 @@ var Toolbar = class {
     this.splitBtn = mkIconButton("split", locale.split, () => cb.onSplit(), "aicut-split");
     this.trimLeftBtn = mkIconButton("trimLeft", locale.trimLeft, () => cb.onTrimLeft(), "aicut-trim-left");
     this.trimRightBtn = mkIconButton("trimRight", locale.trimRight, () => cb.onTrimRight(), "aicut-trim-right");
-    const speedBtn = mkIconButton("speed", locale.speedComingSoon, () => void 0, "aicut-speed");
-    speedBtn.disabled = true;
-    left.append(this.undoBtn, this.redoBtn, this.splitBtn, this.trimLeftBtn, this.trimRightBtn, speedBtn);
+    this.seekClipStartBtn = mkIconButton(
+      "seekClipStart",
+      locale.seekClipStart,
+      () => cb.onSeekClipStart(),
+      "aicut-seek-clip-start"
+    );
+    this.seekClipStartBtn.style.display = "none";
+    this.keyframeBtn = mkIconButton(
+      "keyframeOutline",
+      locale.keyframeAdd,
+      () => cb.onKeyframeToggle(),
+      "aicut-keyframe"
+    );
+    this.keyframeBtn.style.display = "none";
+    this.seekClipEndBtn = mkIconButton(
+      "seekClipEnd",
+      locale.seekClipEnd,
+      () => cb.onSeekClipEnd(),
+      "aicut-seek-clip-end"
+    );
+    this.seekClipEndBtn.style.display = "none";
+    left.append(
+      this.undoBtn,
+      this.redoBtn,
+      this.splitBtn,
+      this.trimLeftBtn,
+      this.trimRightBtn,
+      this.seekClipStartBtn,
+      this.keyframeBtn,
+      this.seekClipEndBtn
+    );
     const center = mkGroup("aicut-toolbar-center");
     this.timeLabel = mkSpan("aicut-time-current", "00:00", "aicut-time-current");
     this.playBtn = document.createElement("button");
@@ -2682,11 +3876,38 @@ var Toolbar = class {
       this.trimLeftBtn.disabled = !state.canTrim;
       this.trimRightBtn.disabled = !state.canTrim;
     }
+    if (!this.lastState || this.lastState.clipEdgeNavEnabled !== state.clipEdgeNavEnabled) {
+      const display = state.clipEdgeNavEnabled ? "" : "none";
+      this.seekClipStartBtn.style.display = display;
+      this.seekClipEndBtn.style.display = display;
+    }
+    if (!this.lastState || this.lastState.canSeekClipEdge !== state.canSeekClipEdge) {
+      this.seekClipStartBtn.disabled = !state.canSeekClipEdge;
+      this.seekClipEndBtn.disabled = !state.canSeekClipEdge;
+    }
     if (!this.lastState || this.lastState.snap !== state.snap) {
       this.snapBtn.setAttribute("aria-pressed", state.snap ? "true" : "false");
       this.snapBtn.classList.toggle("aicut-toggle-on", state.snap);
       this.snapBtn.title = state.snap ? this.locale.snapOnTitle : this.locale.snapOffTitle;
     }
+    if (!this.lastState || this.lastState.keyframesEnabled !== state.keyframesEnabled) {
+      this.keyframeBtn.style.display = state.keyframesEnabled ? "" : "none";
+    }
+    if (state.keyframesEnabled) {
+      if (!this.lastState || this.lastState.hasKeyframeAtPlayhead !== state.hasKeyframeAtPlayhead) {
+        this.keyframeBtn.innerHTML = state.hasKeyframeAtPlayhead ? ICONS.keyframeFilled : ICONS.keyframeOutline;
+        const title = state.hasKeyframeAtPlayhead ? this.locale.keyframeRemove : this.locale.keyframeAdd;
+        this.keyframeBtn.title = title;
+        this.keyframeBtn.setAttribute("aria-label", title);
+        this.keyframeBtn.setAttribute(
+          "data-state",
+          state.hasKeyframeAtPlayhead ? "on" : "off"
+        );
+      }
+      if (!this.lastState || this.lastState.canKeyframe !== state.canKeyframe) {
+        this.keyframeBtn.disabled = !state.canKeyframe;
+      }
+    }
     if (!this.lastState || this.lastState.pxPerSec !== state.pxPerSec) {
       const ratio = scaleToSlider(state.pxPerSec);
       const nextVal = String(Math.round(ratio * 100));
@@ -2719,12 +3940,20 @@ var Toolbar = class {
     applyTitle(this.splitBtn, locale.split);
     applyTitle(this.trimLeftBtn, locale.trimLeft);
     applyTitle(this.trimRightBtn, locale.trimRight);
+    applyTitle(this.seekClipStartBtn, locale.seekClipStart);
+    applyTitle(this.seekClipEndBtn, locale.seekClipEnd);
     applyTitle(this.playBtn, locale.playPause);
     applyTitle(this.fullscreenBtn, locale.fullscreen);
     applyTitle(this.snapBtn, locale.snap);
     applyTitle(this.zoomOutBtn, locale.zoomOut);
     applyTitle(this.zoomInBtn, locale.zoomIn);
     applyTitle(this.resetBtn, locale.reset);
+    if (this.keyframeBtn) {
+      const hasKf = this.lastState?.hasKeyframeAtPlayhead === true;
+      const t = hasKf ? locale.keyframeRemove : locale.keyframeAdd;
+      this.keyframeBtn.title = t;
+      this.keyframeBtn.setAttribute("aria-label", t);
+    }
     if (this.lastState) {
       this.snapBtn.title = this.lastState.snap ? locale.snapOnTitle : locale.snapOffTitle;
     }
@@ -2784,6 +4013,8 @@ var EditorUI = class {
   toolbar;
   timelineHost;
   timeline;
+  keyframePanel;
+  keyframeOverlay;
   fullscreen = false;
   onDocKeydown = null;
   constructor(root, editor, cb) {
@@ -2830,10 +4061,14 @@ var EditorUI = class {
       snap: editor.getSnap(),
       autoFit: true,
       locale,
+      keyframesEnabled: editor.isKeyframesEnabled(),
+      selectedKeyframe: editor.getSelectedKeyframe(),
       onSeek: cb.onSeek,
       onSelectClip: cb.onSelectClip,
       onMoveClip: cb.onMoveClip,
       onResizeClip: cb.onResizeClip,
+      onSelectKeyframe: cb.onSelectKeyframe,
+      onMoveKeyframe: cb.onMoveKeyframe,
       onScaleChange: cb.onScaleChange,
       onDeleteTrack: (trackId) => editor.removeTrack(trackId),
       // Mirror the editor's smart routing into the drag preview so
@@ -2858,6 +4093,8 @@ var EditorUI = class {
         };
       }
     });
+    this.keyframePanel = new KeyframePanel(this.preview, editor, locale);
+    this.keyframeOverlay = new KeyframeOverlay(this.preview, editor);
     this.attachKeyboard(cb);
   }
   // ---- fullscreen -----------------------------------------------------
@@ -2907,6 +4144,13 @@ var EditorUI = class {
     const selectedClipId = this.editor.getSelection();
     const pxPerSec = this.editor.getScale();
     const snap = this.editor.getSnap();
+    const kfEnabled = this.editor.isKeyframesEnabled();
+    const kfState = this.computeKeyframeToolbarState(
+      project,
+      selectedClipId,
+      time,
+      kfEnabled
+    );
     this.toolbar.render({
       playing: this.editor.isPlaying(),
       time,
@@ -2915,18 +4159,34 @@ var EditorUI = class {
       canRedo: this.editor.canRedo(),
       canSplit: this.canSplitAt(time),
       canTrim: this.canTrimAt(time, selectedClipId),
+      canSeekClipEdge: selectedClipId != null,
+      clipEdgeNavEnabled: this.editor.isClipEdgeNavEnabled(),
       snap,
-      pxPerSec
+      pxPerSec,
+      ...kfState
     });
     this.timeline.setProject(project);
     this.timeline.setTime(time);
     this.timeline.setScale(pxPerSec);
     this.timeline.setSelection(selectedClipId);
     this.timeline.setSnap(snap);
+    this.timeline.setKeyframeState({
+      enabled: this.editor.isKeyframesEnabled(),
+      selected: this.editor.getSelectedKeyframe()
+    });
+    this.keyframePanel.render();
   }
   /** Playback-fast path: nudge playhead + toolbar time label only. */
   onTimeTick(timeMs) {
     this.timeline.setTime(timeMs);
+    const selectedClipId = this.editor.getSelection();
+    const kfEnabled = this.editor.isKeyframesEnabled();
+    const kfState = this.computeKeyframeToolbarState(
+      this.editor.getProject(),
+      selectedClipId,
+      timeMs,
+      kfEnabled
+    );
     this.toolbar.render({
       playing: this.editor.isPlaying(),
       time: timeMs,
@@ -2934,9 +4194,12 @@ var EditorUI = class {
       canUndo: this.editor.canUndo(),
       canRedo: this.editor.canRedo(),
       canSplit: this.canSplitAt(timeMs),
-      canTrim: this.canTrimAt(timeMs, this.editor.getSelection()),
+      canTrim: this.canTrimAt(timeMs, selectedClipId),
+      canSeekClipEdge: selectedClipId != null,
+      clipEdgeNavEnabled: this.editor.isClipEdgeNavEnabled(),
       snap: this.editor.getSnap(),
-      pxPerSec: this.editor.getScale()
+      pxPerSec: this.editor.getScale(),
+      ...kfState
     });
   }
   /** Explicit re-fit — Editor calls this when a brand-new project replaces the current one. */
@@ -2948,6 +4211,7 @@ var EditorUI = class {
     this.fullscreenExitBtn.title = locale.exitFullscreenTitle;
     this.fullscreenExitBtn.textContent = locale.exitFullscreen;
     this.timeline.setLocale(locale);
+    this.keyframePanel.setLocale(locale);
     this.render();
   }
   destroy() {
@@ -2957,10 +4221,56 @@ var EditorUI = class {
     }
     this.toolbar.destroy();
     this.timeline.destroy();
+    this.keyframePanel.destroy();
+    this.keyframeOverlay.destroy();
     this.root.innerHTML = "";
     this.root.classList.remove("aicut-root", "aicut-fullscreen");
   }
   // ---- helpers --------------------------------------------------------
+  /** Walk the selected clip + playhead state to figure out (a) whether
+   *  the keyframe button should be enabled, and (b) whether a keyframe
+   *  already exists at the playhead's clip-local time (so the button
+   *  swaps to "remove" mode). */
+  computeKeyframeToolbarState(project, selectedClipId, time, keyframesEnabled) {
+    if (!keyframesEnabled || !selectedClipId) {
+      return {
+        canKeyframe: false,
+        hasKeyframeAtPlayhead: false,
+        keyframesEnabled
+      };
+    }
+    let clip = null;
+    for (const t of project.tracks) {
+      const c = t.clips.find((cl) => cl.id === selectedClipId);
+      if (c) {
+        clip = c;
+        break;
+      }
+    }
+    if (!clip) {
+      return {
+        canKeyframe: false,
+        hasKeyframeAtPlayhead: false,
+        keyframesEnabled
+      };
+    }
+    const localMs = time - clip.start;
+    const duration = clipDuration(clip);
+    if (localMs < 0 || localMs > duration) {
+      return {
+        canKeyframe: false,
+        hasKeyframeAtPlayhead: false,
+        keyframesEnabled
+      };
+    }
+    const roundedLocal = Math.round(localMs);
+    const hasKf = clip.keyframes?.some((k) => k.time === roundedLocal) ?? false;
+    return {
+      canKeyframe: true,
+      hasKeyframeAtPlayhead: hasKf,
+      keyframesEnabled
+    };
+  }
   canSplitAt(timeMs) {
     const project = this.editor.getProject();
     for (const t of project.tracks) {
@@ -3002,6 +4312,22 @@ var EditorUI = class {
       } else if (e.code === "KeyW") {
         e.preventDefault();
         cb.onTrimRight();
+      } else if (e.code === "KeyI" && this.editor.isClipEdgeNavEnabled()) {
+        e.preventDefault();
+        cb.onSeekClipStart();
+      } else if (e.code === "KeyO" && this.editor.isClipEdgeNavEnabled()) {
+        e.preventDefault();
+        cb.onSeekClipEnd();
+      } else if (e.code === "ArrowLeft" || e.code === "ArrowRight") {
+        e.preventDefault();
+        const project = this.editor.getProject();
+        const step = e.shiftKey ? bigFrameStepMs(project) : frameStepMs(project);
+        const dir = e.code === "ArrowLeft" ? -1 : 1;
+        const next = Math.max(
+          0,
+          Math.min(this.editor.getDuration(), this.editor.getTime() + dir * step)
+        );
+        cb.onSeek(next);
       } else if ((e.metaKey || e.ctrlKey) && e.code === "KeyZ") {
         e.preventDefault();
         if (e.shiftKey) cb.onRedo();
@@ -3030,6 +4356,13 @@ var Editor = class _Editor {
   bus = new EventBus();
   history = new HistoryStack();
   selectedClipId = null;
+  selectedKeyframe = null;
+  keyframesEnabled;
+  clipEdgeNavEnabled;
+  /** Drag-session bookkeeping for ripple-merge undo. See
+   *  beginInteraction / endInteraction docs on EditorApi. */
+  interactionDepth = 0;
+  interactionStartSnapshot = null;
   pxPerSec;
   snap;
   locale;
@@ -3040,6 +4373,8 @@ var Editor = class _Editor {
     this.pxPerSec = clampScale2(opts.initialScale ?? DEFAULT_PX_PER_SEC);
     this.snap = opts.initialSnap !== false;
     this.locale = mergeLocale(opts.locale);
+    this.keyframesEnabled = opts.keyframes?.enabled === true;
+    this.clipEdgeNavEnabled = opts.clipEdgeNav?.enabled === true;
     if (opts.trackHeight != null || opts.rulerHeight != null) {
       setTimelineMetrics({
         ...opts.trackHeight != null ? { trackHeight: opts.trackHeight } : {},
@@ -3068,7 +4403,12 @@ var Editor = class _Editor {
       onSelectClip: (id) => this.setSelection(id),
       onDeleteClip: (id) => this.removeClip(id),
       onMoveClip: (id, opts2) => this.moveClip(id, opts2),
-      onResizeClip: (id, edits) => this.resizeClip(id, edits)
+      onResizeClip: (id, edits) => this.resizeClip(id, edits),
+      onSelectKeyframe: (target) => this.setSelectedKeyframe(target),
+      onMoveKeyframe: (clipId, keyframeId, timeMs) => this.moveKeyframe(clipId, keyframeId, timeMs),
+      onKeyframeToggle: () => this.toggleKeyframeAtPlayhead(),
+      onSeekClipStart: () => this.seekToSelectedClipEdge("start"),
+      onSeekClipEnd: () => this.seekToSelectedClipEdge("end")
     });
     const engineFactory = opts.playbackEngine ?? ((o) => new HtmlVideoEngine(o));
     this.engine = engineFactory({
@@ -3492,6 +4832,9 @@ var Editor = class _Editor {
       for (const c of t.clips) {
         if (c.id === ignoreClipId) continue;
         targets.push(c.start, clipEnd(c));
+        if (c.keyframes) {
+          for (const kf of c.keyframes) targets.push(c.start + kf.time);
+        }
       }
     }
     let best = timeMs;
@@ -3513,6 +4856,304 @@ var Editor = class _Editor {
     if (clipId === this.selectedClipId) return;
     this.selectedClipId = clipId;
     this.bus.emit("selectionChange", { clipId });
+    if (this.selectedKeyframe && this.selectedKeyframe.clipId !== clipId) {
+      this.selectedKeyframe = null;
+      this.bus.emit("keyframeSelectionChange", { target: null });
+    }
+    this.ui.render();
+  }
+  // ---- keyframes ------------------------------------------------------
+  isKeyframesEnabled() {
+    return this.keyframesEnabled;
+  }
+  /**
+   * Screen-space CSS-pixel rect of the actively painted frame
+   * (post-transform), relative to the editor's preview element.
+   * Null when no clip is active, the engine doesn't expose
+   * `getFrameRect`, or the rect isn't computed yet. Used by the
+   * library's keyframe-editing overlay.
+   */
+  getActiveFrameRect() {
+    return this.engine.getFrameRect?.() ?? null;
+  }
+  /**
+   * Screen-space CSS-pixel rect of the OUTPUT FRAME (the fixed
+   * stage that clips the rendered video). Different from
+   * `getActiveFrameRect` which includes the keyframe transform —
+   * this one stays put as the user drags / scales the content.
+   * Used by the overlay to anchor the dashed border + drag body.
+   */
+  getActiveOutputFrameRect() {
+    return this.engine.getOutputFrameRect?.() ?? null;
+  }
+  setKeyframesEnabled(enabled) {
+    if (enabled === this.keyframesEnabled) return;
+    this.keyframesEnabled = enabled;
+    if (!enabled && this.selectedKeyframe) {
+      this.selectedKeyframe = null;
+      this.bus.emit("keyframeSelectionChange", { target: null });
+    }
+    this.bus.emit("keyframesEnabledChange", { enabled });
+    this.ui.render();
+  }
+  isClipEdgeNavEnabled() {
+    return this.clipEdgeNavEnabled;
+  }
+  setClipEdgeNavEnabled(enabled) {
+    if (enabled === this.clipEdgeNavEnabled) return;
+    this.clipEdgeNavEnabled = enabled;
+    this.bus.emit("clipEdgeNavEnabledChange", { enabled });
+    this.ui.render();
+  }
+  addKeyframe(clipId, prop, opts = {}) {
+    const trk = findTrackOfClip(this.project, clipId);
+    const cl = trk?.clips.find((c) => c.id === clipId);
+    if (!trk || !cl) return null;
+    const duration = clipDuration(cl);
+    const playheadLocal = this.engine.getTime() - cl.start;
+    const rawTime = opts.time ?? playheadLocal;
+    const time = Math.max(0, Math.min(duration, Math.round(rawTime)));
+    const value = opts.value ?? interpolateProp(cl, prop, time);
+    this.pushHistory();
+    cl.keyframes = upsertKeyframe(
+      cl.keyframes,
+      prop,
+      time,
+      value,
+      () => createId("kf")
+    );
+    cl.keyframes.sort((a, b) => {
+      if (a.prop !== b.prop) return a.prop.localeCompare(b.prop);
+      return a.time - b.time;
+    });
+    this.afterMutation();
+    const created = cl.keyframes.find(
+      (k) => k.prop === prop && Math.abs(k.time - time) < 16
+    );
+    return created?.id ?? null;
+  }
+  removeKeyframe(clipId, keyframeId) {
+    const trk = findTrackOfClip(this.project, clipId);
+    const cl = trk?.clips.find((c) => c.id === clipId);
+    if (!trk || !cl || !cl.keyframes) return false;
+    const idx = cl.keyframes.findIndex((k) => k.id === keyframeId);
+    if (idx < 0) return false;
+    this.pushHistory();
+    const next = cl.keyframes.slice();
+    next.splice(idx, 1);
+    cl.keyframes = next.length > 0 ? next : void 0;
+    if (this.selectedKeyframe && this.selectedKeyframe.clipId === clipId && this.selectedKeyframe.keyframeId === keyframeId) {
+      this.selectedKeyframe = null;
+      this.bus.emit("keyframeSelectionChange", { target: null });
+    }
+    this.afterMutation();
+    return true;
+  }
+  moveKeyframe(clipId, keyframeId, timeMs) {
+    const trk = findTrackOfClip(this.project, clipId);
+    const cl = trk?.clips.find((c) => c.id === clipId);
+    const kf = cl?.keyframes?.find((k) => k.id === keyframeId);
+    if (!trk || !cl || !kf || !cl.keyframes) return false;
+    const duration = clipDuration(cl);
+    const clamped = Math.max(0, Math.min(duration, Math.round(timeMs)));
+    if (clamped === kf.time) return false;
+    if (cl.keyframes.some(
+      (k) => k.id !== keyframeId && k.prop === kf.prop && k.time === clamped
+    )) {
+      return false;
+    }
+    this.pushHistory();
+    kf.time = clamped;
+    cl.keyframes.sort((a, b) => {
+      if (a.prop !== b.prop) return a.prop.localeCompare(b.prop);
+      return a.time - b.time;
+    });
+    this.afterMutation();
+    return true;
+  }
+  setKeyframeValue(clipId, keyframeId, value) {
+    const trk = findTrackOfClip(this.project, clipId);
+    const cl = trk?.clips.find((c) => c.id === clipId);
+    const kf = cl?.keyframes?.find((k) => k.id === keyframeId);
+    if (!trk || !cl || !kf) return false;
+    if (Math.abs(kf.value - value) < 1e-9) return false;
+    this.pushHistory();
+    kf.value = value;
+    this.afterMutation();
+    return true;
+  }
+  setKeyframeEasing(clipId, keyframeId, easing) {
+    const trk = findTrackOfClip(this.project, clipId);
+    const cl = trk?.clips.find((c) => c.id === clipId);
+    const kf = cl?.keyframes?.find((k) => k.id === keyframeId);
+    if (!trk || !cl || !kf) return false;
+    const current = kf.easing ?? "linear";
+    if (current === easing) return false;
+    this.pushHistory();
+    if (easing === "linear") {
+      delete kf.easing;
+    } else {
+      kf.easing = easing;
+    }
+    this.afterMutation();
+    return true;
+  }
+  setKeyframesEasingAtTime(clipId, timeMs, easing) {
+    const trk = findTrackOfClip(this.project, clipId);
+    const cl = trk?.clips.find((c) => c.id === clipId);
+    if (!trk || !cl || !cl.keyframes) return false;
+    const t = Math.round(timeMs);
+    const matches = cl.keyframes.filter((k) => Math.abs(k.time - t) < 16);
+    if (matches.length === 0) return false;
+    const anyChange = matches.some((k) => (k.easing ?? "linear") !== easing);
+    if (!anyChange) return false;
+    this.pushHistory();
+    for (const kf of matches) {
+      if (easing === "linear") delete kf.easing;
+      else kf.easing = easing;
+    }
+    this.afterMutation();
+    return true;
+  }
+  setValueAtPlayhead(clipId, prop, value) {
+    const trk = findTrackOfClip(this.project, clipId);
+    const cl = trk?.clips.find((c) => c.id === clipId);
+    if (!trk || !cl) return false;
+    const duration = clipDuration(cl);
+    const playheadLocal = this.engine.getTime() - cl.start;
+    const time = Math.max(0, Math.min(duration, Math.round(playheadLocal)));
+    const hasKf = cl.keyframes?.some((k) => k.prop === prop) ?? false;
+    if (hasKf) {
+      this.pushHistory();
+      cl.keyframes = upsertKeyframe(
+        cl.keyframes,
+        prop,
+        time,
+        value,
+        () => createId("kf")
+      );
+      cl.keyframes.sort((a, b) => {
+        if (a.prop !== b.prop) return a.prop.localeCompare(b.prop);
+        return a.time - b.time;
+      });
+      this.afterMutation();
+      return true;
+    }
+    if ((cl[prop] ?? (prop === "scale" ? 1 : 0)) === value) return false;
+    this.pushHistory();
+    cl[prop] = value;
+    this.afterMutation();
+    return true;
+  }
+  getSelectedKeyframe() {
+    return this.selectedKeyframe;
+  }
+  resetClipTransform(clipId) {
+    const trk = findTrackOfClip(this.project, clipId);
+    const cl = trk?.clips.find((c) => c.id === clipId);
+    if (!trk || !cl) return false;
+    const dirty = cl.keyframes && cl.keyframes.length > 0 || cl.panX !== void 0 || cl.panY !== void 0 || cl.scale !== void 0;
+    if (!dirty) return false;
+    this.pushHistory();
+    delete cl.panX;
+    delete cl.panY;
+    delete cl.scale;
+    cl.keyframes = void 0;
+    if (this.selectedKeyframe && this.selectedKeyframe.clipId === clipId) {
+      this.selectedKeyframe = null;
+      this.bus.emit("keyframeSelectionChange", { target: null });
+    }
+    this.afterMutation();
+    return true;
+  }
+  resetKeyframesAtTime(clipId, timeMs) {
+    const trk = findTrackOfClip(this.project, clipId);
+    const cl = trk?.clips.find((c) => c.id === clipId);
+    if (!trk || !cl) return false;
+    const duration = clipDuration(cl);
+    const t = Math.max(0, Math.min(duration, Math.round(timeMs)));
+    this.pushHistory();
+    let kfs = cl.keyframes ?? [];
+    kfs = upsertKeyframe(kfs, "panX", t, 0, () => createId("kf"));
+    kfs = upsertKeyframe(kfs, "panY", t, 0, () => createId("kf"));
+    kfs = upsertKeyframe(kfs, "scale", t, 1, () => createId("kf"));
+    kfs.sort((a, b) => {
+      if (a.prop !== b.prop) return a.prop.localeCompare(b.prop);
+      return a.time - b.time;
+    });
+    cl.keyframes = kfs;
+    this.afterMutation();
+    return true;
+  }
+  seekToClipEdge(clipId, edge) {
+    const trk = findTrackOfClip(this.project, clipId);
+    const cl = trk?.clips.find((c) => c.id === clipId);
+    if (!trk || !cl) return false;
+    const target = edge === "start" ? cl.start : Math.max(cl.start, clipEnd(cl) - 1);
+    if (this.engine.getTime() === target) return false;
+    this.seek(target);
+    return true;
+  }
+  seekToSelectedClipEdge(edge) {
+    if (!this.selectedClipId) return false;
+    return this.seekToClipEdge(this.selectedClipId, edge);
+  }
+  toggleKeyframeAtPlayhead() {
+    const clipId = this.selectedClipId;
+    if (!clipId) return false;
+    const trk = findTrackOfClip(this.project, clipId);
+    const cl = trk?.clips.find((c) => c.id === clipId);
+    if (!trk || !cl) return false;
+    const localMs = this.engine.getTime() - cl.start;
+    const duration = clipDuration(cl);
+    if (localMs < 0 || localMs > duration) return false;
+    const t = Math.round(localMs);
+    const existing = cl.keyframes?.filter((k) => Math.abs(k.time - t) < 16);
+    if (existing && existing.length > 0) {
+      this.pushHistory();
+      const ids = new Set(existing.map((k) => k.id));
+      const next = cl.keyframes.filter((k) => !ids.has(k.id));
+      cl.keyframes = next.length > 0 ? next : void 0;
+      if (this.selectedKeyframe && ids.has(this.selectedKeyframe.keyframeId)) {
+        this.selectedKeyframe = null;
+        this.bus.emit("keyframeSelectionChange", { target: null });
+      }
+      this.afterMutation();
+      return true;
+    }
+    const current = getEffectiveTransform(cl, t);
+    this.pushHistory();
+    let kfs = cl.keyframes ?? [];
+    kfs = upsertKeyframe(kfs, "panX", t, current.panX, () => createId("kf"));
+    kfs = upsertKeyframe(kfs, "panY", t, current.panY, () => createId("kf"));
+    kfs = upsertKeyframe(kfs, "scale", t, current.scale, () => createId("kf"));
+    kfs.sort((a, b) => {
+      if (a.prop !== b.prop) return a.prop.localeCompare(b.prop);
+      return a.time - b.time;
+    });
+    cl.keyframes = kfs;
+    const anchor = kfs.find(
+      (k) => k.prop === "panX" && Math.abs(k.time - t) < 16
+    );
+    if (anchor) {
+      this.selectedKeyframe = { clipId, keyframeId: anchor.id };
+      this.bus.emit("keyframeSelectionChange", {
+        target: this.selectedKeyframe
+      });
+    }
+    this.afterMutation();
+    return true;
+  }
+  setSelectedKeyframe(target) {
+    if (target?.clipId === this.selectedKeyframe?.clipId && target?.keyframeId === this.selectedKeyframe?.keyframeId) {
+      return;
+    }
+    this.selectedKeyframe = target;
+    if (target && target.clipId !== this.selectedClipId) {
+      this.selectedClipId = target.clipId;
+      this.bus.emit("selectionChange", { clipId: target.clipId });
+    }
+    this.bus.emit("keyframeSelectionChange", { target });
     this.ui.render();
   }
   // ---- history --------------------------------------------------------
@@ -3526,6 +5167,7 @@ var Editor = class _Editor {
     const prev = this.history.undo(this.project);
     if (!prev) return false;
     this.project = prev;
+    this.reconcileSelectionsWithProject();
     this.engine.setProject(this.project);
     this.bus.emit("change", { project: this.getProject() });
     this.emitHistory();
@@ -3536,12 +5178,57 @@ var Editor = class _Editor {
     const next = this.history.redo(this.project);
     if (!next) return false;
     this.project = next;
+    this.reconcileSelectionsWithProject();
     this.engine.setProject(this.project);
     this.bus.emit("change", { project: this.getProject() });
     this.emitHistory();
     this.ui.render();
     return true;
   }
+  beginInteraction() {
+    this.interactionDepth += 1;
+  }
+  endInteraction() {
+    if (this.interactionDepth === 0) return;
+    this.interactionDepth -= 1;
+    if (this.interactionDepth > 0) return;
+    const snapshot = this.interactionStartSnapshot;
+    this.interactionStartSnapshot = null;
+    if (snapshot == null) return;
+    const now = JSON.stringify(this.project);
+    if (now === snapshot) return;
+    this.history.push(JSON.parse(snapshot));
+    this.emitHistory();
+  }
+  /**
+   * Selections (clipId + selectedKeyframe) live OUTSIDE the project
+   * snapshot, so undo / redo can leave them pointing at ids that no
+   * longer exist. Defend against dangling refs by clearing anything
+   * the restored project doesn't actually contain — and emit the
+   * paired change events so panels / overlays hide cleanly instead
+   * of holding zombie references.
+   */
+  reconcileSelectionsWithProject() {
+    if (this.selectedKeyframe) {
+      const trk = findTrackOfClip(this.project, this.selectedKeyframe.clipId);
+      const cl = trk?.clips.find((c) => c.id === this.selectedKeyframe.clipId);
+      const kf = cl?.keyframes?.find(
+        (k) => k.id === this.selectedKeyframe.keyframeId
+      );
+      if (!kf) {
+        this.selectedKeyframe = null;
+        this.bus.emit("keyframeSelectionChange", { target: null });
+      }
+    }
+    if (this.selectedClipId) {
+      const trk = findTrackOfClip(this.project, this.selectedClipId);
+      const cl = trk?.clips.find((c) => c.id === this.selectedClipId);
+      if (!cl) {
+        this.selectedClipId = null;
+        this.bus.emit("selectionChange", { clipId: null });
+      }
+    }
+  }
   // ---- events ---------------------------------------------------------
   on(event, handler) {
     return this.bus.on(event, handler);
@@ -3578,6 +5265,12 @@ var Editor = class _Editor {
     return null;
   }
   pushHistory() {
+    if (this.interactionDepth > 0) {
+      if (this.interactionStartSnapshot == null) {
+        this.interactionStartSnapshot = JSON.stringify(this.project);
+      }
+      return;
+    }
     this.history.push(this.project);
     this.emitHistory();
   }