@aicut/core 0.5.0 → 0.6.0

package/dist/index.d.cts

@@ -1,33 +1,22 @@
-import { P as PlaybackEngine, a as PlaybackEngineOptions, b as PlaybackEngineFactory } from './types-DvKlxylu.cjs';
-import { M as Ms, P as Project, T as Track, C as Clip, a as MediaSource, b as Theme } from './types-CHplD9V5.cjs';
-import { L as Locale } from './i18n-B-DFWgKe.cjs';
-export { f as formatLabel, l as localeEn, a as localeZh, m as mergeLocale } from './i18n-B-DFWgKe.cjs';
+import { P as PlaybackEngine, a as PlaybackEngineOptions, b as PlaybackEngineFactory } from './types-CjvRUPtZ.cjs';
+import { M as Ms, P as Project, T as Track, C as Clip, a as MediaSource, b as Theme, K as KeyframeProp, E as EasingKind } from './types-CmS-UIEr.cjs';
+export { c as Keyframe } from './types-CmS-UIEr.cjs';
+import { L as Locale } from './i18n-B24k4XVG.cjs';
+export { f as formatLabel, l as localeEn, a as localeZh, m as mergeLocale } from './i18n-B24k4XVG.cjs';
 
-/**
- * Default preview engine — one hidden `<video>` per `MediaSource`,
- * "active" video shown for the current playhead. Tick loop drives a
- * single video track's playhead, advancing through clips end-to-end.
- * When the playhead crosses a clip boundary we pause the outgoing
- * video and resume the next at `clip.in`.
- *
- * Strengths: zero deps, browser-native decode (GPU when available),
- * works in every browser today.
- *
- * Limits: no multi-track compositing (one video visible at a time),
- * seek snaps to keyframes (browser controls the decode pipeline), no
- * transitions / shaders / filters. See `WebCodecsEngine` for the
- * frame-accurate path.
- */
 declare class HtmlVideoEngine implements PlaybackEngine {
     private host;
     private mount;
-    private videos;
+    private sources;
     private project;
     private currentClipId;
     private playing;
     private timeMs;
     private rafHandle;
     private lastFrameTs;
+    /** Permanent rAF that positions the active wrapper at the output
+     *  rect + pushes keyframe transform onto the inner video via CSS. */
+    private transformRaf;
     /** Public event hooks — set by Editor. */
     onTimeUpdate?: (ms: Ms) => void;
     onEnded?: () => void;
@@ -41,6 +30,37 @@ declare class HtmlVideoEngine implements PlaybackEngine {
     isPlaying(): boolean;
     getTime(): Ms;
     seek(timeMs: Ms): void;
+    /**
+     * 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(): {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | null;
+    /**
+     * 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(): {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | null;
+    /** Untransformed contain-letterbox rect — the OUTPUT frame. */
+    private baseFrameRect;
+    /**
+     * 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.
+     */
+    private startTransformLoop;
+    private applyTransforms;
     destroy(): void;
     private syncSources;
     private activate;
@@ -49,10 +69,7 @@ declare class HtmlVideoEngine implements PlaybackEngine {
     /**
      * 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.
      */
     private clipAtTime;
     /** Earliest clip starting at-or-after `timeMs` across all video tracks. */
@@ -107,6 +124,10 @@ declare class CanvasCompositorEngine implements PlaybackEngine {
     private rafHandle;
     private lastFrameTs;
     private paintedFrames;
+    /** Output frame rect (no transform) — fixed bounds. */
+    private lastOutputRect;
+    /** Post-transform content rect. */
+    private lastFrameRect;
     onTimeUpdate?: (ms: Ms) => void;
     onEnded?: () => void;
     onError?: (err: Error) => void;
@@ -138,6 +159,18 @@ declare class CanvasCompositorEngine implements PlaybackEngine {
      * and the seek preview both update when paused.
      */
     private paint;
+    getOutputFrameRect(): {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | null;
+    getFrameRect(): {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | null;
     private updateBadge;
 }
 /** Factory shorthand for `Editor.create({ playbackEngine })`. */
@@ -194,6 +227,31 @@ interface EditorOptions {
      * Reasonable range: [120, 480].
      */
     timelineHeight?: number;
+    /**
+     * Per-clip keyframe animation (X / Y / Scale). Off by default; flip
+     * `enabled: true` to surface keyframe markers on the timeline and
+     * route the canvas / WebCodecs engines through `getEffectiveTransform`
+     * when painting. Data is preserved either way — disabling just hides
+     * the editing UI and renders identity transforms.
+     *
+     * HtmlVideoEngine cannot apply per-frame transforms (it shows a raw
+     * `<video>`), so keyframes are silently ignored on that engine
+     * regardless of this flag. Swap to `CanvasCompositorEngine` or
+     * `WebCodecsEngine` for live preview.
+     */
+    keyframes?: {
+        enabled?: boolean;
+    };
+    /**
+     * Show the |◀ / ▶| "jump to clip start / end" toolbar buttons and
+     * bind the I / O keyboard shortcuts. Off by default — hosts opt in
+     * the same way they do for keyframes. When off the buttons are
+     * completely hidden (display: none) so they don't take up toolbar
+     * space, and the I / O keys fall through to the page.
+     */
+    clipEdgeNav?: {
+        enabled?: boolean;
+    };
 }
 interface EditorEventMap {
     /** Emitted whenever the project mutates. */
@@ -221,6 +279,23 @@ interface EditorEventMap {
     selectionChange: {
         clipId: string | null;
     };
+    /** Currently selected keyframe (parent clip + keyframe id), or null.
+     *  Selecting a keyframe also selects its parent clip — listeners
+     *  watching `selectionChange` get notified independently. */
+    keyframeSelectionChange: {
+        target: {
+            clipId: string;
+            keyframeId: string;
+        } | null;
+    };
+    /** Keyframe-mode toggle changed (Editor.setKeyframesEnabled). */
+    keyframesEnabledChange: {
+        enabled: boolean;
+    };
+    /** Jump-to-clip-edge nav toggle changed (Editor.setClipEdgeNavEnabled). */
+    clipEdgeNavEnabledChange: {
+        enabled: boolean;
+    };
     /** Zoom (px/sec) changed. */
     scaleChange: {
         pxPerSec: number;
@@ -297,10 +372,131 @@ interface EditorApi {
     setSnap(snap: boolean): void;
     getSelection(): string | null;
     setSelection(clipId: string | null): void;
+    isKeyframesEnabled(): boolean;
+    setKeyframesEnabled(enabled: boolean): void;
+    isClipEdgeNavEnabled(): boolean;
+    setClipEdgeNavEnabled(enabled: boolean): void;
+    /** Screen-space CSS-pixel rect of the active rendered frame, post
+     *  transform, relative to the editor preview. Null when none. */
+    getActiveFrameRect(): {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | null;
+    /** Output frame rect (fixed bounds, no transform). The overlay
+     *  draws the dashed border here. */
+    getActiveOutputFrameRect(): {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | null;
+    /**
+     * Upsert a per-property keyframe at the given clip-local time. If a
+     * keyframe for the same `prop` already exists within ~1 frame of
+     * `time` it gets its value updated; else a new one is appended.
+     * Returns the keyframe's id, or null when the clip can't be found.
+     *
+     * Defaults: `time` = playhead in clip-local coords; `value` = the
+     * currently interpolated value for that prop (so adding doesn't
+     * cause a visible jump).
+     */
+    addKeyframe(clipId: string, prop: KeyframeProp, opts?: {
+        time?: Ms;
+        value?: number;
+    }): string | null;
+    removeKeyframe(clipId: string, keyframeId: string): boolean;
+    moveKeyframe(clipId: string, keyframeId: string, timeMs: Ms): boolean;
+    /** Change one keyframe's value (single number, since each kf is
+     *  per-property). */
+    setKeyframeValue(clipId: string, keyframeId: string, value: number): boolean;
+    /**
+     * Change one keyframe's outgoing easing curve. Shapes only the
+     * segment from this kf to the NEXT kf in time on the same prop.
+     * The kf's value is untouched.
+     */
+    setKeyframeEasing(clipId: string, keyframeId: string, easing: EasingKind): boolean;
+    /**
+     * Batch-set the outgoing easing on every kf at one moment in time
+     * (within the 16ms tolerance that the rest of the API uses) on a
+     * single clip. Mirrors the panel's "one dropdown for the moment"
+     * UX so all three props (panX / panY / scale) at the selected
+     * moment animate with the same curve. Single history entry.
+     */
+    setKeyframesEasingAtTime(clipId: string, timeMs: Ms, easing: EasingKind): boolean;
+    /**
+     * CapCut-style auto-record: write `value` for `prop` at the playhead.
+     * - If the prop already has keyframes → upsert a keyframe at the
+     *   playhead with this value.
+     * - If the prop has no keyframes → just update the static base
+     *   (panX / panY / scale on the clip) so the visual changes
+     *   without committing the user to an animation track yet.
+     * Returns true if the project changed.
+     */
+    setValueAtPlayhead(clipId: string, prop: KeyframeProp, value: number): boolean;
+    getSelectedKeyframe(): {
+        clipId: string;
+        keyframeId: string;
+    } | null;
+    setSelectedKeyframe(target: {
+        clipId: string;
+        keyframeId: string;
+    } | null): void;
+    /**
+     * Toolbar-style toggle. If ANY keyframe exists at the playhead time
+     * on the selected clip, remove every keyframe at that time (all
+     * props). Otherwise, capture one keyframe per prop (panX, panY,
+     * scale) at the playhead with the currently interpolated values.
+     * Returns true when the project changed.
+     */
+    toggleKeyframeAtPlayhead(): boolean;
+    /**
+     * Clear every keyframe AND every static transform value on a clip,
+     * restoring the identity pose (panX=0, panY=0, scale=1). Single
+     * history entry. */
+    resetClipTransform(clipId: string): boolean;
+    /**
+     * Pin all three transform props (panX, panY, scale) to identity
+     * (0, 0, 1) at one specific clip-local time. Upserts on each prop —
+     * keyframes that already exist at that time get their values
+     * overwritten; props with no kf there get one added. Single history
+     * entry. Used by the panel's Reset button when a keyframe is selected.
+     */
+    resetKeyframesAtTime(clipId: string, timeMs: Ms): boolean;
+    /**
+     * Move the playhead to a clip edge. "end" intentionally lands 1ms
+     * INSIDE the clip (clipEnd - 1) so the playhead remains inside the
+     * clip — that lets the user immediately press the keyframe button
+     * (or the I/O shortcut) and have it find the right clip + drop a
+     * keyframe at clip-local time `duration - 1ms`. Without the -1ms
+     * offset the playhead lands on the seam and `toggleKeyframeAtPlayhead`
+     * picks the next clip (or none at all).
+     * Returns true when the seek actually moved.
+     */
+    seekToClipEdge(clipId: string, edge: "start" | "end"): boolean;
+    /** Convenience for the toolbar: act on the currently-selected clip. */
+    seekToSelectedClipEdge(edge: "start" | "end"): boolean;
     canUndo(): boolean;
     canRedo(): boolean;
     undo(): boolean;
     redo(): boolean;
+    /**
+     * Open a "drag session". While open, every internal `pushHistory`
+     * call captures the pre-session snapshot ONCE — subsequent calls
+     * during the same session are no-ops. The session commits a single
+     * history entry on `endInteraction()` (or is dropped entirely if
+     * the project ended up unchanged). Nestable: nested begin/end pairs
+     * count by depth and only the outermost commits.
+     *
+     * Hosts call this around continuous gestures (drag the preview
+     * overlay, scrub a numeric slider, wheel-zoom) so a single user
+     * gesture becomes ONE undo entry instead of 30-100. Without this,
+     * each pointermove of an overlay drag pushes its own history entry
+     * and the user has to mash Cmd+Z that many times to fully undo.
+     */
+    beginInteraction(): void;
+    endInteraction(): void;
     /**
      * Bookend slot at the very left of the top toolbar — host appends
      * its own controls (e.g. an aspect-ratio dropdown). Empty by default
@@ -339,6 +535,13 @@ declare class Editor implements EditorApi {
     private bus;
     private history;
     private selectedClipId;
+    private selectedKeyframe;
+    private keyframesEnabled;
+    private clipEdgeNavEnabled;
+    /** Drag-session bookkeeping for ripple-merge undo. See
+     *  beginInteraction / endInteraction docs on EditorApi. */
+    private interactionDepth;
+    private interactionStartSnapshot;
     private pxPerSec;
     private snap;
     private locale;
@@ -426,10 +629,74 @@ declare class Editor implements EditorApi {
     snapMs(timeMs: Ms, ignoreClipId?: string | null): Ms;
     getSelection(): string | null;
     setSelection(clipId: string | null): void;
+    isKeyframesEnabled(): boolean;
+    /**
+     * 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(): {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | 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(): {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | null;
+    setKeyframesEnabled(enabled: boolean): void;
+    isClipEdgeNavEnabled(): boolean;
+    setClipEdgeNavEnabled(enabled: boolean): void;
+    addKeyframe(clipId: string, prop: KeyframeProp, opts?: {
+        time?: Ms;
+        value?: number;
+    }): string | null;
+    removeKeyframe(clipId: string, keyframeId: string): boolean;
+    moveKeyframe(clipId: string, keyframeId: string, timeMs: Ms): boolean;
+    setKeyframeValue(clipId: string, keyframeId: string, value: number): boolean;
+    setKeyframeEasing(clipId: string, keyframeId: string, easing: EasingKind): boolean;
+    setKeyframesEasingAtTime(clipId: string, timeMs: Ms, easing: EasingKind): boolean;
+    setValueAtPlayhead(clipId: string, prop: KeyframeProp, value: number): boolean;
+    getSelectedKeyframe(): {
+        clipId: string;
+        keyframeId: string;
+    } | null;
+    resetClipTransform(clipId: string): boolean;
+    resetKeyframesAtTime(clipId: string, timeMs: Ms): boolean;
+    seekToClipEdge(clipId: string, edge: "start" | "end"): boolean;
+    seekToSelectedClipEdge(edge: "start" | "end"): boolean;
+    toggleKeyframeAtPlayhead(): boolean;
+    setSelectedKeyframe(target: {
+        clipId: string;
+        keyframeId: string;
+    } | null): void;
     canUndo(): boolean;
     canRedo(): boolean;
     undo(): boolean;
     redo(): boolean;
+    beginInteraction(): void;
+    endInteraction(): void;
+    /**
+     * 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.
+     */
+    private reconcileSelectionsWithProject;
     on<K extends EditorEventName>(event: K, handler: (payload: EditorEventMap[K]) => void): () => void;
     off<K extends EditorEventName>(event: K, handler: (payload: EditorEventMap[K]) => void): void;
     destroy(): void;
@@ -441,6 +708,32 @@ declare class Editor implements EditorApi {
     private handleSourceMetadata;
 }
 
+/**
+ * The transform a clip's content is rendered with at a given moment.
+ * Engines apply this INSIDE a fixed output frame: `panX` / `panY`
+ * translate the content (in CSS px), `scale` resizes it around the
+ * output frame's center. Anything pushed outside the frame is
+ * clipped. Identity = `{ panX: 0, panY: 0, scale: 1 }`.
+ */
+interface EffectiveTransform {
+    panX: number;
+    panY: number;
+    scale: number;
+}
+/** Identity transform — no pan, no scaling (content fills the output frame). */
+declare const IDENTITY_TRANSFORM: EffectiveTransform;
+/** True when a transform is effectively identity (within FP slop). */
+declare function isIdentityTransform(t: EffectiveTransform): boolean;
+
+/**
+ * Effective transform = all three properties evaluated together. The
+ * engine applies this to the content inside the fixed output frame:
+ * scale around frame center, then translate by (panX, panY).
+ */
+declare function getEffectiveTransform(clip: Clip, localMs: Ms): EffectiveTransform;
+/** Same as `getEffectiveTransform` but takes timeline-absolute time. */
+declare function getTransformAtTimelineTime(clip: Clip, timelineMs: Ms): EffectiveTransform;
+
 declare function createEmptyProject(): Project;
 /**
  * Defensive normalization — ensures clips on each track are sorted by
@@ -528,6 +821,23 @@ interface TimelineOptions {
     }) => void;
     onResizeClip?: (clipId: string, edits: Partial<Pick<Clip, "in" | "out" | "start">>) => void;
     onChange?: (project: Project) => void;
+    /**
+     * Hosts wire these to forward keyframe edits to the Editor. The
+     * Timeline only paints + hit-tests; mutation goes through these
+     * callbacks so the Editor can push history + emit events.
+     */
+    onSelectKeyframe?: (target: {
+        clipId: string;
+        keyframeId: string;
+    } | null) => void;
+    onMoveKeyframe?: (clipId: string, keyframeId: string, timeMs: Ms) => void;
+    /** Host-driven state mirror — Editor passes these on every render
+     *  via `Timeline.setKeyframeState`. */
+    keyframesEnabled?: boolean;
+    selectedKeyframe?: {
+        clipId: string;
+        keyframeId: string;
+    } | null;
     /**
      * Lets the host predict where a drop will actually land — used to
      * keep the drag-ghost visual honest. The Editor wires this to its
@@ -576,6 +886,8 @@ declare class Timeline {
     private readOnly;
     private autoFitEnabled;
     private locale;
+    private keyframesEnabled;
+    private selectedKeyframe;
     private scrollLeft;
     private scrollTop;
     private viewportWidth;
@@ -594,6 +906,7 @@ declare class Timeline {
     private scrollbarDrag;
     private hoveredClipId;
     private hoveredTrackIndex;
+    private hoveredKeyframe;
     private hoverCursor;
     private dropTargetTrackIndex;
     private snapX;
@@ -690,6 +1003,15 @@ declare class Timeline {
     private maybeContinueFade;
     private maybeAutoFit;
     private buildDrawState;
+    /** Host-pushed state — Editor calls this when its keyframe mode
+     *  changes or when a keyframe is selected/deselected externally. */
+    setKeyframeState(state: {
+        enabled?: boolean;
+        selected?: {
+            clipId: string;
+            keyframeId: string;
+        } | null;
+    }): void;
     private readStyle;
     private attachPointer;
     private onPointerDown;
@@ -718,6 +1040,7 @@ declare class Timeline {
      */
     private maybeStartDragAutoScroll;
     private onPointerUp;
+    private attachKeyboard;
     private attachWheel;
     private attachResize;
     private localCoords;
@@ -726,4 +1049,4 @@ declare class Timeline {
     private applySnap;
 }
 
-export { CanvasCompositorEngine, type CanvasCompositorEngineOptions, Clip, Editor, type EditorApi, type EditorEventMap, type EditorEventName, type EditorOptions, HEADER_WIDTH, HtmlVideoEngine, Locale, MediaSource, Ms, PlaybackEngine, PlaybackEngineFactory, PlaybackEngineOptions, Project, RULER_HEIGHT, TRACK_HEIGHT, Theme, Timeline, type TimelineOptions, Track, canvasCompositorEngineFactory, createEmptyProject, createId, htmlVideoEngineFactory, normalizeProject, setTimelineMetrics };
+export { CanvasCompositorEngine, type CanvasCompositorEngineOptions, Clip, EasingKind, Editor, type EditorApi, type EditorEventMap, type EditorEventName, type EditorOptions, type EffectiveTransform, HEADER_WIDTH, HtmlVideoEngine, IDENTITY_TRANSFORM, KeyframeProp, Locale, MediaSource, Ms, PlaybackEngine, PlaybackEngineFactory, PlaybackEngineOptions, Project, RULER_HEIGHT, TRACK_HEIGHT, Theme, Timeline, type TimelineOptions, Track, canvasCompositorEngineFactory, createEmptyProject, createId, getEffectiveTransform, getTransformAtTimelineTime, htmlVideoEngineFactory, isIdentityTransform, normalizeProject, setTimelineMetrics };