@aicut/core 0.4.2 → 0.5.0

package/dist/index.d.cts

@@ -1,5 +1,147 @@
-import { M as Ms, T as Track, C as Clip, a as MediaSource, P as Project, b as Theme, L as Locale } from './types-C95koNwJ.cjs';
-export { f as formatLabel, l as localeEn, c as localeZh, m as mergeLocale } from './types-C95koNwJ.cjs';
+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';
+
+/**
+ * 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 project;
+    private currentClipId;
+    private playing;
+    private timeMs;
+    private rafHandle;
+    private lastFrameTs;
+    /** Public event hooks — set by Editor. */
+    onTimeUpdate?: (ms: Ms) => void;
+    onEnded?: () => void;
+    onError?: (err: Error) => void;
+    onReady?: () => void;
+    onSourceMetadata?: (sourceId: string, durationMs: Ms) => void;
+    constructor(opts: PlaybackEngineOptions);
+    setProject(next: Project): void;
+    play(): void;
+    pause(): void;
+    isPlaying(): boolean;
+    getTime(): Ms;
+    seek(timeMs: Ms): void;
+    destroy(): void;
+    private syncSources;
+    private activate;
+    private seekVideoToClipOffset;
+    private clipById;
+    /**
+     * 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).
+     */
+    private clipAtTime;
+    /** Earliest clip starting at-or-after `timeMs` across all video tracks. */
+    private nextClipAfterTime;
+    /** Max clip end across all video tracks. */
+    private totalDuration;
+    private startTickLoop;
+    private stopTickLoop;
+    private advance;
+}
+/** Factory shorthand for `Editor.create({ playbackEngine })`. */
+declare const htmlVideoEngineFactory: PlaybackEngineFactory;
+
+interface CanvasCompositorEngineOptions extends PlaybackEngineOptions {
+    /**
+     * Show the corner HUD ("engine: canvas compositor • t=… • frames
+     * painted: …"). Off by default — production hosts get a clean canvas
+     * with no chrome painted on top. Turn on in development / demos to
+     * see who's drawing and what the current state is.
+     */
+    debug?: boolean;
+}
+/**
+ * Reference second engine — demonstrates that the `PlaybackEngine`
+ * surface really is engine-agnostic. Same `<video>`-based decode as
+ * `HtmlVideoEngine` (so it works in every browser, no WebCodecs gate),
+ * but rendering happens via `ctx.drawImage(video, …)` on a single
+ * canvas instead of the browser painting the video element itself.
+ *
+ * Why ship it: it's tangible proof that a host can swap the rendering
+ * surface for compositing / shaders / overlays / capture-to-canvas
+ * without touching Editor internals. It's also the natural stepping
+ * stone toward a WebGL or WebCodecs path (those replace the decoder
+ * but keep the canvas-blit pattern).
+ *
+ * Limits: same as `HtmlVideoEngine` (one source visible at a time,
+ * seek snaps to the browser's keyframe pipeline). The point is the
+ * surface, not new capability.
+ */
+declare class CanvasCompositorEngine implements PlaybackEngine {
+    private host;
+    private mount;
+    private canvas;
+    private ctx;
+    /** Only created when constructed with `debug: true`. */
+    private badge;
+    private videos;
+    private project;
+    private currentClipId;
+    private playing;
+    private timeMs;
+    private rafHandle;
+    private lastFrameTs;
+    private paintedFrames;
+    onTimeUpdate?: (ms: Ms) => void;
+    onEnded?: () => void;
+    onError?: (err: Error) => void;
+    onReady?: () => void;
+    onSourceMetadata?: (sourceId: string, durationMs: Ms) => void;
+    constructor(opts: CanvasCompositorEngineOptions);
+    setProject(next: Project): void;
+    play(): void;
+    pause(): void;
+    isPlaying(): boolean;
+    getTime(): Ms;
+    seek(timeMs: Ms): void;
+    destroy(): void;
+    private syncSources;
+    private activate;
+    private seekVideoToClipOffset;
+    private clipById;
+    private clipAtTime;
+    private nextClipAfterTime;
+    private totalDuration;
+    private resizeCanvas;
+    private startTickLoop;
+    private stopTickLoop;
+    private advance;
+    /**
+     * One paint per rAF — clears the canvas, draws the current active
+     * video frame letterboxed to fit, then refreshes the HUD. Done
+     * unconditionally (not just on `playing`) so the HUD frame counter
+     * and the seek preview both update when paused.
+     */
+    private paint;
+    private updateBadge;
+}
+/** Factory shorthand for `Editor.create({ playbackEngine })`. */
+declare const canvasCompositorEngineFactory: PlaybackEngineFactory;
 
 interface EditorOptions {
     /** Host element to mount the editor into. Will be wiped on init. */
@@ -20,6 +162,38 @@ interface EditorOptions {
      * Call `editor.setLocale(...)` to switch at runtime.
      */
     locale?: Partial<Locale>;
+    /**
+     * Optional factory for a custom playback engine. Receives the
+     * editor's preview host element + the initial project, returns
+     * anything satisfying `PlaybackEngine`. Defaults to the built-in
+     * `HtmlVideoEngine` (one hidden `<video>` per source, swap on
+     * boundaries). Hosts that need frame-accurate editing, multi-track
+     * compositing, transitions, etc. pass a `WebCodecsEngine` factory
+     * (v0.6+) or their own.
+     */
+    playbackEngine?: PlaybackEngineFactory;
+    /**
+     * Pixel height of each track row in the timeline (default 56). Lower
+     * values (~32–40) shrink the timeline footprint for small viewports
+     * where the default crowds out the preview. Reasonable range:
+     * [28, 96]. Applied process-wide via `setTimelineMetrics` — multi-
+     * editor mounts share the value.
+     */
+    trackHeight?: number;
+    /**
+     * Pixel height of the timeline ruler / time-label strip (default 24).
+     * Pair with `trackHeight` to compact the whole timeline. Reasonable
+     * range: [18, 36].
+     */
+    rulerHeight?: number;
+    /**
+     * Pixel height of the whole bottom timeline area (default 240). The
+     * canvas inside fills 100% of this and shows a vertical scrollbar
+     * when there are more tracks than fit. Lower this (~120–180) on
+     * small viewports so the preview takes more of the editor's height.
+     * Reasonable range: [120, 480].
+     */
+    timelineHeight?: number;
 }
 interface EditorEventMap {
     /** Emitted whenever the project mutates. */
@@ -282,10 +456,30 @@ declare function normalizeProject(project: Project): Project;
  */
 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;
+/** Visual constants — kept here so draw + hit-test share one source of truth.
+ *  The two row-height values are `let` rather than `const` so hosts can
+ *  shrink the timeline footprint for small screens via
+ *  `setTimelineMetrics(...)`. ES module live bindings mean every importer
+ *  sees the updated value automatically. */
+declare let TRACK_HEIGHT: number;
+declare let RULER_HEIGHT: number;
 declare const HEADER_WIDTH = 96;
+/**
+ * Override the default timeline row + ruler heights. Process-wide — call
+ * before / during editor construction. Useful when the editor is mounted
+ * in a small viewport (e.g. side-by-side panel on a laptop) and the
+ * default 56px tracks crowd out the preview.
+ *
+ * Reasonable ranges: trackHeight ∈ [28, 96], rulerHeight ∈ [18, 36].
+ * Anything smaller leaves no room for the clip label or the time ticks.
+ *
+ * Multi-editor mounts share these values. If you have two editors with
+ * different needs, agree on the smaller one or remount on switch.
+ */
+declare function setTimelineMetrics(opts: {
+    trackHeight?: number;
+    rulerHeight?: number;
+}): void;
 
 /**
  * Public options for the standalone `Timeline` component. The class
@@ -532,4 +726,4 @@ declare class Timeline {
     private applySnap;
 }
 
-export { Clip, Editor, type EditorApi, type EditorEventMap, type EditorEventName, type EditorOptions, HEADER_WIDTH, Locale, MediaSource, Ms, Project, RULER_HEIGHT, TRACK_HEIGHT, Theme, Timeline, type TimelineOptions, Track, createEmptyProject, createId, normalizeProject };
+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 };

package/dist/index.d.ts

@@ -1,5 +1,147 @@
-import { M as Ms, T as Track, C as Clip, a as MediaSource, P as Project, b as Theme, L as Locale } from './types-C95koNwJ.js';
-export { f as formatLabel, l as localeEn, c as localeZh, m as mergeLocale } from './types-C95koNwJ.js';
+import { P as PlaybackEngine, a as PlaybackEngineOptions, b as PlaybackEngineFactory } from './types-rwZx6FxE.js';
+import { M as Ms, P as Project, T as Track, C as Clip, a as MediaSource, b as Theme } from './types-CHplD9V5.js';
+import { L as Locale } from './i18n-B-DFWgKe.js';
+export { f as formatLabel, l as localeEn, a as localeZh, m as mergeLocale } from './i18n-B-DFWgKe.js';
+
+/**
+ * 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 project;
+    private currentClipId;
+    private playing;
+    private timeMs;
+    private rafHandle;
+    private lastFrameTs;
+    /** Public event hooks — set by Editor. */
+    onTimeUpdate?: (ms: Ms) => void;
+    onEnded?: () => void;
+    onError?: (err: Error) => void;
+    onReady?: () => void;
+    onSourceMetadata?: (sourceId: string, durationMs: Ms) => void;
+    constructor(opts: PlaybackEngineOptions);
+    setProject(next: Project): void;
+    play(): void;
+    pause(): void;
+    isPlaying(): boolean;
+    getTime(): Ms;
+    seek(timeMs: Ms): void;
+    destroy(): void;
+    private syncSources;
+    private activate;
+    private seekVideoToClipOffset;
+    private clipById;
+    /**
+     * 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).
+     */
+    private clipAtTime;
+    /** Earliest clip starting at-or-after `timeMs` across all video tracks. */
+    private nextClipAfterTime;
+    /** Max clip end across all video tracks. */
+    private totalDuration;
+    private startTickLoop;
+    private stopTickLoop;
+    private advance;
+}
+/** Factory shorthand for `Editor.create({ playbackEngine })`. */
+declare const htmlVideoEngineFactory: PlaybackEngineFactory;
+
+interface CanvasCompositorEngineOptions extends PlaybackEngineOptions {
+    /**
+     * Show the corner HUD ("engine: canvas compositor • t=… • frames
+     * painted: …"). Off by default — production hosts get a clean canvas
+     * with no chrome painted on top. Turn on in development / demos to
+     * see who's drawing and what the current state is.
+     */
+    debug?: boolean;
+}
+/**
+ * Reference second engine — demonstrates that the `PlaybackEngine`
+ * surface really is engine-agnostic. Same `<video>`-based decode as
+ * `HtmlVideoEngine` (so it works in every browser, no WebCodecs gate),
+ * but rendering happens via `ctx.drawImage(video, …)` on a single
+ * canvas instead of the browser painting the video element itself.
+ *
+ * Why ship it: it's tangible proof that a host can swap the rendering
+ * surface for compositing / shaders / overlays / capture-to-canvas
+ * without touching Editor internals. It's also the natural stepping
+ * stone toward a WebGL or WebCodecs path (those replace the decoder
+ * but keep the canvas-blit pattern).
+ *
+ * Limits: same as `HtmlVideoEngine` (one source visible at a time,
+ * seek snaps to the browser's keyframe pipeline). The point is the
+ * surface, not new capability.
+ */
+declare class CanvasCompositorEngine implements PlaybackEngine {
+    private host;
+    private mount;
+    private canvas;
+    private ctx;
+    /** Only created when constructed with `debug: true`. */
+    private badge;
+    private videos;
+    private project;
+    private currentClipId;
+    private playing;
+    private timeMs;
+    private rafHandle;
+    private lastFrameTs;
+    private paintedFrames;
+    onTimeUpdate?: (ms: Ms) => void;
+    onEnded?: () => void;
+    onError?: (err: Error) => void;
+    onReady?: () => void;
+    onSourceMetadata?: (sourceId: string, durationMs: Ms) => void;
+    constructor(opts: CanvasCompositorEngineOptions);
+    setProject(next: Project): void;
+    play(): void;
+    pause(): void;
+    isPlaying(): boolean;
+    getTime(): Ms;
+    seek(timeMs: Ms): void;
+    destroy(): void;
+    private syncSources;
+    private activate;
+    private seekVideoToClipOffset;
+    private clipById;
+    private clipAtTime;
+    private nextClipAfterTime;
+    private totalDuration;
+    private resizeCanvas;
+    private startTickLoop;
+    private stopTickLoop;
+    private advance;
+    /**
+     * One paint per rAF — clears the canvas, draws the current active
+     * video frame letterboxed to fit, then refreshes the HUD. Done
+     * unconditionally (not just on `playing`) so the HUD frame counter
+     * and the seek preview both update when paused.
+     */
+    private paint;
+    private updateBadge;
+}
+/** Factory shorthand for `Editor.create({ playbackEngine })`. */
+declare const canvasCompositorEngineFactory: PlaybackEngineFactory;
 
 interface EditorOptions {
     /** Host element to mount the editor into. Will be wiped on init. */
@@ -20,6 +162,38 @@ interface EditorOptions {
      * Call `editor.setLocale(...)` to switch at runtime.
      */
     locale?: Partial<Locale>;
+    /**
+     * Optional factory for a custom playback engine. Receives the
+     * editor's preview host element + the initial project, returns
+     * anything satisfying `PlaybackEngine`. Defaults to the built-in
+     * `HtmlVideoEngine` (one hidden `<video>` per source, swap on
+     * boundaries). Hosts that need frame-accurate editing, multi-track
+     * compositing, transitions, etc. pass a `WebCodecsEngine` factory
+     * (v0.6+) or their own.
+     */
+    playbackEngine?: PlaybackEngineFactory;
+    /**
+     * Pixel height of each track row in the timeline (default 56). Lower
+     * values (~32–40) shrink the timeline footprint for small viewports
+     * where the default crowds out the preview. Reasonable range:
+     * [28, 96]. Applied process-wide via `setTimelineMetrics` — multi-
+     * editor mounts share the value.
+     */
+    trackHeight?: number;
+    /**
+     * Pixel height of the timeline ruler / time-label strip (default 24).
+     * Pair with `trackHeight` to compact the whole timeline. Reasonable
+     * range: [18, 36].
+     */
+    rulerHeight?: number;
+    /**
+     * Pixel height of the whole bottom timeline area (default 240). The
+     * canvas inside fills 100% of this and shows a vertical scrollbar
+     * when there are more tracks than fit. Lower this (~120–180) on
+     * small viewports so the preview takes more of the editor's height.
+     * Reasonable range: [120, 480].
+     */
+    timelineHeight?: number;
 }
 interface EditorEventMap {
     /** Emitted whenever the project mutates. */
@@ -282,10 +456,30 @@ declare function normalizeProject(project: Project): Project;
  */
 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;
+/** Visual constants — kept here so draw + hit-test share one source of truth.
+ *  The two row-height values are `let` rather than `const` so hosts can
+ *  shrink the timeline footprint for small screens via
+ *  `setTimelineMetrics(...)`. ES module live bindings mean every importer
+ *  sees the updated value automatically. */
+declare let TRACK_HEIGHT: number;
+declare let RULER_HEIGHT: number;
 declare const HEADER_WIDTH = 96;
+/**
+ * Override the default timeline row + ruler heights. Process-wide — call
+ * before / during editor construction. Useful when the editor is mounted
+ * in a small viewport (e.g. side-by-side panel on a laptop) and the
+ * default 56px tracks crowd out the preview.
+ *
+ * Reasonable ranges: trackHeight ∈ [28, 96], rulerHeight ∈ [18, 36].
+ * Anything smaller leaves no room for the clip label or the time ticks.
+ *
+ * Multi-editor mounts share these values. If you have two editors with
+ * different needs, agree on the smaller one or remount on switch.
+ */
+declare function setTimelineMetrics(opts: {
+    trackHeight?: number;
+    rulerHeight?: number;
+}): void;
 
 /**
  * Public options for the standalone `Timeline` component. The class
@@ -532,4 +726,4 @@ declare class Timeline {
     private applySnap;
 }
 
-export { Clip, Editor, type EditorApi, type EditorEventMap, type EditorEventName, type EditorOptions, HEADER_WIDTH, Locale, MediaSource, Ms, Project, RULER_HEIGHT, TRACK_HEIGHT, Theme, Timeline, type TimelineOptions, Track, createEmptyProject, createId, normalizeProject };
+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 };