@f8team/reel-core 1.0.3 → 1.0.5

package/dist/index.d.cts

@@ -58,7 +58,7 @@ interface CreateStoreOptions<_T> {
  * Golden cases: G13 (unauthorized HLS), every error path in G1..G16.
  */
 /** Stable error codes. The string literal IS the public contract. */
-type PlayerErrorCode = "source" | "network" | "decode" | "unauthorized" | "unsupported" | "internal";
+type PlayerErrorCode = "source" | "network" | "decode" | "unauthorized" | "unsupported" | "hls-fragment-loop" | "internal";
 /**
  * Structured player error. Adapters render the message; plugins can inspect
  * `code`, `status`, and `retryable` to decide on retry/UI strategy.
@@ -132,12 +132,12 @@ interface ThumbnailsDescriptor {
 /**
  * The kind of source. `auto` lets the registry pick.
  *
- * - `hls` — HLS m3u8 manifest, dispatched to `hls.js` (or native on Safari).
- * - `mp4` — Progressive MP4/WebM, dispatched to the native engine.
- * - `youtube` — YouTube IFrame API.
- * - `dash` — MPEG-DASH (reserved for a future dash provider).
- * - `native` — Force the native engine even if the URL looks like HLS (G4 Safari escape).
- * - `auto` — Detect from the URL via `looksLikeHls` / `detectSourceType`.
+ * - `hls` - HLS m3u8 manifest, dispatched to `hls.js` (or native on Safari).
+ * - `mp4` - Progressive MP4/WebM, dispatched to the native engine.
+ * - `youtube` - YouTube IFrame API.
+ * - `dash` - MPEG-DASH (reserved for a future dash provider).
+ * - `native` - Force the native engine even if the URL looks like HLS (G4 Safari escape).
+ * - `auto` - Detect from the URL via `looksLikeHls` / `detectSourceType`.
  */
 type SourceType = "auto" | "hls" | "mp4" | "youtube" | "dash" | "native";
 /**
@@ -154,8 +154,8 @@ interface SourceDescriptor {
     /**
      * Cookie / credentials policy for HLS XHRs.
      *
-     * - `boolean` — sent for every request.
-     * - `(url) => boolean` — predicate (e.g. allowlist `https://api-gateway*`, see G7, G13).
+     * - `boolean` - sent for every request.
+     * - `(url) => boolean` - predicate scoped to a trusted API origin/path (see G7, G13).
      */
     withCredentials?: boolean | ((url: string) => boolean);
     /** Subtitle tracks to attach (G1, G15). */
@@ -222,9 +222,9 @@ interface SourceProvider {
     /**
      * Decide whether this provider can handle the given source.
      *
-     * - `true` — definite match.
-     * - `"maybe"` — handle if no `true` match exists (used by the native fallback).
-     * - `false` — skip.
+     * - `true` - definite match.
+     * - `"maybe"` - handle if no `true` match exists (used by the native fallback).
+     * - `false` - skip.
      */
     canHandle(source: SourceDescriptor): boolean | "maybe";
     /** Construct a fresh loader. Called once per source attach. */
@@ -469,6 +469,13 @@ interface Player {
     dispose(): void;
 }
 
+/** Synchronous source normalization hook applied before provider resolution. */
+type SourceTransform = (source: SourceDescriptor) => SourceDescriptor;
+/** Media element and container owned by one player attachment. */
+interface PluginMediaAttachment {
+    video: HTMLVideoElement;
+    container: Element;
+}
 /**
  * Command registry shared between the player and plugins. Commands are the
  * extension point for keyboard handlers, plugin contributions, and UI buttons.
@@ -505,6 +512,22 @@ interface PluginHost {
     };
     /** Shared command registry. Plugins MUST namespace their commands. */
     commands: CommandRegistry;
+    /**
+     * Register a synchronous source transform. Core applies transforms before
+     * the source is stored or passed to a provider, including the initial
+     * source supplied in `PlayerOptions`.
+     *
+     * Optional for compatibility with custom test hosts built against earlier
+     * versions of the contract.
+     */
+    sources?: {
+        transform(transform: SourceTransform): () => void;
+    };
+    /** Player-scoped media ownership and attach/detach lifecycle. */
+    media?: {
+        get(): PluginMediaAttachment | null;
+        subscribe(listener: (attachment: PluginMediaAttachment | null) => void): () => void;
+    };
     /** Read-only state. */
     store: ReadableStore<PlayerState>;
     /** Emit a custom plugin event. Use the `${plugin}:${verb}` namespace. */
@@ -639,7 +662,7 @@ interface PlayerOptions {
 }
 
 /**
- * `createPlayer(options)` — wires every piece of `@f8team/reel-core` into a
+ * `createPlayer(options)` - wires every piece of `@f8team/reel-core` into a
  * single `Player`. The factory is the one and only public entry point.
  *
  * Responsibilities:
@@ -658,7 +681,7 @@ interface PlayerOptions {
  * unit tests.
  */
 
-/** @internal — extra knobs surfaced for tests and adapters. */
+/** @internal - extra knobs surfaced for tests and adapters. */
 interface CreatePlayerInternalOptions {
     /** Override the microtask scheduler for the store. Tests use this. */
     storeOptions?: CreateStoreOptions<PlayerState>;
@@ -810,9 +833,13 @@ declare function toSeconds(input: number | string): number;
 
 /**
  * URL helpers used by the source registry to dispatch a source descriptor to
- * the right provider. Pure string predicates — no DOM, no I/O.
+ * the right provider. Pure string predicates - no DOM, no I/O.
  */
 
+/** Compare the descriptor fields that affect provider loading or media UI. */
+declare function areSourceDescriptorsEquivalent(previous: SourceDescriptor | null, next: SourceDescriptor | null): boolean;
+/** Whether a media/resource URL is safe to hand to browser media APIs. */
+declare function isSafeMediaUrl(input: string | undefined | null): boolean;
 /**
  * Heuristic for HLS m3u8 URLs.
  *
@@ -843,4 +870,4 @@ declare function looksLikeProgressive(input: string | undefined | null): boolean
  */
 declare function detectSourceType(source: SourceDescriptor): SourceType;
 
-export { type AutoplayMode, type BufferedRange, type CommandRegistry, DEFAULT_TOKENS, type Disposer, type KeyboardScope, type MutableStore, type Player, type PlayerError, type PlayerErrorCode, type PlayerEvents, type PlayerHooks, type PlayerOptions, type PlayerState, type PlayerStatus, type PluginHost, type PluginInstance, type QualityLevel, type ReadableStore, type SourceDescriptor, type SourceLoader, type SourceProvider, type SourceType, type SubtitleTrack, THEME_PRESETS, TOKEN_TO_CSS_VAR, type ThemeName, type ThemeTokens, type ThumbnailsDescriptor, type UnauthorizedEvent, announce, applyTheme, createFocusTrap, createPlayer, definePlugin, detectSourceType, formatTime, looksLikeHls, looksLikeProgressive, looksLikeYouTube, parseTime, resolveTokens, toSeconds };
+export { type AutoplayMode, type BufferedRange, type CommandRegistry, DEFAULT_TOKENS, type Disposer, type KeyboardScope, type MutableStore, type Player, type PlayerError, type PlayerErrorCode, type PlayerEvents, type PlayerHooks, type PlayerOptions, type PlayerState, type PlayerStatus, type PluginHost, type PluginInstance, type PluginMediaAttachment, type QualityLevel, type ReadableStore, type SourceDescriptor, type SourceLoader, type SourceProvider, type SourceTransform, type SourceType, type SubtitleTrack, THEME_PRESETS, TOKEN_TO_CSS_VAR, type ThemeName, type ThemeTokens, type ThumbnailsDescriptor, type UnauthorizedEvent, announce, applyTheme, areSourceDescriptorsEquivalent, createFocusTrap, createPlayer, definePlugin, detectSourceType, formatTime, isSafeMediaUrl, looksLikeHls, looksLikeProgressive, looksLikeYouTube, parseTime, resolveTokens, toSeconds };

package/dist/index.d.ts

@@ -58,7 +58,7 @@ interface CreateStoreOptions<_T> {
  * Golden cases: G13 (unauthorized HLS), every error path in G1..G16.
  */
 /** Stable error codes. The string literal IS the public contract. */
-type PlayerErrorCode = "source" | "network" | "decode" | "unauthorized" | "unsupported" | "internal";
+type PlayerErrorCode = "source" | "network" | "decode" | "unauthorized" | "unsupported" | "hls-fragment-loop" | "internal";
 /**
  * Structured player error. Adapters render the message; plugins can inspect
  * `code`, `status`, and `retryable` to decide on retry/UI strategy.
@@ -132,12 +132,12 @@ interface ThumbnailsDescriptor {
 /**
  * The kind of source. `auto` lets the registry pick.
  *
- * - `hls` — HLS m3u8 manifest, dispatched to `hls.js` (or native on Safari).
- * - `mp4` — Progressive MP4/WebM, dispatched to the native engine.
- * - `youtube` — YouTube IFrame API.
- * - `dash` — MPEG-DASH (reserved for a future dash provider).
- * - `native` — Force the native engine even if the URL looks like HLS (G4 Safari escape).
- * - `auto` — Detect from the URL via `looksLikeHls` / `detectSourceType`.
+ * - `hls` - HLS m3u8 manifest, dispatched to `hls.js` (or native on Safari).
+ * - `mp4` - Progressive MP4/WebM, dispatched to the native engine.
+ * - `youtube` - YouTube IFrame API.
+ * - `dash` - MPEG-DASH (reserved for a future dash provider).
+ * - `native` - Force the native engine even if the URL looks like HLS (G4 Safari escape).
+ * - `auto` - Detect from the URL via `looksLikeHls` / `detectSourceType`.
  */
 type SourceType = "auto" | "hls" | "mp4" | "youtube" | "dash" | "native";
 /**
@@ -154,8 +154,8 @@ interface SourceDescriptor {
     /**
      * Cookie / credentials policy for HLS XHRs.
      *
-     * - `boolean` — sent for every request.
-     * - `(url) => boolean` — predicate (e.g. allowlist `https://api-gateway*`, see G7, G13).
+     * - `boolean` - sent for every request.
+     * - `(url) => boolean` - predicate scoped to a trusted API origin/path (see G7, G13).
      */
     withCredentials?: boolean | ((url: string) => boolean);
     /** Subtitle tracks to attach (G1, G15). */
@@ -222,9 +222,9 @@ interface SourceProvider {
     /**
      * Decide whether this provider can handle the given source.
      *
-     * - `true` — definite match.
-     * - `"maybe"` — handle if no `true` match exists (used by the native fallback).
-     * - `false` — skip.
+     * - `true` - definite match.
+     * - `"maybe"` - handle if no `true` match exists (used by the native fallback).
+     * - `false` - skip.
      */
     canHandle(source: SourceDescriptor): boolean | "maybe";
     /** Construct a fresh loader. Called once per source attach. */
@@ -469,6 +469,13 @@ interface Player {
     dispose(): void;
 }
 
+/** Synchronous source normalization hook applied before provider resolution. */
+type SourceTransform = (source: SourceDescriptor) => SourceDescriptor;
+/** Media element and container owned by one player attachment. */
+interface PluginMediaAttachment {
+    video: HTMLVideoElement;
+    container: Element;
+}
 /**
  * Command registry shared between the player and plugins. Commands are the
  * extension point for keyboard handlers, plugin contributions, and UI buttons.
@@ -505,6 +512,22 @@ interface PluginHost {
     };
     /** Shared command registry. Plugins MUST namespace their commands. */
     commands: CommandRegistry;
+    /**
+     * Register a synchronous source transform. Core applies transforms before
+     * the source is stored or passed to a provider, including the initial
+     * source supplied in `PlayerOptions`.
+     *
+     * Optional for compatibility with custom test hosts built against earlier
+     * versions of the contract.
+     */
+    sources?: {
+        transform(transform: SourceTransform): () => void;
+    };
+    /** Player-scoped media ownership and attach/detach lifecycle. */
+    media?: {
+        get(): PluginMediaAttachment | null;
+        subscribe(listener: (attachment: PluginMediaAttachment | null) => void): () => void;
+    };
     /** Read-only state. */
     store: ReadableStore<PlayerState>;
     /** Emit a custom plugin event. Use the `${plugin}:${verb}` namespace. */
@@ -639,7 +662,7 @@ interface PlayerOptions {
 }
 
 /**
- * `createPlayer(options)` — wires every piece of `@f8team/reel-core` into a
+ * `createPlayer(options)` - wires every piece of `@f8team/reel-core` into a
  * single `Player`. The factory is the one and only public entry point.
  *
  * Responsibilities:
@@ -658,7 +681,7 @@ interface PlayerOptions {
  * unit tests.
  */
 
-/** @internal — extra knobs surfaced for tests and adapters. */
+/** @internal - extra knobs surfaced for tests and adapters. */
 interface CreatePlayerInternalOptions {
     /** Override the microtask scheduler for the store. Tests use this. */
     storeOptions?: CreateStoreOptions<PlayerState>;
@@ -810,9 +833,13 @@ declare function toSeconds(input: number | string): number;
 
 /**
  * URL helpers used by the source registry to dispatch a source descriptor to
- * the right provider. Pure string predicates — no DOM, no I/O.
+ * the right provider. Pure string predicates - no DOM, no I/O.
  */
 
+/** Compare the descriptor fields that affect provider loading or media UI. */
+declare function areSourceDescriptorsEquivalent(previous: SourceDescriptor | null, next: SourceDescriptor | null): boolean;
+/** Whether a media/resource URL is safe to hand to browser media APIs. */
+declare function isSafeMediaUrl(input: string | undefined | null): boolean;
 /**
  * Heuristic for HLS m3u8 URLs.
  *
@@ -843,4 +870,4 @@ declare function looksLikeProgressive(input: string | undefined | null): boolean
  */
 declare function detectSourceType(source: SourceDescriptor): SourceType;
 
-export { type AutoplayMode, type BufferedRange, type CommandRegistry, DEFAULT_TOKENS, type Disposer, type KeyboardScope, type MutableStore, type Player, type PlayerError, type PlayerErrorCode, type PlayerEvents, type PlayerHooks, type PlayerOptions, type PlayerState, type PlayerStatus, type PluginHost, type PluginInstance, type QualityLevel, type ReadableStore, type SourceDescriptor, type SourceLoader, type SourceProvider, type SourceType, type SubtitleTrack, THEME_PRESETS, TOKEN_TO_CSS_VAR, type ThemeName, type ThemeTokens, type ThumbnailsDescriptor, type UnauthorizedEvent, announce, applyTheme, createFocusTrap, createPlayer, definePlugin, detectSourceType, formatTime, looksLikeHls, looksLikeProgressive, looksLikeYouTube, parseTime, resolveTokens, toSeconds };
+export { type AutoplayMode, type BufferedRange, type CommandRegistry, DEFAULT_TOKENS, type Disposer, type KeyboardScope, type MutableStore, type Player, type PlayerError, type PlayerErrorCode, type PlayerEvents, type PlayerHooks, type PlayerOptions, type PlayerState, type PlayerStatus, type PluginHost, type PluginInstance, type PluginMediaAttachment, type QualityLevel, type ReadableStore, type SourceDescriptor, type SourceLoader, type SourceProvider, type SourceTransform, type SourceType, type SubtitleTrack, THEME_PRESETS, TOKEN_TO_CSS_VAR, type ThemeName, type ThemeTokens, type ThumbnailsDescriptor, type UnauthorizedEvent, announce, applyTheme, areSourceDescriptorsEquivalent, createFocusTrap, createPlayer, definePlugin, detectSourceType, formatTime, isSafeMediaUrl, looksLikeHls, looksLikeProgressive, looksLikeYouTube, parseTime, resolveTokens, toSeconds };