ts-video-player 0.1.4 → 0.1.6

package/dist/{chunk-hfd9k46d.js → chunk-fvz33zn4.js}

@@ -666,7 +666,9 @@ class YouTubeProvider2 extends BaseProvider2 {
     });
     this.iframe = this.player.getIframe();
     this.iframe.className = "ts-video-player__media";
-    this.iframe.style.cssText = "position:absolute;inset:0;width:100%;height:100%;border:0";
+    this.iframe.style.cssText = "position:absolute;left:0;top:-100%;width:100%;height:300%;border:0";
+    if (this.iframe.parentElement)
+      this.iframe.parentElement.style.overflow = "hidden";
   }
   async loadYouTubeAPI() {
     if (window.YT?.Player)
@@ -2009,6 +2011,20 @@ function getPreconnectHints2(src, loaders = defaultLoaders2) {
   return loader?.preconnect?.() || [];
 }
 
+// src/core/cover.ts
+function embedCover(state, dismissed) {
+  const embed = state.providerType === "youtube" || state.providerType === "vimeo";
+  const waiting = !state.started || state.ended;
+  if (!embed || !waiting || state.error || dismissed)
+    return { show: false, image: "" };
+  if (state.poster)
+    return { show: true, image: state.poster };
+  const src = state.src;
+  const url = typeof src === "string" ? src : src?.src || "";
+  const youtubeId = state.providerType === "youtube" ? extractYouTubeId2(url) : null;
+  return { show: true, image: youtubeId ? `https://i.ytimg.com/vi/${youtubeId}/hqdefault.jpg` : "" };
+}
+
 // src/player.ts
 class Player2 {
   _el;
@@ -2021,6 +2037,9 @@ class Player2 {
   _destroyed = false;
   _sourceLoadId = 0;
   _announcer = null;
+  _cover = null;
+  _coverDismissed = false;
+  _coverTimer = null;
   constructor(container, options = {}) {
     if (typeof container === "string") {
       const el = document.querySelector(container);
@@ -2068,6 +2087,7 @@ class Player2 {
     mediaContainer.className = "ts-video-player__container";
     mediaContainer.style.cssText = "position:relative;width:100%;height:100%";
     this._el.appendChild(mediaContainer);
+    this.setupCover();
     if (this._options.announcements !== false) {
       const liveRegion = document.createElement("div");
       liveRegion.className = "ts-video-player__announcer";
@@ -2081,6 +2101,53 @@ class Player2 {
     const _el = this._el;
     _el.__videoPlayer = this;
   }
+  setupCover() {
+    const cover = document.createElement("button");
+    cover.type = "button";
+    cover.className = "ts-video-player__cover";
+    cover.setAttribute("aria-label", `Play ${this._options.title || "video"}`);
+    cover.hidden = true;
+    cover.style.cssText = "position:absolute;inset:0;z-index:2;display:none;align-items:center;justify-content:center;width:100%;height:100%;margin:0;padding:0;border:0;border-radius:inherit;background:#000 center/cover no-repeat;cursor:pointer;-webkit-tap-highlight-color:transparent";
+    const button = document.createElement("span");
+    button.setAttribute("aria-hidden", "true");
+    button.style.cssText = "display:flex;align-items:center;justify-content:center;width:64px;height:64px;border-radius:50%;background:rgba(255,255,255,0.92);box-shadow:0 4px 18px rgba(0,0,0,0.35)";
+    const triangle = document.createElement("span");
+    triangle.style.cssText = "width:22px;height:24px;margin-left:5px;background:#0f172a;clip-path:polygon(0 0,100% 50%,0 100%)";
+    button.appendChild(triangle);
+    cover.appendChild(button);
+    cover.addEventListener("click", (event) => {
+      event.stopPropagation();
+      this.play().catch(() => {});
+      if (this._coverTimer)
+        clearTimeout(this._coverTimer);
+      this._coverTimer = setTimeout(() => {
+        if (this.state.started)
+          return;
+        this._coverDismissed = true;
+        this.updateCover(this.state);
+      }, 2000);
+    });
+    this._el.appendChild(cover);
+    this._cover = cover;
+    this._cleanupFns.push(() => {
+      if (this._coverTimer)
+        clearTimeout(this._coverTimer);
+      cover.remove();
+    });
+  }
+  updateCover(state) {
+    const cover = this._cover;
+    if (!cover)
+      return;
+    const { show, image } = embedCover(state, this._coverDismissed);
+    if (show) {
+      const background = image ? `url("${image.replace(/["\\]/g, "")}")` : "none";
+      if (cover.style.backgroundImage !== background)
+        cover.style.backgroundImage = background;
+    }
+    cover.hidden = !show;
+    cover.style.display = show ? "flex" : "none";
+  }
   setupState() {
     this._store.batch({
       volume: this._options.volume ?? 1,
@@ -2095,6 +2162,7 @@ class Player2 {
     });
     const unsubscribe = this._store.subscribe((state) => {
       this.updateAttributes(state);
+      this.updateCover(state);
     });
     this._cleanupFns.push(unsubscribe);
   }
@@ -2238,11 +2306,13 @@ class Player2 {
     if (sources.length === 0) {
       return;
     }
+    this._coverDismissed = false;
     this._store.batch({
       sources,
       src: sources[0],
       loadingState: "loading",
-      error: null
+      error: null,
+      started: false
     });
     this._events.emit("sourceschange", sources);
     const candidates = findSourceCandidates(sources, this._loaders);
@@ -2311,6 +2381,9 @@ class Player2 {
       error: { code: 4, message: "Failed to load all compatible sources", details: lastError }
     });
   }
+  setPoster(url) {
+    this._store.set("poster", url);
+  }
   getSrc() {
     return this.state.src;
   }
@@ -2629,6 +2702,9 @@ class VideoPlayerElement2 extends HTMLElementBase {
         if (value)
           this._player.setSrc(value);
         break;
+      case "poster":
+        this._player.setPoster(value || "");
+        break;
       case "muted":
         this._player.setMuted(value !== null);
         break;

package/dist/core/cover.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The poster over an embedded video until it plays: when to show it, and
+ * with which image.
+ *
+ * @module core/cover
+ */
+import type { PlayerState } from '../types';
+export interface EmbedCover {
+    show: boolean;
+    /** The poster to draw, or '' for a plain black cover. */
+    image: string;
+}
+/**
+ * A YouTube or Vimeo embed draws its own chrome before playback (a title bar,
+ * a play button, "Watch on YouTube", and on iOS the system's controls for the
+ * embed's own video), none of which can be styled from outside the iframe.
+ * Until the first play, and again once it ends (where YouTube shows other
+ * videos), the player covers it with its poster instead: the one the page
+ * gave it, or else YouTube's thumbnail for the video.
+ *
+ * `dismissed` is set when a tap on the cover did not start playback, so the
+ * embed's own button is left reachable.
+ */
+export declare function embedCover(state: Pick<PlayerState, 'providerType' | 'started' | 'ended' | 'error' | 'poster' | 'src'>, dismissed: boolean): EmbedCover;

package/dist/elements/index.js

@@ -23,7 +23,7 @@ import {
   MediaErrorDisplay2,
   MediaRemotePlaybackButton2,
   registerElements2
-} from "../chunk-hfd9k46d.js";
+} from "../chunk-fvz33zn4.js";
 export {
   MediaAirplayButton2 as MediaAirplayButton,
   MediaErrorDisplay2 as MediaErrorDisplay,

package/dist/index.js

@@ -51,7 +51,7 @@ import {
   applyPosition2,
   MediaSettingsMenu2,
   registerElements2
-} from "./chunk-hfd9k46d.js";
+} from "./chunk-fvz33zn4.js";
 import {
   playback2,
   volume2,

package/dist/player.d.ts

@@ -20,6 +20,9 @@ export declare class Player implements IPlayer {
     private _destroyed;
     private _sourceLoadId;
     private _announcer;
+    private _cover;
+    private _coverDismissed;
+    private _coverTimer;
     /**
      * Create a new player instance
      */
@@ -29,6 +32,18 @@ export declare class Player implements IPlayer {
     get provider(): Provider | null;
     get ready(): boolean;
     private setupElement;
+    /**
+     * The poster over an embedded video until it plays.
+     *
+     * A YouTube or Vimeo embed draws its own chrome before playback: a title
+     * bar, a play button, "Watch on YouTube", and on iOS the system's controls
+     * for the embed's own video. None of it can be styled from outside the
+     * iframe, and it stacks under the player's controls. Until the first play,
+     * the player shows its poster and one play button over the embed instead;
+     * once the video plays the embed's chrome is gone and the cover lifts.
+     */
+    private setupCover;
+    private updateCover;
     private setupState;
     private setupKeyboard;
     private setupActivity;
@@ -42,6 +57,8 @@ export declare class Player implements IPlayer {
     private announce;
     destroy(): void;
     setSrc(src: Src | Src[]): Promise<void>;
+    /** The image shown before playback, and on an embed's cover. */
+    setPoster(url: string): void;
     getSrc(): Src | null;
     private attachProviderEvents;
     play(): Promise<void>;

package/dist/types.d.ts

@@ -632,6 +632,8 @@ export interface Player {
     destroy(): void;
     setSrc(src: Src | Src[]): void;
     getSrc(): Src | null;
+    /** The image shown before playback, and on an embed's cover */
+    setPoster(url: string): void;
     play(): Promise<void>;
     pause(): void;
     togglePlay(): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-video-player",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "A modern, framework-agnostic video player with deep stx integration",
   "author": "Chris Breuer <chris@stacksjs.org>",
   "license": "MIT",

package/src/core/cover.ts

@@ -0,0 +1,46 @@
+/**
+ * The poster over an embedded video until it plays: when to show it, and
+ * with which image.
+ *
+ * @module core/cover
+ */
+
+import type { PlayerState } from '../types'
+import { extractYouTubeId } from '../providers/youtube'
+
+export interface EmbedCover {
+  show: boolean
+  /** The poster to draw, or '' for a plain black cover. */
+  image: string
+}
+
+/**
+ * A YouTube or Vimeo embed draws its own chrome before playback (a title bar,
+ * a play button, "Watch on YouTube", and on iOS the system's controls for the
+ * embed's own video), none of which can be styled from outside the iframe.
+ * Until the first play, and again once it ends (where YouTube shows other
+ * videos), the player covers it with its poster instead: the one the page
+ * gave it, or else YouTube's thumbnail for the video.
+ *
+ * `dismissed` is set when a tap on the cover did not start playback, so the
+ * embed's own button is left reachable.
+ */
+export function embedCover(
+  state: Pick<PlayerState, 'providerType' | 'started' | 'ended' | 'error' | 'poster' | 'src'>,
+  dismissed: boolean,
+): EmbedCover {
+  const embed = state.providerType === 'youtube' || state.providerType === 'vimeo'
+  // Back over the embed when the video ends, where YouTube would otherwise
+  // fill the frame with suggestions of other videos.
+  const waiting = !state.started || state.ended
+  if (!embed || !waiting || state.error || dismissed)
+    return { show: false, image: '' }
+
+  if (state.poster)
+    return { show: true, image: state.poster }
+
+  const src = state.src
+  const url = typeof src === 'string' ? src : src?.src || ''
+  const youtubeId = state.providerType === 'youtube' ? extractYouTubeId(url) : null
+  return { show: true, image: youtubeId ? `https://i.ytimg.com/vi/${youtubeId}/hqdefault.jpg` : '' }
+}

package/src/elements/video-player.ts

@@ -73,6 +73,9 @@ export class VideoPlayerElement extends HTMLElementBase {
       case 'src':
         if (value) this._player.setSrc(value)
         break
+      case 'poster':
+        this._player.setPoster(value || '')
+        break
       case 'muted':
         this._player.setMuted(value !== null)
         break

package/src/player.ts

@@ -21,6 +21,7 @@ import { EventEmitter, createKeyboardHandler, createActivityDetector, type Keybo
 import { createMediaSession, type MediaSessionOptions } from './core/media-session'
 import { lockOrientation, unlockOrientation } from './core/orientation'
 import { defaultLoaders, findSourceCandidates } from './providers'
+import { embedCover } from './core/cover'
 
 // =============================================================================
 // Player Class
@@ -40,6 +41,9 @@ export class Player implements IPlayer {
   private _destroyed = false
   private _sourceLoadId = 0
   private _announcer: HTMLElement | null = null
+  private _cover: HTMLButtonElement | null = null
+  private _coverDismissed = false
+  private _coverTimer: ReturnType<typeof setTimeout> | null = null
 
   /**
    * Create a new player instance
@@ -114,6 +118,8 @@ export class Player implements IPlayer {
     mediaContainer.style.cssText = 'position:relative;width:100%;height:100%'
     this._el.appendChild(mediaContainer)
 
+    this.setupCover()
+
     // Create ARIA live region for screen reader announcements
     if (this._options.announcements !== false) {
       const liveRegion = document.createElement('div')
@@ -132,6 +138,63 @@ export class Player implements IPlayer {
     _el.__videoPlayer = this
   }
 
+  /**
+   * The poster over an embedded video until it plays.
+   *
+   * A YouTube or Vimeo embed draws its own chrome before playback: a title
+   * bar, a play button, "Watch on YouTube", and on iOS the system's controls
+   * for the embed's own video. None of it can be styled from outside the
+   * iframe, and it stacks under the player's controls. Until the first play,
+   * the player shows its poster and one play button over the embed instead;
+   * once the video plays the embed's chrome is gone and the cover lifts.
+   */
+  private setupCover(): void {
+    const cover = document.createElement('button')
+    cover.type = 'button'
+    cover.className = 'ts-video-player__cover'
+    cover.setAttribute('aria-label', `Play ${this._options.title || 'video'}`)
+    cover.hidden = true
+    cover.style.cssText = 'position:absolute;inset:0;z-index:2;display:none;align-items:center;justify-content:center;width:100%;height:100%;margin:0;padding:0;border:0;border-radius:inherit;background:#000 center/cover no-repeat;cursor:pointer;-webkit-tap-highlight-color:transparent'
+    const button = document.createElement('span')
+    button.setAttribute('aria-hidden', 'true')
+    button.style.cssText = 'display:flex;align-items:center;justify-content:center;width:64px;height:64px;border-radius:50%;background:rgba(255,255,255,0.92);box-shadow:0 4px 18px rgba(0,0,0,0.35)'
+    const triangle = document.createElement('span')
+    triangle.style.cssText = 'width:22px;height:24px;margin-left:5px;background:#0f172a;clip-path:polygon(0 0,100% 50%,0 100%)'
+    button.appendChild(triangle)
+    cover.appendChild(button)
+    cover.addEventListener('click', (event) => {
+      event.stopPropagation()
+      void this.play().catch(() => {})
+      // Some browsers only let a tap inside the embed start it. If this one
+      // did not, get out of the way so the embed's own button can.
+      if (this._coverTimer) clearTimeout(this._coverTimer)
+      this._coverTimer = setTimeout(() => {
+        if (this.state.started) return
+        this._coverDismissed = true
+        this.updateCover(this.state)
+      }, 2000)
+    })
+    this._el.appendChild(cover)
+    this._cover = cover
+    this._cleanupFns.push(() => {
+      if (this._coverTimer) clearTimeout(this._coverTimer)
+      cover.remove()
+    })
+  }
+
+  private updateCover(state: PlayerState): void {
+    const cover = this._cover
+    if (!cover) return
+    const { show, image } = embedCover(state, this._coverDismissed)
+    if (show) {
+      const background = image ? `url("${image.replace(/["\\]/g, '')}")` : 'none'
+      if (cover.style.backgroundImage !== background) cover.style.backgroundImage = background
+    }
+    // `hidden` alone would not do it: the inline display wins over it.
+    cover.hidden = !show
+    cover.style.display = show ? 'flex' : 'none'
+  }
+
   private setupState(): void {
     // Initial state from options
     this._store.batch({
@@ -150,6 +213,7 @@ export class Player implements IPlayer {
     const unsubscribe = this._store.subscribe((state) => {
       // Update DOM attributes
       this.updateAttributes(state)
+      this.updateCover(state)
     })
 
     this._cleanupFns.push(unsubscribe)
@@ -366,12 +430,14 @@ export class Player implements IPlayer {
       return
     }
 
-    // Update state
+    // Update state. A new source has not played yet, so its cover returns.
+    this._coverDismissed = false
     this._store.batch({
       sources,
       src: sources[0],
       loadingState: 'loading',
       error: null,
+      started: false,
     })
 
     this._events.emit('sourceschange', sources)
@@ -451,6 +517,11 @@ export class Player implements IPlayer {
     })
   }
 
+  /** The image shown before playback, and on an embed's cover. */
+  setPoster(url: string): void {
+    this._store.set('poster', url)
+  }
+
   getSrc(): Src | null {
     return this.state.src
   }

package/src/providers/youtube.ts

@@ -254,8 +254,14 @@ export class YouTubeProvider extends BaseProvider {
     // Get iframe reference
     this.iframe = this.player.getIframe()
     this.iframe.className = 'ts-video-player__media'
-    // Filling the player, whatever size the provider's API gave the frame.
-    this.iframe.style.cssText = 'position:absolute;inset:0;width:100%;height:100%;border:0'
+    // Three times the player's height, centred, and clipped by the player.
+    // YouTube letterboxes the video in the middle of its frame, so the video
+    // still fills the player, while the chrome it draws at the frame's edges
+    // during playback (the title bar and channel avatar at the top, the
+    // YouTube logo and "More videos" at the bottom) falls outside the clip.
+    // It cannot be styled from outside the iframe any other way.
+    this.iframe.style.cssText = 'position:absolute;left:0;top:-100%;width:100%;height:300%;border:0'
+    if (this.iframe.parentElement) this.iframe.parentElement.style.overflow = 'hidden'
   }
 
   private async loadYouTubeAPI(): Promise<void> {

package/src/types.ts

@@ -756,6 +756,8 @@ export interface Player {
   // Source
   setSrc(src: Src | Src[]): void
   getSrc(): Src | null
+  /** The image shown before playback, and on an embed's cover */
+  setPoster(url: string): void
 
   // Playback
   play(): Promise<void>