@aicut/core 0.5.0 → 0.6.0

package/dist/index.cjs

@@ -80,7 +80,110 @@ function createId(prefix = "id") {
   return `${prefix}_${t}${rand}`;
 }
 
+// src/keyframes/types.ts
+var IDENTITY_TRANSFORM = {
+  panX: 0,
+  panY: 0,
+  scale: 1
+};
+function isIdentityTransform(t) {
+  return Math.abs(t.panX) < 1e-3 && Math.abs(t.panY) < 1e-3 && Math.abs(t.scale - 1) < 1e-4;
+}
+
+// src/keyframes/interpolate.ts
+function applyEasing(t, easing) {
+  switch (easing) {
+    case "linear":
+      return t;
+    case "easeIn":
+      return t * t * t;
+    case "easeOut": {
+      const u = 1 - t;
+      return 1 - u * u * u;
+    }
+    case "easeInOut":
+      return t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
+  }
+}
+function defaultFor(prop) {
+  return prop === "scale" ? 1 : 0;
+}
+function staticValue(clip, prop) {
+  const v = clip[prop];
+  return v ?? defaultFor(prop);
+}
+function keyframesForProp(kfs, prop) {
+  const out = [];
+  for (const k of kfs) if (k.prop === prop) out.push(k);
+  out.sort((a, b) => a.time - b.time);
+  return out;
+}
+function hasKeyframesForProp(clip, prop) {
+  return clip.keyframes?.some((k) => k.prop === prop) ?? false;
+}
+function interpolateProp(clip, prop, localMs) {
+  if (!clip.keyframes || clip.keyframes.length === 0) {
+    return staticValue(clip, prop);
+  }
+  const arr = keyframesForProp(clip.keyframes, prop);
+  if (arr.length === 0) return staticValue(clip, prop);
+  if (arr.length === 1) return arr[0].value;
+  const first = arr[0];
+  const last = arr[arr.length - 1];
+  if (localMs <= first.time) return first.value;
+  if (localMs >= last.time) return last.value;
+  for (let i = 0; i < arr.length - 1; i += 1) {
+    const a = arr[i];
+    const b = arr[i + 1];
+    if (localMs >= a.time && localMs <= b.time) {
+      if (b.time === a.time) return a.value;
+      const rawT = (localMs - a.time) / (b.time - a.time);
+      const eased = applyEasing(rawT, a.easing ?? "linear");
+      return a.value + (b.value - a.value) * eased;
+    }
+  }
+  return last.value;
+}
+function getEffectiveTransform(clip, localMs) {
+  if ((!clip.keyframes || clip.keyframes.length === 0) && clip.panX === void 0 && clip.panY === void 0 && clip.scale === void 0) {
+    return IDENTITY_TRANSFORM;
+  }
+  return {
+    panX: interpolateProp(clip, "panX", localMs),
+    panY: interpolateProp(clip, "panY", localMs),
+    scale: interpolateProp(clip, "scale", localMs)
+  };
+}
+function getTransformAtTimelineTime(clip, timelineMs) {
+  return getEffectiveTransform(clip, timelineMs - clip.start);
+}
+function upsertKeyframe(kfs, prop, time, value, idFactory) {
+  const existing = kfs ?? [];
+  const idx = existing.findIndex(
+    (k) => k.prop === prop && Math.abs(k.time - time) < 16
+  );
+  if (idx >= 0) {
+    const next = existing.slice();
+    next[idx] = { ...next[idx], value };
+    return next;
+  }
+  return [...existing, { id: idFactory(), prop, time, value }];
+}
+
 // 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,
@@ -117,11 +220,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;
@@ -132,6 +282,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) {
@@ -151,6 +342,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) {
     exports.TRACK_HEIGHT = Math.round(opts.trackHeight);
@@ -186,8 +382,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;
@@ -215,6 +413,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;
@@ -265,13 +466,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;
@@ -283,8 +487,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;
@@ -307,9 +518,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();
   }
@@ -320,8 +531,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();
       }
     }
   }
@@ -348,41 +558,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",
@@ -395,8 +701,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) {
@@ -404,25 +711,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) {
@@ -434,10 +741,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) {
@@ -506,8 +810,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?.();
@@ -516,8 +820,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);
   }
@@ -540,6 +844,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;
@@ -824,19 +1132,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);
@@ -878,12 +1222,11 @@ function applyTheme(root, theme) {
 
 // src/i18n.ts
 var localeEn = {
-  undo: "Undo",
-  redo: "Redo",
-  split: "Split",
-  trimLeft: "Trim left edge",
-  trimRight: "Trim right edge",
-  speedComingSoon: "Speed (coming soon)",
+  undo: "Undo (\u2318Z)",
+  redo: "Redo (\u21E7\u2318Z)",
+  split: "Split (K)",
+  trimLeft: "Trim left edge (Q)",
+  trimRight: "Trim right edge (W)",
   playPause: "Play / Pause (Space)",
   fullscreen: "Fullscreen preview",
   snap: "Snap",
@@ -892,6 +1235,25 @@ var localeEn = {
   zoomOut: "Zoom out",
   zoomIn: "Zoom in",
   reset: "Reset edits (keep sources)",
+  keyframeAdd: "Add keyframe at playhead",
+  keyframeRemove: "Remove keyframe at playhead",
+  seekClipStart: "Jump to clip start (I)",
+  seekClipEnd: "Jump to clip end (O)",
+  keyframePanelTitle: "Keyframe",
+  keyframePanelLabelX: "X",
+  keyframePanelLabelY: "Y",
+  keyframePanelLabelScale: "Scale",
+  keyframePanelLabelEasing: "Easing",
+  keyframePanelReset: "Reset to 0 0 1",
+  keyframePanelResetTitle: "Pin this keyframe to identity (panX=0, panY=0, scale=1)",
+  keyframePanelBadgePinned: "Pinned at this moment",
+  keyframePanelBadgeAnimated: "Animated \u2014 but not pinned at this exact moment",
+  keyframePanelBadgeStatic: "Static value",
+  keyframePanelTimeSuffix: "s",
+  keyframeEasingLinear: "Linear",
+  keyframeEasingEaseIn: "Ease in",
+  keyframeEasingEaseOut: "Ease out",
+  keyframeEasingEaseInOut: "Ease in-out",
   exitFullscreen: "Exit fullscreen",
   exitFullscreenTitle: "Exit fullscreen (Esc)",
   newTrack: "+ New track",
@@ -899,12 +1261,11 @@ var localeEn = {
   audioTrackLabel: "Audio {n}"
 };
 var localeZh = {
-  undo: "\u64A4\u9500",
-  redo: "\u91CD\u505A",
-  split: "\u5206\u5272",
-  trimLeft: "\u5411\u5DE6\u88C1\u526A",
-  trimRight: "\u5411\u53F3\u88C1\u526A",
-  speedComingSoon: "\u53D8\u901F\uFF08\u5373\u5C06\u5230\u6765\uFF09",
+  undo: "\u64A4\u9500 (\u2318Z)",
+  redo: "\u91CD\u505A (\u21E7\u2318Z)",
+  split: "\u5206\u5272 (K)",
+  trimLeft: "\u5411\u5DE6\u88C1\u526A (Q)",
+  trimRight: "\u5411\u53F3\u88C1\u526A (W)",
   playPause: "\u64AD\u653E / \u6682\u505C (Space)",
   fullscreen: "\u5168\u5C4F\u9884\u89C8",
   snap: "\u5438\u9644",
@@ -913,6 +1274,25 @@ var localeZh = {
   zoomOut: "\u7F29\u5C0F",
   zoomIn: "\u653E\u5927",
   reset: "\u91CD\u7F6E\u7F16\u8F91\uFF08\u4FDD\u7559\u89C6\u9891\u6E90\uFF09",
+  keyframeAdd: "\u6DFB\u52A0\u5173\u952E\u5E27",
+  keyframeRemove: "\u5220\u9664\u5F53\u524D\u5173\u952E\u5E27",
+  seekClipStart: "\u8DF3\u5230\u7247\u6BB5\u8D77\u70B9 (I)",
+  seekClipEnd: "\u8DF3\u5230\u7247\u6BB5\u672B\u5C3E (O)",
+  keyframePanelTitle: "\u5173\u952E\u5E27",
+  keyframePanelLabelX: "X \u4F4D\u79FB",
+  keyframePanelLabelY: "Y \u4F4D\u79FB",
+  keyframePanelLabelScale: "\u7F29\u653E",
+  keyframePanelLabelEasing: "\u7F13\u52A8",
+  keyframePanelReset: "\u91CD\u7F6E\u4E3A 0 0 1",
+  keyframePanelResetTitle: "\u5C06\u8BE5\u5173\u952E\u5E27\u91CD\u7F6E\u4E3A\u521D\u59CB\u59FF\u6001\uFF08panX=0, panY=0, scale=1\uFF09",
+  keyframePanelBadgePinned: "\u5DF2\u5728\u8BE5\u65F6\u523B\u56FA\u5B9A",
+  keyframePanelBadgeAnimated: "\u6574\u6BB5\u6709\u52A8\u753B\uFF0C\u4F46\u5F53\u524D\u65F6\u523B\u6CA1\u6709\u9501\u70B9",
+  keyframePanelBadgeStatic: "\u672A\u52A8\u753B\uFF08\u6CBF\u7528\u9759\u6001\u503C\uFF09",
+  keyframePanelTimeSuffix: "\u79D2",
+  keyframeEasingLinear: "\u7EBF\u6027",
+  keyframeEasingEaseIn: "\u7F13\u5165",
+  keyframeEasingEaseOut: "\u7F13\u51FA",
+  keyframeEasingEaseInOut: "\u7F13\u5165\u7F13\u51FA",
   exitFullscreen: "\u9000\u51FA\u5168\u5C4F",
   exitFullscreenTitle: "\u9000\u51FA\u5168\u5C4F (Esc)",
   newTrack: "+ \u65B0\u8F68\u9053",
@@ -1106,7 +1486,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 - exports.RULER_HEIGHT - SCROLLBAR_THICKNESS;
   ctx.save();
@@ -1146,15 +1526,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 - exports.RULER_HEIGHT - SCROLLBAR_THICKNESS;
   for (const [s, e] of gaps) {
     const x1 = Math.max(
@@ -1193,7 +1579,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;
@@ -1263,7 +1649,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, exports.RULER_HEIGHT);
@@ -1309,7 +1695,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, exports.TRACK_HEIGHT);
@@ -1347,7 +1733,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;
@@ -1396,6 +1782,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) {
@@ -1446,7 +1860,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;
@@ -1460,7 +1874,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);
@@ -1516,7 +1932,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;
@@ -1599,11 +2015,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 - exports.RULER_HEIGHT - SCROLLBAR_THICKNESS;
   const contentH = contentHeight(ctx.project.tracks, ctx.isDragging);
   if (contentH > visibleH && x >= ctx.viewportWidth - SCROLLBAR_THICKNESS && x < ctx.viewportWidth && y >= exports.RULER_HEIGHT && y < ctx.viewportHeight - SCROLLBAR_THICKNESS) {
@@ -1655,6 +2085,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);
@@ -1673,8 +2120,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
@@ -1708,6 +2154,8 @@ var Timeline = class _Timeline {
   readOnly;
   autoFitEnabled;
   locale;
+  keyframesEnabled = false;
+  selectedKeyframe = null;
   scrollLeft = 0;
   scrollTop = 0;
   viewportWidth = 0;
@@ -1726,6 +2174,7 @@ var Timeline = class _Timeline {
   scrollbarDrag = null;
   hoveredClipId = null;
   hoveredTrackIndex = null;
+  hoveredKeyframe = null;
   hoverCursor = "default";
   dropTargetTrackIndex = null;
   snapX = null;
@@ -1764,6 +2213,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";
@@ -1811,6 +2262,7 @@ var Timeline = class _Timeline {
     this.thumbs.syncSources(this.project.sources);
     this.attachPointer();
     this.attachWheel();
+    this.attachKeyboard();
     this.attachResize();
     this.resizeCanvas();
     this.scheduleRender();
@@ -1891,7 +2343,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];
@@ -1944,17 +2396,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 - exports.RULER_HEIGHT - SCROLLBAR_THICKNESS;
@@ -2056,9 +2508,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;
@@ -2087,6 +2566,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;
@@ -2127,7 +2607,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
@@ -2167,6 +2647,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;
@@ -2233,7 +2740,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;
@@ -2257,10 +2764,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;
@@ -2284,12 +2800,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;
@@ -2312,6 +2830,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;
@@ -2464,6 +3002,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) {
@@ -2477,6 +3023,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",
@@ -2497,7 +3062,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");
@@ -2560,7 +3125,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) {
@@ -2583,7 +3149,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;
@@ -2592,6 +3158,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 = {
@@ -2635,6 +3904,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>`
 };
@@ -2661,6 +3948,9 @@ var Toolbar = class {
   splitBtn;
   trimLeftBtn;
   trimRightBtn;
+  seekClipStartBtn;
+  seekClipEndBtn;
+  keyframeBtn;
   playBtn;
   playIcon;
   timeLabel;
@@ -2686,9 +3976,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");
@@ -2765,11 +4083,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));
@@ -2802,12 +4147,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;
     }
@@ -2867,6 +4220,8 @@ var EditorUI = class {
   toolbar;
   timelineHost;
   timeline;
+  keyframePanel;
+  keyframeOverlay;
   fullscreen = false;
   onDocKeydown = null;
   constructor(root, editor, cb) {
@@ -2913,10 +4268,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
@@ -2941,6 +4300,8 @@ var EditorUI = class {
         };
       }
     });
+    this.keyframePanel = new KeyframePanel(this.preview, editor, locale);
+    this.keyframeOverlay = new KeyframeOverlay(this.preview, editor);
     this.attachKeyboard(cb);
   }
   // ---- fullscreen -----------------------------------------------------
@@ -2990,6 +4351,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,
@@ -2998,18 +4366,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,
@@ -3017,9 +4401,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. */
@@ -3031,6 +4418,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() {
@@ -3040,10 +4428,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) {
@@ -3085,6 +4519,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();
@@ -3113,6 +4563,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;
@@ -3123,6 +4580,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 } : {},
@@ -3151,7 +4610,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({
@@ -3575,6 +5039,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;
@@ -3596,6 +5063,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 --------------------------------------------------------
@@ -3609,6 +5374,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();
@@ -3619,12 +5385,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);
@@ -3661,6 +5472,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();
   }
@@ -3706,12 +5523,16 @@ exports.CanvasCompositorEngine = CanvasCompositorEngine;
 exports.Editor = Editor;
 exports.HEADER_WIDTH = HEADER_WIDTH;
 exports.HtmlVideoEngine = HtmlVideoEngine;
+exports.IDENTITY_TRANSFORM = IDENTITY_TRANSFORM;
 exports.Timeline = Timeline;
 exports.canvasCompositorEngineFactory = canvasCompositorEngineFactory;
 exports.createEmptyProject = createEmptyProject;
 exports.createId = createId;
 exports.formatLabel = formatLabel;
+exports.getEffectiveTransform = getEffectiveTransform;
+exports.getTransformAtTimelineTime = getTransformAtTimelineTime;
 exports.htmlVideoEngineFactory = htmlVideoEngineFactory;
+exports.isIdentityTransform = isIdentityTransform;
 exports.localeEn = localeEn;
 exports.localeZh = localeZh;
 exports.mergeLocale = mergeLocale;