@aicut/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,640 @@
+/**
+ * UI strings the editor paints into the DOM (toolbar tooltips, the
+ * fullscreen exit button) and onto the timeline canvas (phantom new-
+ * track label, track header labels). Every user-visible literal in
+ * `@aicut/core` flows through this interface — there are no hidden
+ * hard-coded translations elsewhere in the library.
+ *
+ * Defaults to English. Hosts that want Chinese (or any other locale)
+ * pass `locale: localeZh` to `Editor.create` / `Timeline.create`, or
+ * override individual keys with `locale: { undo: "撤销" }`.
+ */
+interface Locale {
+    undo: string;
+    redo: string;
+    split: string;
+    trimLeft: string;
+    trimRight: string;
+    speedComingSoon: string;
+    playPause: string;
+    fullscreen: string;
+    snap: string;
+    /** Title shown on the snap button when snap is ON (clicking turns OFF). */
+    snapOnTitle: string;
+    /** Title shown when snap is OFF (clicking turns ON). */
+    snapOffTitle: string;
+    zoomOut: string;
+    zoomIn: string;
+    reset: string;
+    exitFullscreen: string;
+    exitFullscreenTitle: string;
+    /** Phantom row that appears under the last track during a drag. */
+    newTrack: string;
+    /** Track header — `{n}` is replaced with the 1-based track index. */
+    videoTrackLabel: string;
+    /** Same template format as videoTrackLabel. */
+    audioTrackLabel: string;
+}
+/** English. The library default — chosen over Chinese as the OSS norm. */
+declare const localeEn: Locale;
+/** Simplified Chinese. */
+declare const localeZh: Locale;
+/** Spread defaults under host overrides — host can supply a partial. */
+declare function mergeLocale(partial: Partial<Locale> | undefined): Locale;
+/**
+ * Replace `{key}` placeholders in a template. We only need `{n}`
+ * substitution today; the implementation is generic so additional
+ * keys (e.g. `{name}`) won't need a second pass.
+ */
+declare function formatLabel(template: string, vars: Record<string, string | number>): string;
+
+/**
+ * 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;
+}
+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[];
+}
+/**
+ * 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;
+}
+
+interface EditorOptions {
+    /** Host element to mount the editor into. Will be wiped on init. */
+    container: HTMLElement;
+    /** Initial project state. Falls back to an empty single-track project. */
+    project?: Project;
+    /** CSS variable overrides. */
+    theme?: Theme;
+    /** Initial playhead position (ms). */
+    initialTime?: Ms;
+    /** Initial timeline zoom (pixels per second). Defaults to 80. */
+    initialScale?: number;
+    /** Initial snap toggle. Defaults to true. */
+    initialSnap?: boolean;
+    /**
+     * UI string overrides. Falls back to English (`localeEn`) for any
+     * keys not provided. Use `localeZh` as the value for full Chinese.
+     * Call `editor.setLocale(...)` to switch at runtime.
+     */
+    locale?: Partial<Locale>;
+}
+interface EditorEventMap {
+    /** Emitted whenever the project mutates. */
+    change: {
+        project: Project;
+    };
+    /** Playhead position update — driven by the playback tick loop. */
+    time: {
+        timeMs: Ms;
+    };
+    play: void;
+    pause: void;
+    /** A source's metadata finished loading (duration etc). */
+    ready: {
+        sourceId: string | null;
+    };
+    /** User clicked the Export button. Host decides what to do with the JSON. */
+    export: {
+        project: Project;
+    };
+    error: {
+        error: Error;
+    };
+    /** Currently selected clip id, or null. */
+    selectionChange: {
+        clipId: string | null;
+    };
+    /** Zoom (px/sec) changed. */
+    scaleChange: {
+        pxPerSec: number;
+    };
+    /** Snap toggle changed. */
+    snapChange: {
+        snap: boolean;
+    };
+    /** Undo/redo stack states changed (button enablement). */
+    historyChange: {
+        canUndo: boolean;
+        canRedo: boolean;
+    };
+}
+type EditorEventName = keyof EditorEventMap;
+interface EditorApi {
+    play(): void;
+    pause(): void;
+    togglePlay(): void;
+    seek(timeMs: Ms): void;
+    getTime(): Ms;
+    getDuration(): Ms;
+    isPlaying(): boolean;
+    enterFullscreen(): Promise<void>;
+    exitFullscreen(): Promise<void>;
+    isFullscreen(): boolean;
+    split(timeMs?: Ms): string[] | null;
+    /** Alias of split, kept for back-compat. */
+    cut(timeMs?: Ms): string[] | null;
+    /** Trim the selected clip's left edge to the given time (or playhead). */
+    trimLeft(timeMs?: Ms): boolean;
+    /** Trim the selected clip's right edge to the given time (or playhead). */
+    trimRight(timeMs?: Ms): boolean;
+    removeClip(clipId: string): boolean;
+    setClipSpeed(clipId: string, speed: number): boolean;
+    previewMoveTarget(clipId: string, start: Ms, intendedTrackId?: string): {
+        trackIndex: number;
+        trackId: string;
+        wouldCreateNew: boolean;
+    } | null;
+    addTrack(kind: Track["kind"]): Track;
+    removeTrack(trackId: string): boolean;
+    moveClip(clipId: string, opts: {
+        start?: Ms;
+        trackId?: string;
+        newTrack?: boolean;
+    }): boolean;
+    resizeClip(clipId: string, edits: Partial<Pick<Clip, "in" | "out" | "start">>): boolean;
+    addSource(source: MediaSource, opts?: {
+        appendClip?: boolean;
+    }): MediaSource;
+    setProject(project: Project): void;
+    getProject(): Project;
+    /** Replace the project with a brand-new empty one. */
+    reset(): void;
+    setTheme(theme: Theme): void;
+    /**
+     * Swap the UI locale at runtime. Partial overrides merge with the
+     * English default. Triggers a re-render so the toolbar tooltips
+     * and timeline canvas labels pick up the new strings immediately.
+     */
+    setLocale(locale: Partial<Locale>): void;
+    /**
+     * Fire the `export` event with the current project JSON. Hosts call
+     * this from their own export button (built into their toolbarRight
+     * slot, a keyboard shortcut, a menu item, etc.) to surface project
+     * data to whatever pipeline they own. The library never invokes
+     * this on its own — it has no UI for export.
+     */
+    requestExport(): void;
+    getScale(): number;
+    setScale(pxPerSec: number): void;
+    getSnap(): boolean;
+    setSnap(snap: boolean): void;
+    getSelection(): string | null;
+    setSelection(clipId: string | null): void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    undo(): boolean;
+    redo(): boolean;
+    /**
+     * Bookend slot at the very left of the top toolbar — host appends
+     * its own controls (e.g. an aspect-ratio dropdown). Empty by default
+     * and renders no separator until populated.
+     */
+    readonly toolbarLeft: HTMLElement;
+    /** Right-side bookend slot — conventionally export / save / share. */
+    readonly toolbarRight: HTMLElement;
+    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;
+}
+/**
+ * Top-level editor instance — the only stateful object a host app
+ * interacts with. Owns the project, the playback engine, the vanilla
+ * DOM UI, plus viewport (zoom/snap), selection, and history state.
+ *
+ * Framework wrappers (`@aicut/react`, `@aicut/vue`) should mount a
+ * container, instantiate this once, mirror prop changes (`theme`)
+ * into it, and forward events as framework-native callbacks.
+ */
+declare class Editor implements EditorApi {
+    private container;
+    private project;
+    private engine;
+    private ui;
+    private bus;
+    private history;
+    private selectedClipId;
+    private pxPerSec;
+    private snap;
+    private locale;
+    private destroyed;
+    constructor(opts: EditorOptions);
+    static create(opts: EditorOptions): Editor;
+    get toolbarLeft(): HTMLElement;
+    get toolbarRight(): HTMLElement;
+    play(): void;
+    pause(): void;
+    togglePlay(): void;
+    seek(timeMs: Ms): void;
+    getTime(): Ms;
+    getDuration(): Ms;
+    isPlaying(): boolean;
+    /**
+     * In-tab "fullscreen" — covers the browser viewport via fixed
+     * positioning, NOT the OS Fullscreen API. This is what the reference
+     * UI calls "全屏预览": the user stays in their tab, no browser
+     * permission prompt, ESC exits. Browser fullscreen would also work
+     * but is heavier UX and gets blocked in iframes.
+     */
+    enterFullscreen(): Promise<void>;
+    exitFullscreen(): Promise<void>;
+    isFullscreen(): boolean;
+    /**
+     * Split the clip at `timeMs` (or playhead). Returns the two new clip ids
+     * or null if there's no clip to split at that time.
+     */
+    split(timeMs?: Ms): string[] | null;
+    cut(timeMs?: Ms): string[] | null;
+    trimLeft(timeMs?: Ms): boolean;
+    trimRight(timeMs?: Ms): boolean;
+    removeClip(clipId: string): boolean;
+    setClipSpeed(clipId: string, speed: number): boolean;
+    addTrack(kind: Track["kind"]): Track;
+    removeTrack(trackId: string): boolean;
+    /**
+     * Pure prediction of where a `moveClip(...)` would land — same smart
+     * routing as the real move (intended → source → other → new track),
+     * just no mutation, no history. Lets the Timeline preview the
+     * ACTUAL outcome of a drop so the ghost stops lying about new
+     * tracks that won't get created.
+     */
+    previewMoveTarget(clipId: string, start: Ms, intendedTrackId?: string): {
+        trackIndex: number;
+        trackId: string;
+        wouldCreateNew: boolean;
+    } | null;
+    moveClip(clipId: string, opts: {
+        start?: Ms;
+        trackId?: string;
+        newTrack?: boolean;
+    }): boolean;
+    resizeClip(clipId: string, edits: Partial<Pick<Clip, "in" | "out" | "start">>): boolean;
+    addSource(source: MediaSource, opts?: {
+        appendClip?: boolean;
+    }): MediaSource;
+    setProject(project: Project): void;
+    getProject(): Project;
+    /**
+     * Restore the "fresh import" state: same media library, single
+     * default video track, one full-length clip per video source laid
+     * end-to-end. This mirrors the initial layout a host would get
+     * after dropping their videos in, so "reset" feels like "start
+     * over without re-importing" rather than "wipe everything".
+     *
+     * Goes through the regular history stack — ⌘Z brings the previous
+     * edit back. Sources without a known duration are skipped (they'd
+     * render as zero-width clips, which is worse than absent).
+     */
+    reset(): void;
+    setTheme(theme: Theme): void;
+    setLocale(locale: Partial<Locale>): void;
+    /** Internal — UI reads the resolved locale here on each render. */
+    getLocale(): Locale;
+    requestExport(): void;
+    getScale(): number;
+    setScale(pxPerSec: number): void;
+    getSnap(): boolean;
+    setSnap(snap: boolean): void;
+    /** Snap a candidate ms to the nearest snappable surface within SNAP_PX. */
+    snapMs(timeMs: Ms, ignoreClipId?: string | null): Ms;
+    getSelection(): string | null;
+    setSelection(clipId: string | null): void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    undo(): boolean;
+    redo(): boolean;
+    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;
+    private appendTrack;
+    private resolveTrimTarget;
+    private pushHistory;
+    private emitHistory;
+    private afterMutation;
+    private handleSourceMetadata;
+}
+
+declare function createEmptyProject(): Project;
+/**
+ * Defensive normalization — ensures clips on each track are sorted by
+ * `start`, IDs exist, and trivially-empty clips (out <= in) are dropped.
+ * Called from `Editor.setProject` so consumers can hand us loosely-formed
+ * JSON without risking inconsistent internal state.
+ */
+declare function normalizeProject(project: Project): Project;
+
+/**
+ * Short, stable, URL-safe ID. Not cryptographic — fine for client IDs
+ * that get persisted in the project JSON.
+ */
+declare function createId(prefix?: string): string;
+
+/** Visual constants — kept here so draw + hit-test share one source of truth. */
+declare const TRACK_HEIGHT = 56;
+declare const RULER_HEIGHT = 24;
+declare const HEADER_WIDTH = 96;
+
+/**
+ * Public options for the standalone `Timeline` component. The class
+ * is framework-agnostic — `@aicut/react` and `@aicut/vue` wrap it,
+ * and the built-in `Editor` composes one internally for its timeline
+ * panel. Reuse the same instance for a "frame-picker" use case by
+ * loading a project with a single video clip and `readOnly: true`.
+ */
+interface TimelineOptions {
+    /** Host element. Will be wiped on init. */
+    container: HTMLElement;
+    project: Project;
+    /** Pixels per second. Defaults to 80; auto-fits on mount when possible. */
+    pxPerSec?: number;
+    /** Initial playhead position. */
+    time?: Ms;
+    /** Initially selected clip. */
+    selectedClipId?: string | null;
+    /** Show the track-name header column (left). Default true. */
+    showHeader?: boolean;
+    /** Disable interactions — useful for read-only preview / frame picker. */
+    readOnly?: boolean;
+    /** Snap to clip edges + playhead when dragging. Default true. */
+    snap?: boolean;
+    /** Compute and apply fit-to-window on first project change. Default true. */
+    autoFit?: boolean;
+    /** UI string overrides (English defaults). Use `localeZh` for Chinese. */
+    locale?: Partial<Locale>;
+    /**
+     * Render an empty 36px toolbar strip at the top of the host element
+     * with `toolbarLeft` / `toolbarRight` flex slots. The library paints
+     * NOTHING into either slot — hosts append their own controls (an
+     * export button, a size/aspect dropdown, etc.). Default false; the
+     * canvas takes the full host height when the toolbar is off, so
+     * adopting the slot later is a non-breaking opt-in.
+     */
+    toolbar?: boolean;
+    onSeek?: (timeMs: Ms) => void;
+    onSelectClip?: (clipId: string | null) => void;
+    onScaleChange?: (pxPerSec: number) => void;
+    onDeleteTrack?: (trackId: string) => void;
+    onMoveClip?: (clipId: string, opts: {
+        start?: Ms;
+        trackId?: string;
+        newTrack?: boolean;
+    }) => void;
+    onResizeClip?: (clipId: string, edits: Partial<Pick<Clip, "in" | "out" | "start">>) => void;
+    onChange?: (project: Project) => void;
+    /**
+     * Lets the host predict where a drop will actually land — used to
+     * keep the drag-ghost visual honest. The Editor wires this to its
+     * smart routing (intended → source → other → new track), so the
+     * ghost shows the real outcome rather than just the user's hover.
+     *
+     * Return `{ trackIndex }` for an existing track, or
+     * `{ wouldCreateNew: true }` for the auto-split case.
+     */
+    resolveDrop?: (clipId: string, intent: {
+        start: Ms;
+        intendedTrackIndex: number;
+    }) => {
+        trackIndex: number;
+        wouldCreateNew: boolean;
+    };
+}
+/**
+ * Canvas-rendered, framework-free timeline. Owns ruler, multi-track
+ * layout, headers, frame-thumbnails, playhead, snap, and all pointer
+ * gestures. No DOM children for clips/ticks/etc — every pixel is
+ * painted via 2D canvas, so even hundreds of clips render in <2ms.
+ */
+declare class Timeline {
+    private root;
+    private opts;
+    private canvas;
+    private ctx;
+    private thumbs;
+    private hiddenHost;
+    private toolbarEl;
+    /**
+     * Public flex slot at the left of the top toolbar. `null` when
+     * `toolbar` is disabled. Hosts append their own elements (e.g. a
+     * size/aspect dropdown). React/Vue wrappers portal children here.
+     */
+    readonly toolbarLeft: HTMLDivElement | null;
+    /** Right-side counterpart — conventionally used for export/save. */
+    readonly toolbarRight: HTMLDivElement | null;
+    private project;
+    private pxPerSec;
+    private timeMs;
+    private selectedClipId;
+    private snapEnabled;
+    private showHeader;
+    private readOnly;
+    private autoFitEnabled;
+    private locale;
+    private scrollLeft;
+    private scrollTop;
+    private viewportWidth;
+    private viewportHeight;
+    /**
+     * `Date.now()` of the last interaction with each scrollbar (scroll
+     * change OR hover OR drag). Drives the macOS-style fade — bars are
+     * fully opaque for SCROLLBAR_FADE_HOLD_MS after activity, then ease
+     * out over the next SCROLLBAR_FADE_OUT_MS.
+     */
+    private lastScrollInteractY;
+    private lastScrollInteractX;
+    private hoverScrollbarY;
+    private hoverScrollbarX;
+    /** When set, pointer is dragging a scrollbar thumb. */
+    private scrollbarDrag;
+    private hoveredClipId;
+    private hoveredTrackIndex;
+    private hoverCursor;
+    private dropTargetTrackIndex;
+    private snapX;
+    private drag;
+    /**
+     * In-flight ghost of the clip being dragged. Decoupled from the
+     * project data so the data stays clean and undo-able only commits
+     * on release. Has both the proposed `start` (X) and `trackIndex`
+     * (Y), so the rendered ghost follows the cursor across tracks.
+     */
+    private dragGhost;
+    /**
+     * Most recent local pointer coords during a move drag — used by the
+     * edge-autoscroll loop to re-run drop-target resolution between
+     * pointermove events while scrollTop ticks under a stationary cursor.
+     */
+    private lastDragPointerX;
+    private lastDragPointerY;
+    private dragScrollRafPending;
+    private rafPending;
+    private hasAutoFitted;
+    private resizeObs;
+    private destroyed;
+    static create(opts: TimelineOptions): Timeline;
+    constructor(opts: TimelineOptions);
+    /**
+     * Sync the project data. Does NOT reset the auto-fit latch — that's
+     * what caused the editor-side zoom feedback loop: every Editor
+     * mutation called `ui.render() → timeline.setProject()` which used
+     * to reset auto-fit, refit on the next frame, emit a new scale,
+     * which re-rendered… and round we went. Callers that genuinely
+     * want a re-fit (e.g. when the host swaps to a brand-new project)
+     * should call `refit()` explicitly.
+     */
+    setProject(p: Project): void;
+    /** Force a re-fit on the next render. */
+    refit(): void;
+    getProject(): Project;
+    setTime(timeMs: Ms): void;
+    getTime(): Ms;
+    setScale(pxPerSec: number): void;
+    getScale(): number;
+    setSelection(id: string | null): void;
+    getSelection(): string | null;
+    setSnap(snap: boolean): void;
+    getSnap(): boolean;
+    setLocale(locale: Partial<Locale>): void;
+    /** Fit the project's full duration into the current viewport width. */
+    fitToWindow(): void;
+    /**
+     * Test/debug introspection — pixel coordinates of every visible clip,
+     * the playhead, and the headers. Because clips are canvas-painted
+     * there are no DOM nodes to query in e2e; tests use this instead.
+     * Exposed publicly so React/Vue wrappers can forward it to a ref.
+     */
+    getDebugInfo(): {
+        pxPerSec: number;
+        scrollLeft: number;
+        viewportWidth: number;
+        viewportHeight: number;
+        playheadX: number;
+        clips: Array<{
+            id: string;
+            trackIndex: number;
+            x: number;
+            width: number;
+            y: number;
+            height: number;
+        }>;
+    };
+    destroy(): void;
+    private resizeCanvas;
+    private computeFitScale;
+    private maxScrollLeft;
+    private maxScrollTop;
+    private clampScroll;
+    /**
+     * Scrollbar opacity = full for SCROLLBAR_FADE_HOLD_MS after last
+     * interaction, then linearly fades to 0 over SCROLLBAR_FADE_OUT_MS.
+     * Hovering or actively dragging the bar pins opacity at 1. Returns
+     * 0 if the bar isn't needed (content fits).
+     */
+    private scrollbarOpacity;
+    /** Mark a scrollbar axis as just-touched so its fade timer restarts. */
+    private touchScrollbar;
+    private scheduleRender;
+    /**
+     * Keep the raf loop alive while a scrollbar is still in its HOLD or
+     * fade-out window. Without this, opacity is sampled once and the
+     * bar would freeze at whatever value it had at the last input event
+     * instead of smoothly fading out. Skipped when a bar is pinned
+     * (hover or active drag) since opacity is constant there.
+     */
+    private maybeContinueFade;
+    private maybeAutoFit;
+    private buildDrawState;
+    private readStyle;
+    private attachPointer;
+    private onPointerDown;
+    private onPointerMove;
+    /**
+     * Update dragGhost + dropTargetTrackIndex for the in-flight move
+     * drag, given the current viewport pointer position. Pulled out of
+     * onPointerMove so the edge-autoscroll loop can re-run it on each
+     * tick — autoscroll moves scrollTop under a stationary cursor, and
+     * the ghost must follow the new row under that cursor.
+     */
+    private processMoveDrag;
+    /**
+     * Px-per-frame scroll speed when the pointer is in a vertical edge
+     * zone of the track region. Returns 0 outside the zone. Speed ramps
+     * linearly from 0 at the zone's inner edge to ~16 px/frame at the
+     * outer edge, so brushing the edge gives a gentle nudge and parking
+     * deep at it gives a brisk auto-scroll.
+     */
+    private dragScrollSpeedY;
+    /**
+     * Drive vertical auto-scroll while the user holds a clip near the
+     * top/bottom edge of the track area. Self-stopping — exits the loop
+     * once the pointer leaves the zone, the drag ends, or scroll bottoms
+     * out at the clamp.
+     */
+    private maybeStartDragAutoScroll;
+    private onPointerUp;
+    private attachWheel;
+    private attachResize;
+    private localCoords;
+    private hitTarget;
+    private trackIndexAtY;
+    private applySnap;
+}
+
+export { type Clip, Editor, type EditorApi, type EditorEventMap, type EditorEventName, type EditorOptions, HEADER_WIDTH, type Locale, type MediaSource, type Ms, type Project, RULER_HEIGHT, TRACK_HEIGHT, type Theme, Timeline, type TimelineOptions, type Track, createEmptyProject, createId, formatLabel, localeEn, localeZh, mergeLocale, normalizeProject };