@aicut/core 0.5.0 → 0.6.0

package/dist/{types-DvKlxylu.d.cts → types-BbZjOQLz.d.ts}

@@ -1,4 +1,4 @@
-import { P as Project, M as Ms } from './types-CHplD9V5.cjs';
+import { P as Project, M as Ms } from './types-CmS-UIEr.js';
 
 /**
  * Construction context the Editor hands to a playback engine. The
@@ -43,6 +43,39 @@ interface PlaybackEngine {
     seek(timeMs: Ms): void;
     /** Free all resources (DOM nodes, decoders, AudioContexts, rAF). */
     destroy(): void;
+    /**
+     * Optional. The **output frame rect** — the fixed bounds anything
+     * the engine renders is clipped to. The user's keyframe X / Y /
+     * scale move the content WITHIN this frame (think picture-in-
+     * picture, pan, zoom); anything outside is hidden by the engine.
+     *
+     * This rect does NOT change with the active transform — it's
+     * the stage. The overlay's dashed border is drawn here. Coords
+     * relative to `opts.host`. Returns null when no clip is active.
+     */
+    getOutputFrameRect?(): {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | null;
+    /**
+     * Optional. Return the screen-space CSS-pixel rectangle of the
+     * actually-rendered content (the video frame after the active
+     * keyframe transform is applied). May extend outside the output
+     * frame — the engine clips to the output frame at paint time, but
+     * the overlay still wants the geometric rect to position scale
+     * handles on the visible content corners.
+     *
+     * Returns null when no clip is active. Engines that don't expose
+     * this leave keyframe handles attached to the output frame instead.
+     */
+    getFrameRect?(): {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | null;
     /** Fired on each rAF / decoded frame with the current playhead. */
     onTimeUpdate?: (ms: Ms) => void;
     /** Fired once when the project's end is reached during playback. */

package/dist/{types-rwZx6FxE.d.ts → types-CjvRUPtZ.d.cts}

@@ -1,4 +1,4 @@
-import { P as Project, M as Ms } from './types-CHplD9V5.js';
+import { P as Project, M as Ms } from './types-CmS-UIEr.cjs';
 
 /**
  * Construction context the Editor hands to a playback engine. The
@@ -43,6 +43,39 @@ interface PlaybackEngine {
     seek(timeMs: Ms): void;
     /** Free all resources (DOM nodes, decoders, AudioContexts, rAF). */
     destroy(): void;
+    /**
+     * Optional. The **output frame rect** — the fixed bounds anything
+     * the engine renders is clipped to. The user's keyframe X / Y /
+     * scale move the content WITHIN this frame (think picture-in-
+     * picture, pan, zoom); anything outside is hidden by the engine.
+     *
+     * This rect does NOT change with the active transform — it's
+     * the stage. The overlay's dashed border is drawn here. Coords
+     * relative to `opts.host`. Returns null when no clip is active.
+     */
+    getOutputFrameRect?(): {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | null;
+    /**
+     * Optional. Return the screen-space CSS-pixel rectangle of the
+     * actually-rendered content (the video frame after the active
+     * keyframe transform is applied). May extend outside the output
+     * frame — the engine clips to the output frame at paint time, but
+     * the overlay still wants the geometric rect to position scale
+     * handles on the visible content corners.
+     *
+     * Returns null when no clip is active. Engines that don't expose
+     * this leave keyframe handles attached to the output frame instead.
+     */
+    getFrameRect?(): {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | null;
     /** Fired on each rAF / decoded frame with the current playhead. */
     onTimeUpdate?: (ms: Ms) => void;
     /** Fired once when the project's end is reached during playback. */

package/dist/types-CmS-UIEr.d.cts

@@ -0,0 +1,137 @@
+/**
+ * Milliseconds. All timing in the project is expressed as integer ms to
+ * keep JSON serialization unambiguous (no frame-rate coupling in the
+ * data model — the renderer can present time as frames if it wants).
+ */
+type Ms = number;
+interface MediaSource {
+    id: string;
+    url: string;
+    kind: "video" | "audio";
+    /** Optional — probed lazily from the <video> element if absent. */
+    duration?: Ms;
+    name?: string;
+}
+interface Clip {
+    id: string;
+    sourceId: string;
+    /** Window into the source — `in` inclusive, `out` exclusive. */
+    in: Ms;
+    out: Ms;
+    /** Position on the timeline. */
+    start: Ms;
+    /**
+     * Playback rate. 1 = normal, 2 = 2× speed. Default 1.
+     * Persisted in the project JSON so a host can restore exactly.
+     */
+    speed?: number;
+    /**
+     * Static base values for the content transform, used when the clip
+     * has no keyframes for that property. Pan slides the video inside
+     * the FIXED output frame (the dashed border the user sees); scale
+     * grows / shrinks the content around the frame center. Anything
+     * pushed outside the output frame is clipped — that's how
+     * picture-in-picture, pan, and zoom work.
+     *
+     * `panX`, `panY` are CSS pixels relative to the output frame center.
+     * Defaults: panX = 0, panY = 0, scale = 1 (content fills frame).
+     */
+    panX?: number;
+    panY?: number;
+    scale?: number;
+    /**
+     * Per-property keyframe animation. Each keyframe targets one prop
+     * (`panX`, `panY`, or `scale`) so the user can animate one axis
+     * independently of the others (the standard NLE / CapCut model).
+     *
+     * Times are clip-local (0 = clip's `in`), so trim and move ops
+     * carry keyframes with the clip. Empty array / undefined = use the
+     * static base values above. `normalizeProject` keeps it sorted by
+     * (prop, time).
+     */
+    keyframes?: Keyframe[];
+}
+/** Properties on a Clip that can be animated by keyframes. */
+type KeyframeProp = "panX" | "panY" | "scale";
+/**
+ * Easing curve that shapes the segment LEAVING this keyframe — i.e.
+ * the curve from this keyframe to the next one in time. Matches the
+ * "outgoing" easing model in After Effects / Premiere / CapCut so a
+ * single dropdown per keyframe is enough.
+ *
+ *   - `linear`     — constant rate (default)
+ *   - `easeIn`     — start slow, finish fast (cubic)
+ *   - `easeOut`    — start fast, finish slow (cubic)
+ *   - `easeInOut`  — slow on both ends, fast in the middle (cubic)
+ */
+type EasingKind = "linear" | "easeIn" | "easeOut" | "easeInOut";
+/**
+ * One pinned value for one property at one moment in clip-local time.
+ * Properties without keyframes fall back to the clip's static base
+ * value (`Clip.panX` / `panY` / `scale`).
+ */
+interface Keyframe {
+    id: string;
+    /** Which property this keyframe controls. */
+    prop: KeyframeProp;
+    /** Clip-local time in ms. 0 = clip's `in`. Bounds: [0, clip.out - clip.in]. */
+    time: Ms;
+    /** The value the property holds at this moment. Same units as the
+     *  matching static field (CSS px for pan, multiplier for scale). */
+    value: number;
+    /** Easing curve for the segment leaving THIS keyframe toward the
+     *  next one. Optional — omitted / undefined = "linear" (back-compat
+     *  with projects authored before the easing field existed). */
+    easing?: EasingKind;
+}
+interface Track {
+    id: string;
+    kind: "video" | "audio";
+    /** Clips on this track. Must be kept sorted by `start` and non-overlapping. */
+    clips: Clip[];
+}
+interface Project {
+    /** Schema version — bump when breaking the JSON shape. */
+    version: 1;
+    sources: MediaSource[];
+    tracks: Track[];
+    /**
+     * Project frame rate. Drives keyboard frame-stepping (← / →), the
+     * future timecode display, and ffmpeg compilation of keyframe
+     * animations. Optional for back-compat — projects without `fps`
+     * default to 30, matching consumer NLE convention (CapCut /
+     * Premiere project defaults). `normalizeProject` does NOT fill
+     * this in, so a missing field stays missing through round-trips.
+     */
+    fps?: number;
+}
+/**
+ * Subset of CSS variables the editor honors. Pass any custom values
+ * via `Editor` options; everything is forwarded as `--aicut-*` on the
+ * editor's root container, so a host can also override via plain CSS.
+ */
+interface Theme {
+    brand?: string;
+    secondary?: string;
+    surface?: string;
+    dark?: string;
+    muted?: string;
+    card?: string;
+    success?: string;
+    warning?: string;
+    info?: string;
+    error?: string;
+    /** Toolbar / ruler chrome. Background of the editor frame. */
+    controlsBg?: string;
+    controlsBorder?: string;
+    controlsText?: string;
+    controlsHover?: string;
+    controlsActive?: string;
+    /** Letterbox color around the preview video. Defaults to black. */
+    previewBg?: string;
+    radiusSm?: string;
+    radiusMd?: string;
+    radiusLg?: string;
+}
+
+export type { Clip as C, EasingKind as E, KeyframeProp as K, Ms as M, Project as P, Track as T, MediaSource as a, Theme as b, Keyframe as c };

package/dist/types-CmS-UIEr.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Milliseconds. All timing in the project is expressed as integer ms to
+ * keep JSON serialization unambiguous (no frame-rate coupling in the
+ * data model — the renderer can present time as frames if it wants).
+ */
+type Ms = number;
+interface MediaSource {
+    id: string;
+    url: string;
+    kind: "video" | "audio";
+    /** Optional — probed lazily from the <video> element if absent. */
+    duration?: Ms;
+    name?: string;
+}
+interface Clip {
+    id: string;
+    sourceId: string;
+    /** Window into the source — `in` inclusive, `out` exclusive. */
+    in: Ms;
+    out: Ms;
+    /** Position on the timeline. */
+    start: Ms;
+    /**
+     * Playback rate. 1 = normal, 2 = 2× speed. Default 1.
+     * Persisted in the project JSON so a host can restore exactly.
+     */
+    speed?: number;
+    /**
+     * Static base values for the content transform, used when the clip
+     * has no keyframes for that property. Pan slides the video inside
+     * the FIXED output frame (the dashed border the user sees); scale
+     * grows / shrinks the content around the frame center. Anything
+     * pushed outside the output frame is clipped — that's how
+     * picture-in-picture, pan, and zoom work.
+     *
+     * `panX`, `panY` are CSS pixels relative to the output frame center.
+     * Defaults: panX = 0, panY = 0, scale = 1 (content fills frame).
+     */
+    panX?: number;
+    panY?: number;
+    scale?: number;
+    /**
+     * Per-property keyframe animation. Each keyframe targets one prop
+     * (`panX`, `panY`, or `scale`) so the user can animate one axis
+     * independently of the others (the standard NLE / CapCut model).
+     *
+     * Times are clip-local (0 = clip's `in`), so trim and move ops
+     * carry keyframes with the clip. Empty array / undefined = use the
+     * static base values above. `normalizeProject` keeps it sorted by
+     * (prop, time).
+     */
+    keyframes?: Keyframe[];
+}
+/** Properties on a Clip that can be animated by keyframes. */
+type KeyframeProp = "panX" | "panY" | "scale";
+/**
+ * Easing curve that shapes the segment LEAVING this keyframe — i.e.
+ * the curve from this keyframe to the next one in time. Matches the
+ * "outgoing" easing model in After Effects / Premiere / CapCut so a
+ * single dropdown per keyframe is enough.
+ *
+ *   - `linear`     — constant rate (default)
+ *   - `easeIn`     — start slow, finish fast (cubic)
+ *   - `easeOut`    — start fast, finish slow (cubic)
+ *   - `easeInOut`  — slow on both ends, fast in the middle (cubic)
+ */
+type EasingKind = "linear" | "easeIn" | "easeOut" | "easeInOut";
+/**
+ * One pinned value for one property at one moment in clip-local time.
+ * Properties without keyframes fall back to the clip's static base
+ * value (`Clip.panX` / `panY` / `scale`).
+ */
+interface Keyframe {
+    id: string;
+    /** Which property this keyframe controls. */
+    prop: KeyframeProp;
+    /** Clip-local time in ms. 0 = clip's `in`. Bounds: [0, clip.out - clip.in]. */
+    time: Ms;
+    /** The value the property holds at this moment. Same units as the
+     *  matching static field (CSS px for pan, multiplier for scale). */
+    value: number;
+    /** Easing curve for the segment leaving THIS keyframe toward the
+     *  next one. Optional — omitted / undefined = "linear" (back-compat
+     *  with projects authored before the easing field existed). */
+    easing?: EasingKind;
+}
+interface Track {
+    id: string;
+    kind: "video" | "audio";
+    /** Clips on this track. Must be kept sorted by `start` and non-overlapping. */
+    clips: Clip[];
+}
+interface Project {
+    /** Schema version — bump when breaking the JSON shape. */
+    version: 1;
+    sources: MediaSource[];
+    tracks: Track[];
+    /**
+     * Project frame rate. Drives keyboard frame-stepping (← / →), the
+     * future timecode display, and ffmpeg compilation of keyframe
+     * animations. Optional for back-compat — projects without `fps`
+     * default to 30, matching consumer NLE convention (CapCut /
+     * Premiere project defaults). `normalizeProject` does NOT fill
+     * this in, so a missing field stays missing through round-trips.
+     */
+    fps?: number;
+}
+/**
+ * Subset of CSS variables the editor honors. Pass any custom values
+ * via `Editor` options; everything is forwarded as `--aicut-*` on the
+ * editor's root container, so a host can also override via plain CSS.
+ */
+interface Theme {
+    brand?: string;
+    secondary?: string;
+    surface?: string;
+    dark?: string;
+    muted?: string;
+    card?: string;
+    success?: string;
+    warning?: string;
+    info?: string;
+    error?: string;
+    /** Toolbar / ruler chrome. Background of the editor frame. */
+    controlsBg?: string;
+    controlsBorder?: string;
+    controlsText?: string;
+    controlsHover?: string;
+    controlsActive?: string;
+    /** Letterbox color around the preview video. Defaults to black. */
+    previewBg?: string;
+    radiusSm?: string;
+    radiusMd?: string;
+    radiusLg?: string;
+}
+
+export type { Clip as C, EasingKind as E, KeyframeProp as K, Ms as M, Project as P, Track as T, MediaSource as a, Theme as b, Keyframe as c };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aicut/core",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Framework-agnostic core for the AiCut video editor — canvas timeline, data model, pluggable PlaybackEngine (HTML5 / Canvas / WebCodecs), plus opt-in 3D lighting picker.",
   "license": "MIT",
   "author": "ziqiang <ziqiangytu@gmail.com>",