@vplayer/core 0.1.0

package/dist/media-capabilities.d.ts

@@ -0,0 +1,14 @@
+export interface MediaCapabilitiesSnapshot {
+    mse: boolean;
+    nativeHls: boolean;
+    fullscreen: boolean;
+    pictureInPicture: boolean;
+    textTracks: boolean;
+}
+export declare function canUseMSE(): boolean;
+export declare function canUseNativeHLS(video?: HTMLVideoElement | null): boolean;
+export declare function canUseFullscreen(container?: HTMLElement | null): boolean;
+export declare function canUsePictureInPicture(video?: HTMLVideoElement | null): boolean;
+export declare function canUseTextTracks(video?: HTMLVideoElement | null): boolean;
+export declare function getMediaCapabilities(video?: HTMLVideoElement | null, container?: HTMLElement | null): MediaCapabilitiesSnapshot;
+export declare function isFiniteDuration(value: number): boolean;

package/dist/media-engine/base-engine.d.ts

@@ -0,0 +1,43 @@
+/**
+ * BaseMediaEngine — Shared boilerplate for MediaEngine implementations.
+ *
+ * All playback state is read from the underlying HTMLVideoElement.
+ * Subclasses override load() and destroy() for custom source handling
+ * (HLS.js, DASH.js, etc.) and use this.emit() for custom events.
+ */
+import type { MediaEngine, MediaEngineError, MediaEngineEvent, MediaEngineEventHandler } from './types';
+export declare abstract class BaseMediaEngine implements MediaEngine {
+    readonly element: HTMLVideoElement;
+    protected destroyed: boolean;
+    private listeners;
+    private domListeners;
+    constructor(video: HTMLVideoElement);
+    play(): Promise<void>;
+    pause(): void;
+    seek(time: number): void;
+    setVolume(volume: number): void;
+    setMuted(muted: boolean): void;
+    setPlaybackRate(rate: number): void;
+    setLooping(loop: boolean): void;
+    load(): void;
+    requestPictureInPicture(): Promise<void>;
+    exitPictureInPicture(): Promise<void>;
+    screenshot(): Promise<Blob | null>;
+    get currentTime(): number;
+    get duration(): number;
+    get volume(): number;
+    get muted(): boolean;
+    get playbackRate(): number;
+    get paused(): boolean;
+    get ended(): boolean;
+    get looping(): boolean;
+    get buffered(): TimeRanges;
+    get videoWidth(): number;
+    get videoHeight(): number;
+    get error(): MediaEngineError | null;
+    on(event: MediaEngineEvent, handler: MediaEngineEventHandler): () => void;
+    protected emit(event: MediaEngineEvent, ...args: any[]): void;
+    private attachDOMListeners;
+    private detachDOMListeners;
+    destroy(): void;
+}

package/dist/media-engine/dash-engine.d.ts

@@ -0,0 +1,32 @@
+/**
+ * DashMediaEngine — MediaEngine backed by dash.js (MPEG-DASH).
+ *
+ * Uses dash.js to play DASH streams via MSE.
+ *
+ * Usage:
+ * ```ts
+ * const player = createPlayer({
+ *   engine: (video) => new DashMediaEngine(video, {
+ *     src: 'https://example.com/stream.mpd',
+ *   }),
+ * })
+ * ```
+ */
+import type { MediaPlayerSettingClass } from 'dashjs';
+import { BaseMediaEngine } from './base-engine';
+export interface DashMediaEngineOptions {
+    /** Source URL (.mpd manifest). */
+    src?: string;
+    /** Optional dash.js settings (MediaPlayerSettingClass). */
+    dashConfig?: MediaPlayerSettingClass;
+}
+export declare class DashMediaEngine extends BaseMediaEngine {
+    private dashPlayer;
+    private dashSrc;
+    private dashConfig?;
+    constructor(video: HTMLVideoElement, options?: DashMediaEngineOptions);
+    private initDash;
+    private initDashAsync;
+    load(): void;
+    destroy(): void;
+}

package/dist/media-engine/hls-engine.d.ts

@@ -0,0 +1,32 @@
+/**
+ * HlsMediaEngine — MediaEngine backed by hls.js.
+ *
+ * Uses HLS.js to play HTTP Live Streaming (HLS) sources via MSE.
+ * Falls through to native playback in browsers with native HLS support (Safari).
+ *
+ * Usage:
+ * ```ts
+ * const player = createPlayer({
+ *   engine: (video) => new HlsMediaEngine(video, {
+ *     src: 'https://example.com/stream.m3u8',
+ *   }),
+ * })
+ * ```
+ */
+import { BaseMediaEngine } from './base-engine';
+export interface HlsMediaEngineOptions {
+    /** Source URL (.m3u8 playlist). */
+    src?: string;
+    /** Optional hls.js configuration (Partial<import('hls.js').HlsConfig>). */
+    hlsConfig?: Partial<import('hls.js').HlsConfig>;
+}
+export declare class HlsMediaEngine extends BaseMediaEngine {
+    private hls;
+    private hlsSrc;
+    private hlsConfig;
+    constructor(video: HTMLVideoElement, options?: HlsMediaEngineOptions);
+    private initHls;
+    private initHlsAsync;
+    load(): void;
+    destroy(): void;
+}

package/dist/media-engine/index.d.ts

@@ -0,0 +1,7 @@
+export type { MediaEngine, MediaEngineDimensions, MediaEngineError, MediaEngineEvent, MediaEngineEventHandler, } from './types';
+export { BaseMediaEngine } from './base-engine';
+export { NativeVideoEngine } from './native-engine';
+export { HlsMediaEngine } from './hls-engine';
+export type { HlsMediaEngineOptions } from './hls-engine';
+export { DashMediaEngine } from './dash-engine';
+export type { DashMediaEngineOptions } from './dash-engine';

package/dist/media-engine/native-engine.d.ts

@@ -0,0 +1,9 @@
+/**
+ * NativeVideoEngine — MediaEngine backed by an HTMLVideoElement.
+ *
+ * The default engine used by createPlayer() when no custom engine is provided.
+ * Delegates all playback to the native <video> element.
+ */
+import { BaseMediaEngine } from './base-engine';
+export declare class NativeVideoEngine extends BaseMediaEngine {
+}

package/dist/media-engine/types.d.ts

@@ -0,0 +1,50 @@
+/**
+ * MediaEngine — Strategy interface for media playback.
+ *
+ * Abstracts away the underlying media source (native <video>, HLS, DASH, etc.)
+ * so that the player core operates against a stable contract.
+ *
+ * Implementations own their event listeners and must clean up on destroy().
+ */
+export interface MediaEngineDimensions {
+    width: number;
+    height: number;
+}
+export interface MediaEngineError {
+    message: string;
+    code?: number;
+}
+/** Events emitted by every MediaEngine implementation. */
+export type MediaEngineEvent = 'play' | 'pause' | 'ended' | 'timeupdate' | 'loadedmetadata' | 'loadeddata' | 'durationchange' | 'progress' | 'seeking' | 'seeked' | 'waiting' | 'stalled' | 'playing' | 'canplay' | 'canplaythrough' | 'volumechange' | 'ratechange' | 'playblocked' | 'error' | (string & {});
+export type MediaEngineEventHandler = (...args: any[]) => void;
+export interface MediaEngine {
+    /** The underlying media element (e.g. HTMLVideoElement). */
+    readonly element: HTMLElement;
+    play(): Promise<void>;
+    pause(): void;
+    seek(time: number): void;
+    setVolume(volume: number): void;
+    setMuted(muted: boolean): void;
+    setPlaybackRate(rate: number): void;
+    setLooping(loop: boolean): void;
+    /** Reload the current source. */
+    load(): void;
+    requestPictureInPicture(): Promise<void>;
+    exitPictureInPicture(): Promise<void>;
+    /** Capture a still frame from the current video frame. */
+    screenshot(): Promise<Blob | null>;
+    readonly currentTime: number;
+    readonly duration: number;
+    readonly volume: number;
+    readonly muted: boolean;
+    readonly playbackRate: number;
+    readonly paused: boolean;
+    readonly ended: boolean;
+    readonly looping: boolean;
+    readonly buffered: TimeRanges;
+    readonly videoWidth: number;
+    readonly videoHeight: number;
+    readonly error: MediaEngineError | null;
+    on(event: MediaEngineEvent, handler: MediaEngineEventHandler): () => void;
+    destroy(): void;
+}

package/dist/player.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @vplayer/core — Player factory.
+ *
+ * Architecture:
+ *   createPlayer() → PlayerInstance
+ *     ├── store        → Reactive state (TanStack Store)
+ *     ├── engine       → Media playback abstraction (MediaEngine)
+ *     ├── events       → Typed event bus for plugin communication
+ *     ├── storage      → Persistence layer (localStorage + fallback)
+ *     ├── i18n         → Internationalization
+ *     └── hotkeys      → Keyboard shortcut registry
+ *
+ * The player delegates all media I/O to a swappable MediaEngine.
+ * At mount time, a NativeVideoEngine wraps the <video> element.
+ * Custom engines (HLS, DASH, mock) can be injected for testing or
+ * advanced playback scenarios.
+ */
+import type { PlayerOptions, PlayerInstance } from './types';
+export declare function createPlayer(options: PlayerOptions): PlayerInstance;

package/dist/plugin-api.d.ts

@@ -0,0 +1,86 @@
+import type { Store } from '@tanstack/store';
+import type { EventBus } from './event-bus';
+import type { HotkeyRegistry, HotkeyBinding } from './hotkey-registry';
+import type { I18n } from './i18n';
+import type { Storage } from './storage';
+export interface RemoteRef {
+    play: () => void;
+    pause: () => void;
+    togglePlay: () => void;
+    seek: (time: number) => void;
+    skip: (seconds: number) => void;
+    setVolume: (v: number) => void;
+    toggleMute: () => void;
+    setPlaybackRate: (rate: number) => void;
+    toggleFullscreen: () => void;
+    togglePiP: () => void;
+    takeScreenshot: () => void;
+    setFlip: (flip: FlipState) => void;
+    setAspectRatio: (ratio: AspectRatioState) => void;
+    cycleAspectRatio: () => void;
+    toggleLoop: () => void;
+    toggleInfoPanel: () => void;
+}
+export interface PlayerContextRef {
+    containerRef: {
+        readonly current: HTMLDivElement | null;
+    };
+    videoRef: {
+        readonly current: HTMLVideoElement | null;
+    };
+}
+export interface ControlRegistration {
+    name: string;
+    position: 'left' | 'right' | 'top' | 'center';
+    index: number;
+    render: unknown;
+}
+export interface SettingItem {
+    label: string;
+    value: string;
+}
+export interface SettingRegistration {
+    name: string;
+    label: string;
+    items?: SettingItem[];
+    render?: unknown;
+}
+export interface LayerRegistration {
+    name: string;
+    render: unknown;
+}
+export interface ContextMenuItem {
+    label: string;
+    onAction: () => void;
+    separator?: boolean;
+    disabled?: boolean;
+}
+export interface ContextMenuRegistration {
+    name: string;
+    items: ContextMenuItem[];
+}
+export type FlipState = 'normal' | 'horizontal' | 'vertical';
+export type AspectRatioState = 'default' | '16:9' | '4:3' | '21:9' | 'cover' | 'fill';
+export interface PluginAPI {
+    readonly name: string;
+    readonly store: Store<any>;
+    readonly remote: RemoteRef;
+    readonly events: EventBus;
+    readonly storage: Storage;
+    readonly hotkeys: HotkeyRegistry;
+    readonly i18n: I18n;
+    readonly context: PlayerContextRef;
+    addControl(def: ControlRegistration): () => void;
+    removeControl(name: string): void;
+    addSetting(def: SettingRegistration): () => void;
+    removeSetting(name: string): void;
+    addLayer(def: LayerRegistration): () => void;
+    removeLayer(name: string): void;
+    addHotkey(binding: HotkeyBinding): () => void;
+    addContextMenuItems(items: ContextMenuItem[]): () => void;
+    notify(message: string, duration?: number): void;
+}
+export interface PlayerPlugin {
+    name: string;
+    setup?: (api: PluginAPI) => void | (() => void);
+}

package/dist/source-resolver.d.ts

@@ -0,0 +1,10 @@
+import type { MediaEngine } from './media-engine';
+import type { PlayerOptions } from './types';
+export type SourceKind = 'native' | 'hls' | 'dash' | 'unknown';
+export interface PlayerSource {
+    src: string;
+    type?: string;
+}
+export declare function detectSourceKind(source: PlayerSource): SourceKind;
+export declare function toPlayerSource(options: Pick<PlayerOptions, 'src' | 'type'>): PlayerSource;
+export declare function createResolvedMediaEngine(video: HTMLVideoElement, options: Pick<PlayerOptions, 'src' | 'type' | 'engine' | 'hlsConfig' | 'dashConfig'>): MediaEngine;

package/dist/state/slices.d.ts

@@ -0,0 +1,134 @@
+/**
+ * State Slices — Logical groupings of MediaState properties.
+ *
+ * These types DOCUMENT the slice boundaries within the flat MediaState.
+ * At runtime the store keeps a flat state for backward compat, but the
+ * slice types make ownership clear and enable future per-slice subscriptions.
+ *
+ * Migration path toward separate sub-stores:
+ *   1. Define slices here (done ✓)
+ *   2. Use createMediaStore() for initialization (done ✓)
+ *   3. Eventually migrate to separate Store instances per slice
+ */
+import { Store } from '@tanstack/store';
+import type { MediaCapabilitiesSnapshot } from '../media-capabilities';
+import type { ControlRegistration, ContextMenuItem, FlipState, AspectRatioState } from '../plugin-api';
+import type { LayerRegistration, SettingRegistration } from '../plugin-api';
+import type { PlayerSource } from '../source-resolver';
+import type { SubtitleTrack, ThumbnailCue } from '../subtitle-parser';
+export type PlaybackStatus = 'idle' | 'loading' | 'ready' | 'playing' | 'paused' | 'buffering' | 'seeking' | 'ended' | 'error';
+export interface MediaSlice {
+    status: PlaybackStatus;
+    source: PlayerSource | null;
+    isPlaying: boolean;
+    isPaused: boolean;
+    isBuffering: boolean;
+    isEnded: boolean;
+    currentTime: number;
+    duration: number;
+    bufferedPercent: number;
+    playbackRate: number;
+    isLive: boolean;
+}
+export interface AudioSlice {
+    volume: number;
+    isMuted: boolean;
+}
+export interface PreferencesSlice {
+    isLooping: boolean;
+    flip: FlipState;
+    aspectRatio: AspectRatioState;
+    activeSubtitle: SubtitleTrack | null;
+    subtitleTracks: SubtitleTrack[];
+    activeQuality: string;
+    qualities: string[];
+}
+export interface UISlice {
+    controlsVisible: boolean;
+    capabilities: MediaCapabilitiesSnapshot;
+    isFullscreen: boolean;
+    infoPanelVisible: boolean;
+    notification: {
+        message: string;
+        duration: number;
+    } | null;
+}
+export interface PluginSlice {
+    controls: ControlRegistration[];
+    settings: SettingRegistration[];
+    layers: LayerRegistration[];
+    contextMenuItems: ContextMenuItem[];
+    contextMenuEnabled: boolean;
+}
+export interface ThumbnailSlice {
+    thumbnailCues: ThumbnailCue[];
+}
+export interface ErrorSlice {
+    error: {
+        message: string;
+        reconnectAttempt: number;
+        isReconnecting: boolean;
+    } | null;
+}
+/**
+ * Full MediaState — flat at runtime, logically organized here.
+ *
+ * Consumers can reference MediaState or individual slices depending
+ * on how granular they need to be.
+ */
+export interface MediaState extends MediaSlice, AudioSlice, PreferencesSlice, UISlice, PluginSlice, ThumbnailSlice, ErrorSlice {
+}
+export type PlayerStore = Store<MediaState>;
+export declare function createMediaStore(): PlayerStore;
+export declare function getInitialMediaState(): MediaState;
+export declare const selectMedia: (s: MediaState) => {
+    status: PlaybackStatus;
+    source: PlayerSource | null;
+    isPlaying: boolean;
+    isPaused: boolean;
+    isBuffering: boolean;
+    isEnded: boolean;
+    currentTime: number;
+    duration: number;
+    bufferedPercent: number;
+    playbackRate: number;
+    isLive: boolean;
+};
+export declare const selectAudio: (s: MediaState) => {
+    volume: number;
+    isMuted: boolean;
+};
+export declare const selectPreferences: (s: MediaState) => {
+    isLooping: boolean;
+    flip: FlipState;
+    aspectRatio: AspectRatioState;
+    activeSubtitle: SubtitleTrack | null;
+    subtitleTracks: SubtitleTrack[];
+    activeQuality: string;
+    qualities: string[];
+};
+export declare const selectUI: (s: MediaState) => {
+    controlsVisible: boolean;
+    capabilities: MediaCapabilitiesSnapshot;
+    isFullscreen: boolean;
+    infoPanelVisible: boolean;
+    notification: {
+        message: string;
+        duration: number;
+    } | null;
+};
+export declare const selectPlugins: (s: MediaState) => {
+    controls: ControlRegistration[];
+    settings: SettingRegistration[];
+    layers: LayerRegistration[];
+    contextMenuItems: ContextMenuItem[];
+    contextMenuEnabled: boolean;
+};
+export declare const selectThumbnails: (s: MediaState) => {
+    thumbnailCues: ThumbnailCue[];
+};
+export declare const selectError: (s: MediaState) => {
+    message: string;
+    reconnectAttempt: number;
+    isReconnecting: boolean;
+} | null;

package/dist/storage.d.ts

@@ -0,0 +1,25 @@
+export interface StorageOptions {
+    prefix?: string;
+}
+export declare class Storage {
+    private fallback;
+    private prefix;
+    constructor(options?: StorageOptions);
+    private fullKey;
+    get<T = unknown>(key: string): T | undefined;
+    set<T = unknown>(key: string, value: T): void;
+    remove(key: string): void;
+    clear(): void;
+}
+/** Pre-defined persistence keys */
+export declare const STORAGE_KEYS: {
+    readonly VOLUME: "volume";
+    readonly MUTED: "muted";
+    readonly PLAYBACK_RATE: "playbackRate";
+    readonly SUBTITLE_LANG: "subtitleLang";
+    readonly QUALITY: "quality";
+    readonly PLAYBACK_PROGRESS: "playbackProgress";
+    readonly LOOP: "loop";
+    readonly FLIP: "flip";
+    readonly ASPECT_RATIO: "aspectRatio";
+};

package/dist/subtitle-parser.d.ts

@@ -0,0 +1,41 @@
+export interface SubtitleCue {
+    index: number;
+    start: number;
+    end: number;
+    text: string;
+}
+export interface SubtitleTrack {
+    src: string;
+    lang: string;
+    label: string;
+    default?: boolean;
+}
+/** Parse HH:MM:SS.mmm or HH:MM:SS,mmm timestamp → total seconds */
+export declare function parseTimestamp(ts: string): number;
+/** Parse SRT format text into cues */
+export declare function parseSRT(content: string): SubtitleCue[];
+/** Parse VTT format text into cues */
+export declare function parseVTT(content: string): SubtitleCue[];
+/** Fetch and parse subtitles from URL */
+export declare function fetchSubtitles(track: SubtitleTrack): Promise<SubtitleCue[]>;
+/** Get active cue at a given time */
+export declare function getActiveCue(cues: SubtitleCue[], time: number): SubtitleCue | null;
+export interface ThumbnailCue {
+    start: number;
+    end: number;
+    /** Sprite sheet image URL */
+    src: string;
+    /** Crop x on sprite */
+    x: number;
+    /** Crop y on sprite */
+    y: number;
+    /** Crop width */
+    w: number;
+    /** Crop height */
+    h: number;
+}
+/** Parse a VTT thumbnail sprite file into cues */
+export declare function parseThumbnailVTT(content: string): ThumbnailCue[];
+export declare function fetchThumbnails(url: string, signal?: AbortSignal): Promise<ThumbnailCue[]>;
+/** Find the matching thumbnail cue for a given time */
+export declare function getThumbnailAtTime(cues: ThumbnailCue[], time: number): ThumbnailCue | null;