@f8team/reel-core 1.0.4 → 1.1.0

package/dist/index.d.cts

@@ -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. */
@@ -775,6 +798,33 @@ interface FocusTrap {
  */
 declare function createFocusTrap(container: HTMLElement): FocusTrap;
 
+/**
+ * Focus helpers for the auto-hiding controls chrome.
+ *
+ * The themes keep the controls bar visible while the player matches
+ * `:focus-within`, so keyboard users never lose the control they are on.
+ * A pointer click focuses that control too, which used to latch the chrome
+ * open forever - most visibly after tapping the fullscreen button, the only
+ * way into fullscreen. `shouldKeepControlsVisible` tells the auto-hide timer
+ * which of the two it is looking at, and `blurFocusInside` releases the
+ * pointer-induced focus so `:focus-within` stops matching.
+ */
+/**
+ * Clears focus from any focused descendant of `container`.
+ *
+ * Used on pointer leave of the `[data-reel]` wrapper and when the auto-hide
+ * timer fires, so `:focus-within` does not keep the controls bar visible
+ * after a mouse click or tap on a control.
+ */
+declare function blurFocusInside(container: Element): void;
+/**
+ * `true` when the controls must stay on screen even though the idle timer
+ * expired: an open menu, or a control the user reached with the keyboard.
+ *
+ * Pointer focus deliberately returns `false` - a tap must not pin the chrome.
+ */
+declare function shouldKeepControlsVisible(container: Element): boolean;
+
 /**
  * Time helpers shared by the seek bar, transcript markers (G8), and the
  * keyboard / commands layer.
@@ -810,9 +860,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 +897,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, blurFocusInside, createFocusTrap, createPlayer, definePlugin, detectSourceType, formatTime, isSafeMediaUrl, looksLikeHls, looksLikeProgressive, looksLikeYouTube, parseTime, resolveTokens, shouldKeepControlsVisible, toSeconds };

package/dist/index.d.ts

@@ -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. */
@@ -775,6 +798,33 @@ interface FocusTrap {
  */
 declare function createFocusTrap(container: HTMLElement): FocusTrap;
 
+/**
+ * Focus helpers for the auto-hiding controls chrome.
+ *
+ * The themes keep the controls bar visible while the player matches
+ * `:focus-within`, so keyboard users never lose the control they are on.
+ * A pointer click focuses that control too, which used to latch the chrome
+ * open forever - most visibly after tapping the fullscreen button, the only
+ * way into fullscreen. `shouldKeepControlsVisible` tells the auto-hide timer
+ * which of the two it is looking at, and `blurFocusInside` releases the
+ * pointer-induced focus so `:focus-within` stops matching.
+ */
+/**
+ * Clears focus from any focused descendant of `container`.
+ *
+ * Used on pointer leave of the `[data-reel]` wrapper and when the auto-hide
+ * timer fires, so `:focus-within` does not keep the controls bar visible
+ * after a mouse click or tap on a control.
+ */
+declare function blurFocusInside(container: Element): void;
+/**
+ * `true` when the controls must stay on screen even though the idle timer
+ * expired: an open menu, or a control the user reached with the keyboard.
+ *
+ * Pointer focus deliberately returns `false` - a tap must not pin the chrome.
+ */
+declare function shouldKeepControlsVisible(container: Element): boolean;
+
 /**
  * Time helpers shared by the seek bar, transcript markers (G8), and the
  * keyboard / commands layer.
@@ -810,9 +860,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 +897,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, blurFocusInside, createFocusTrap, createPlayer, definePlugin, detectSourceType, formatTime, isSafeMediaUrl, looksLikeHls, looksLikeProgressive, looksLikeYouTube, parseTime, resolveTokens, shouldKeepControlsVisible, toSeconds };