@aicut/core 0.4.3 → 0.5.0

package/dist/types-CHplD9V5.d.cts

@@ -0,0 +1,70 @@
+/**
+ * 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;
+}
+
+export type { Clip as C, Ms as M, Project as P, Track as T, MediaSource as a, Theme as b };

package/dist/types-CHplD9V5.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 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;
+}
+
+export type { Clip as C, Ms as M, Project as P, Track as T, MediaSource as a, Theme as b };

package/dist/types-DvKlxylu.d.cts

@@ -0,0 +1,75 @@
+import { P as Project, M as Ms } from './types-CHplD9V5.cjs';
+
+/**
+ * Construction context the Editor hands to a playback engine. The
+ * engine mounts itself into `host` (typically the editor's preview
+ * element) and owns whatever DOM / canvas / video elements it needs.
+ */
+interface PlaybackEngineOptions {
+    /** Mount point. Engine appends its preview surface here. */
+    host: HTMLElement;
+    /** Initial project — engine pre-warms sources, etc. */
+    project: Project;
+}
+/**
+ * The contract every preview engine satisfies. Editor talks ONLY
+ * through this surface — implementations are interchangeable.
+ *
+ * Built-in implementations:
+ *   - `HtmlVideoEngine`  default; one HTMLVideoElement per source,
+ *                        swap on clip boundaries. Zero deps,
+ *                        GPU-accelerated decode by the browser, but
+ *                        seek snaps to keyframes (browser controls
+ *                        the decode pipeline).
+ *   - `WebCodecsEngine`  opt-in (v0.6+); manual VideoDecoder loop +
+ *                        canvas blit. Frame-accurate seek; will
+ *                        underpin multi-track compositing, transitions,
+ *                        and shaders in later versions.
+ *
+ * Hosts can ship their own implementation (e.g., a WebGL compositor,
+ * a WebRTC stream consumer, a desktop-wrapper IPC bridge) and inject
+ * it via `Editor.create({ playbackEngine: myFactory })`.
+ */
+interface PlaybackEngine {
+    /** Replace the project. Engine re-warms sources + re-resolves the
+     *  active clip for the current playhead. Idempotent. */
+    setProject(next: Project): void;
+    play(): void;
+    pause(): void;
+    isPlaying(): boolean;
+    /** Current playhead (ms from project start). */
+    getTime(): Ms;
+    /** Move the playhead. Engine clamps to [0, totalDuration]. */
+    seek(timeMs: Ms): void;
+    /** Free all resources (DOM nodes, decoders, AudioContexts, rAF). */
+    destroy(): void;
+    /** 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. */
+    onEnded?: () => void;
+    /** Decode / network / capability failures. */
+    onError?: (err: Error) => void;
+    /**
+     * Fired the first time a fresh playback target is "ready to play"
+     * — analogue of HTMLMediaElement's `loadedmetadata`. Editor uses
+     * it to gate scaling / auto-fit work.
+     */
+    onReady?: () => void;
+    /**
+     * Fired when an individual source's duration becomes known. Editor
+     * folds this into the project model so the timeline can size clips
+     * correctly even when the host didn't ship a `duration` upfront.
+     */
+    onSourceMetadata?: (sourceId: string, durationMs: Ms) => void;
+}
+/**
+ * A factory that builds an engine for a given mount/project. Hosts
+ * pass one of these to `Editor.create({ playbackEngine })` to swap
+ * implementations. The factory shape — rather than a class reference
+ * — keeps Editor decoupled from constructor signatures and lets
+ * factories close over host-side configuration (auth tokens, render
+ * backend URL, custom shaders, etc.) without polluting the interface.
+ */
+type PlaybackEngineFactory = (opts: PlaybackEngineOptions) => PlaybackEngine;
+
+export type { PlaybackEngine as P, PlaybackEngineOptions as a, PlaybackEngineFactory as b };

package/dist/types-rwZx6FxE.d.ts

@@ -0,0 +1,75 @@
+import { P as Project, M as Ms } from './types-CHplD9V5.js';
+
+/**
+ * Construction context the Editor hands to a playback engine. The
+ * engine mounts itself into `host` (typically the editor's preview
+ * element) and owns whatever DOM / canvas / video elements it needs.
+ */
+interface PlaybackEngineOptions {
+    /** Mount point. Engine appends its preview surface here. */
+    host: HTMLElement;
+    /** Initial project — engine pre-warms sources, etc. */
+    project: Project;
+}
+/**
+ * The contract every preview engine satisfies. Editor talks ONLY
+ * through this surface — implementations are interchangeable.
+ *
+ * Built-in implementations:
+ *   - `HtmlVideoEngine`  default; one HTMLVideoElement per source,
+ *                        swap on clip boundaries. Zero deps,
+ *                        GPU-accelerated decode by the browser, but
+ *                        seek snaps to keyframes (browser controls
+ *                        the decode pipeline).
+ *   - `WebCodecsEngine`  opt-in (v0.6+); manual VideoDecoder loop +
+ *                        canvas blit. Frame-accurate seek; will
+ *                        underpin multi-track compositing, transitions,
+ *                        and shaders in later versions.
+ *
+ * Hosts can ship their own implementation (e.g., a WebGL compositor,
+ * a WebRTC stream consumer, a desktop-wrapper IPC bridge) and inject
+ * it via `Editor.create({ playbackEngine: myFactory })`.
+ */
+interface PlaybackEngine {
+    /** Replace the project. Engine re-warms sources + re-resolves the
+     *  active clip for the current playhead. Idempotent. */
+    setProject(next: Project): void;
+    play(): void;
+    pause(): void;
+    isPlaying(): boolean;
+    /** Current playhead (ms from project start). */
+    getTime(): Ms;
+    /** Move the playhead. Engine clamps to [0, totalDuration]. */
+    seek(timeMs: Ms): void;
+    /** Free all resources (DOM nodes, decoders, AudioContexts, rAF). */
+    destroy(): void;
+    /** 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. */
+    onEnded?: () => void;
+    /** Decode / network / capability failures. */
+    onError?: (err: Error) => void;
+    /**
+     * Fired the first time a fresh playback target is "ready to play"
+     * — analogue of HTMLMediaElement's `loadedmetadata`. Editor uses
+     * it to gate scaling / auto-fit work.
+     */
+    onReady?: () => void;
+    /**
+     * Fired when an individual source's duration becomes known. Editor
+     * folds this into the project model so the timeline can size clips
+     * correctly even when the host didn't ship a `duration` upfront.
+     */
+    onSourceMetadata?: (sourceId: string, durationMs: Ms) => void;
+}
+/**
+ * A factory that builds an engine for a given mount/project. Hosts
+ * pass one of these to `Editor.create({ playbackEngine })` to swap
+ * implementations. The factory shape — rather than a class reference
+ * — keeps Editor decoupled from constructor signatures and lets
+ * factories close over host-side configuration (auth tokens, render
+ * backend URL, custom shaders, etc.) without polluting the interface.
+ */
+type PlaybackEngineFactory = (opts: PlaybackEngineOptions) => PlaybackEngine;
+
+export type { PlaybackEngine as P, PlaybackEngineOptions as a, PlaybackEngineFactory as b };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aicut/core",
-  "version": "0.4.3",
-  "description": "Framework-agnostic core for the AiCut video editor — canvas timeline, data model, HTML5 playback engine, plus an opt-in 3D lighting picker.",
+  "version": "0.5.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>",
   "homepage": "https://github.com/ziqiangai/AiCut#readme",
@@ -57,6 +57,11 @@
       "import": "./dist/lighting/index.js",
       "require": "./dist/lighting/index.cjs"
     },
+    "./webcodecs": {
+      "types": "./dist/playback/webcodecs/index.d.ts",
+      "import": "./dist/playback/webcodecs/index.js",
+      "require": "./dist/playback/webcodecs/index.cjs"
+    },
     "./styles.css": "./styles/theme.css"
   },
   "files": [
@@ -65,12 +70,16 @@
     "README.md"
   ],
   "dependencies": {
+    "mp4box": "^2.4.1",
     "three": "^0.159.0"
   },
   "devDependencies": {
     "@types/three": "^0.159.0",
+    "@vitest/coverage-v8": "^4.1.9",
+    "happy-dom": "^20.10.6",
     "tsup": "^8.3.5",
-    "typescript": "^5.7.2"
+    "typescript": "^5.7.2",
+    "vitest": "^4.1.9"
   },
   "publishConfig": {
     "access": "public"
@@ -78,6 +87,8 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
 }

package/styles/theme.css

@@ -430,8 +430,13 @@
   position: relative;
   flex: 0 0 auto;
   background: var(--aicut-controls-bg);
-  height: 240px;
-  min-height: 200px;
+  /* Override via EditorOptions.timelineHeight (sets the custom property
+     on the root container). Default 240 matches historical behavior;
+     small-viewport hosts often want 140–180. min-height is intentionally
+     a hair below the smallest sensible default so the option can dip
+     into the compact range without the min winning. */
+  height: var(--aicut-timeline-height, 240px);
+  min-height: 120px;
   overflow: hidden;
 }
 

package/dist/types-C95koNwJ.d.cts

@@ -1,120 +0,0 @@
-/**
- * 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;
-}
-
-export { type Clip as C, type Locale as L, type Ms as M, type Project as P, type Track as T, type MediaSource as a, type Theme as b, localeZh as c, formatLabel as f, localeEn as l, mergeLocale as m };

package/dist/types-C95koNwJ.d.ts

@@ -1,120 +0,0 @@
-/**
- * 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;
-}
-
-export { type Clip as C, type Locale as L, type Ms as M, type Project as P, type Track as T, type MediaSource as a, type Theme as b, localeZh as c, formatLabel as f, localeEn as l, mergeLocale as m };