@hopecloud/jetstream-player 1.4.0-rc.7 → 1.4.0-rc.8

package/README.md

@@ -1,8 +1,12 @@
-# @hopecloud/jetstream-player
+# Jetstream Player SDK
 
-Control an embedded [Jetstream](https://docs.hope.cloud/libs/jetstream-player/) player
-from your page — play, pause, seek, mute, read playback state, and subscribe to
-events — across the iframe boundary, with no server glue.
+Put the [Jetstream](https://docs.hope.cloud/libs/jetstream-player/) Player on
+your website and drive it from your own code. The player itself lives in an
+iframe served by Jetstream; this SDK is your remote control for it — play,
+pause, seek, mute, ask what's happening, and react to events, without ever
+thinking about the iframe boundary.
+
+It works the same way for videos, audio, and whole playlists.
 
 **[Full documentation →](https://docs.hope.cloud/libs/jetstream-player/)**
 
@@ -14,6 +18,14 @@ npm i @hopecloud/jetstream-player
 
 ## Quick start
 
+Give the player a place on your page — any element with an id:
+
+```html
+<div id="player"></div>
+```
+
+Then create the player and tell it what to play:
+
 ```ts
 import { JetstreamPlayer } from '@hopecloud/jetstream-player';
 
@@ -21,7 +33,7 @@ const player = new JetstreamPlayer('#player', {
   mediaId: 'jsv:xxxxxxxxxx',
   events: {
     ready: () => console.log('ready'),
-    timeupdate: (time) => console.log('time', time),
+    timeupdate: (seconds) => console.log('now at', seconds),
   },
 });
 
@@ -29,49 +41,56 @@ player.play();
 const muted = await player.isMuted();
 ```
 
-`mediaId` is the only required option; the library creates and mounts the iframe
-at the given selector.
+`mediaId` — a video, an audio, or a playlist id from Jetstream — is the only
+required option. The SDK creates the iframe and mounts it inside your element;
+no other markup needed.
 
 ## What you can do
 
-- **Commands** — `play()`, `pause()`, `mute()`, `unmute()`, `seekTo(seconds)`,
-  `playNext()`, `playPrev()`.
-- **Getters** (Promise-based) — `isMuted()`, `isPaused()`, `getCurrentTime()`,
-  `getDuration()`. They reject after 5s if the player doesn't reply.
-- **Events** — subscribe via `options.events`: `ready`, `timeupdate`, `play`,
-  `pause`, `loadedmetadata`, `ended`, `volumechange`, `error`.
-- **Teardown** — `dispose()` removes listeners and tears down Picture-in-Picture.
+- **Control playback** — `play()`, `pause()`, `seekTo(seconds)`, `mute()`,
+  `unmute()`, and `playNext()` / `playPrev()` for playlists.
+- **Ask the player questions** — `isMuted()`, `isPaused()`, `getCurrentTime()`,
+  `getDuration()`. The answers come from the player itself, so these return
+  Promises (and reject after 5 seconds if the player doesn't reply).
+- **React to events** — pass handlers in `options.events`, or subscribe later
+  with `on()` (it returns an unsubscribe function): `ready`, `play`, `pause`,
+  `timeupdate`, `loadedmetadata`, `ended`, `volumechange`, `error`.
+- **Keep it on screen** — `sticky: true` pins the player to a corner of the
+  screen when the visitor scrolls past it.
+- **Clean up** — `dispose()` when your page removes the player.
 
-See the [options](https://docs.hope.cloud/libs/jetstream-player/player-options)
-and [methods](https://docs.hope.cloud/libs/jetstream-player/player-methods)
-reference for the full list.
+Start with [Getting Started](https://docs.hope.cloud/libs/jetstream-player/getting-started),
+then see [Player Options](https://docs.hope.cloud/libs/jetstream-player/player-options)
+and [Player Methods](https://docs.hope.cloud/libs/jetstream-player/player-methods)
+for everything you can configure and call.
 
-## Targeting a non-prod embed
+## Pointing at a staging environment
 
-By default the player loads the production embed. Point it at another host
-(staging/dev) with `embedOrigin`:
+By default the player loads the production embed. For special setups — a
+staging or dev environment — point it elsewhere with `embedOrigin`:
 
 ```ts
-new JetstreamPlayer('#player', {
+const player = new JetstreamPlayer('#player', {
   mediaId: 'jsv:xxxxxxxxxx',
   embedOrigin: 'https://embed-stage.jetstream.studio',
 });
 ```
 
-Communication is cross-origin `postMessage`, and the SDK learns the iframe's
-real origin at runtime — so it keeps working even when the embed redirects.
+Under the hood everything is cross-origin `postMessage`, and the SDK learns
+the iframe's real origin at runtime — so it keeps working even when the embed
+host redirects.
 
 ## Development
 
 ```bash
 pnpm install
-pnpm build       # rolldown + .d.ts
-pnpm test        # vitest
-pnpm lint
-pnpm type-check
+pnpm build       # vp pack — bundle + .d.ts
+pnpm test        # vp test (vitest)
+pnpm check       # format check + type-aware lint + type errors (the CI gate)
 ```
 
 Documentation lives in the monorepo's public docs site at
 `docs/cloud/libs/jetstream-player/`, published to docs.hope.cloud.
 
-Architecture decisions are recorded in [`adr/`](./adr).
+Architecture decisions are recorded in the monorepo at
+`docs/adr/jetstream-player/`.

package/dist/index.d.ts

@@ -1,5 +1,78 @@
-export { JetstreamPlayer } from './player';
-export type { JetstreamPlayerOptions, PlayerEventHandler, PlayerEventHandlers, } from './player.types';
-export type { EmbedFrameOptions } from './embed/embed-frame.types';
-export { playerListenEvents } from './bridge/protocol.types';
-export type { PlayerCommand, PlayerCommandEvent, PlayerEvent, PlayerEventMap, PlayerEvents, PlayerGetterEvents, } from './bridge/protocol.types';
+//#region src/bridge/protocol.types.d.ts
+interface PlayerEventMap {
+  ready: unknown;
+  timeupdate: number;
+  play: unknown;
+  pause: unknown;
+  loadedmetadata: undefined;
+  ended: boolean;
+  volumechange: number;
+  error: unknown;
+}
+type PlayerEvents = keyof PlayerEventMap;
+declare const playerListenEvents: readonly PlayerEvents[];
+type PlayerGetterEvents = "is-muted" | "get-current-time" | "get-video-current-time" | "get-duration" | "is-paused";
+interface PlayerEvent {
+  type: PlayerEvents | PlayerGetterEvents;
+  value?: unknown;
+}
+type PlayerCommandEvent = "play" | "pause" | "mute" | "unmute" | "seek-to" | "seekTo" | "play-next" | "play-prev";
+interface PlayerCommand {
+  name: PlayerCommandEvent | PlayerGetterEvents;
+  params?: unknown;
+}
+//#endregion
+//#region src/embed/embed-frame.types.d.ts
+interface EmbedFrameOptions {
+  mediaId: string;
+  playerId?: string;
+  region?: "eu";
+  audioLang?: string;
+  subtitleLang?: string;
+  embedOrigin?: string;
+  /** @deprecated Use {@link embedOrigin} instead. */
+  origin?: string;
+  width?: string;
+  height?: string;
+}
+//#endregion
+//#region src/player.types.d.ts
+type PlayerEventHandler<E extends PlayerEvents = PlayerEvents> = (value: PlayerEventMap[E]) => void;
+type PlayerEventHandlers = { [E in PlayerEvents]?: PlayerEventHandler<E> };
+type JetstreamPlayerOptions = {
+  sticky?: boolean;
+  events?: PlayerEventHandlers;
+} & EmbedFrameOptions;
+//#endregion
+//#region src/player.d.ts
+declare class JetstreamPlayer {
+  private options;
+  private readonly listeners;
+  private iFramePiP;
+  private bridge;
+  constructor(el: string, options: JetstreamPlayerOptions);
+  private registerEvents;
+  private emit;
+  on<E extends PlayerEvents>(event: E, handler: PlayerEventHandler<E>): () => void;
+  off<E extends PlayerEvents>(event: E, handler?: PlayerEventHandler<E>): void;
+  private request;
+  play(): void;
+  pause(): void;
+  mute(): void;
+  unmute(): void;
+  seekTo(seconds: number): void;
+  playNext(): void;
+  playPrev(): void;
+  isMuted(): Promise<boolean>;
+  isPaused(): Promise<boolean>;
+  getCurrentTime(): Promise<number>;
+  /** @deprecated Use {@link getCurrentTime} instead. */
+  getVideoCurrentTime(): Promise<number>;
+  getDuration(): Promise<number>;
+  dispose(): void;
+}
+//#endregion
+//#region src/bridge/protocol.d.ts
+declare const decodeCommand: (raw: string) => PlayerCommand | null;
+//#endregion
+export { type EmbedFrameOptions, JetstreamPlayer, type JetstreamPlayerOptions, type PlayerCommand, type PlayerCommandEvent, type PlayerEvent, type PlayerEventHandler, type PlayerEventHandlers, type PlayerEventMap, type PlayerEvents, type PlayerGetterEvents, decodeCommand, playerListenEvents };

package/dist/index.js

@@ -1,15 +1,17 @@
 //#region src/bridge/protocol.ts
 const encode = (command) => JSON.stringify(command);
-const decode = (raw) => {
+const parseObjectWithStringKey = (raw, key) => {
 	if (typeof raw !== "string") return null;
 	try {
 		const parsed = JSON.parse(raw);
-		if (typeof parsed === "object" && parsed !== null && typeof parsed.type === "string") return parsed;
+		if (typeof parsed === "object" && parsed !== null && typeof parsed[key] === "string") return parsed;
 		return null;
 	} catch {
 		return null;
 	}
 };
+const decode = (raw) => parseObjectWithStringKey(raw, "type");
+const decodeCommand = (raw) => parseObjectWithStringKey(raw, "name");
 //#endregion
 //#region src/bridge/player-bridge.ts
 const REQUEST_TIMEOUT_MS = 5e3;
@@ -103,7 +105,7 @@ const mountEmbedFrame = (selector, options) => {
 	const iframe = document.createElement("iframe");
 	iframe.allow = "accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture";
 	iframe.allowFullscreen = true;
-	iframe.frameBorder = "0";
+	iframe.style.border = "0";
 	iframe.title = "Jetstream Player";
 	iframe.src = src;
 	iframe.width = options.width || "480px";
@@ -134,8 +136,6 @@ var IFramePiPPlugin = class {
 	originalIframeStyle = null;
 	parent = null;
 	constructor(containerSelector, iframe) {
-		this.containerSelector = containerSelector;
-		this.iframe = iframe;
 		this.containerSelector = containerSelector;
 		this.iframe = iframe;
 		this.init();
@@ -147,8 +147,10 @@ var IFramePiPPlugin = class {
 		this.parent = parent;
 		this.originalParentHeight = parent.style.height || null;
 		this.originalIframeStyle = this.iframe.getAttribute("style");
-		this.observer = new IntersectionObserver(([{ isIntersecting }]) => {
-			if (!isIntersecting) {
+		this.observer = new IntersectionObserver((entries) => {
+			const entry = entries[0];
+			if (!entry) return;
+			if (!entry.isIntersecting) {
 				const height = parent.getBoundingClientRect().height;
 				parent.style.height = `${height}px`;
 				this.iframe.style.position = PiP_STYLES.position;
@@ -253,7 +255,7 @@ var JetstreamPlayer = class {
 	}
 	seekTo(seconds) {
 		this.bridge?.send({
-			name: "seekTo",
+			name: "seek-to",
 			params: seconds
 		});
 	}
@@ -270,7 +272,7 @@ var JetstreamPlayer = class {
 		return this.request({ name: "is-paused" });
 	}
 	getCurrentTime() {
-		return this.request({ name: "get-video-current-time" });
+		return this.request({ name: "get-current-time" });
 	}
 	/** @deprecated Use {@link getCurrentTime} instead. */
 	getVideoCurrentTime() {
@@ -298,4 +300,4 @@ const playerListenEvents = [
 	"error"
 ];
 //#endregion
-export { JetstreamPlayer, playerListenEvents };
+export { JetstreamPlayer, decodeCommand, playerListenEvents };

package/package.json

@@ -1,45 +1,39 @@
 {
   "name": "@hopecloud/jetstream-player",
-  "version": "1.4.0-rc.7",
+  "version": "1.4.0-rc.8",
   "description": "Jetstream Embed Player SDK",
-  "type": "module",
-  "sideEffects": false,
   "homepage": "https://docs.hope.cloud/libs/jetstream-player/",
-  "engines": {
-    "node": "24"
-  },
-  "publishConfig": {
-    "access": "public"
+  "author": {
+    "name": "DV Software",
+    "email": "code@deepvision.software"
   },
-  "main": "dist/index.js",
   "files": [
     "dist"
   ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "dist/index.js",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     }
   },
-  "author": {
-    "email": "code@deepvision.software",
-    "name": "DV Software"
+  "publishConfig": {
+    "access": "public"
   },
   "devDependencies": {
-    "@deepvision/eslint-plugin": "2.0.3",
     "@types/node": "24.12.0",
-    "eslint": "10.1.0",
     "happy-dom": "^20.4.0",
-    "rolldown": "^1.1.4",
-    "typescript": "6.0.3",
-    "vitest": "^4.0.18"
+    "vite-plus": "^0.2.2"
+  },
+  "engines": {
+    "node": "24"
   },
   "scripts": {
-    "build": "rolldown --config && tsc --emitDeclarationOnly",
-    "lint": "eslint",
-    "lint:fix": "eslint --fix",
-    "type-check": "tsc --noEmit",
-    "test": "vitest",
-    "test:run": "vitest run"
+    "build": "vp pack",
+    "check": "vp check",
+    "check:fix": "vp check --fix",
+    "test": "vp test"
   }
 }

package/dist/bridge/player-bridge.d.ts

@@ -1,13 +0,0 @@
-import type { PlayerCommand, PlayerEvent } from './protocol.types';
-import type { PlayerTransport } from './player-transport';
-export declare class PlayerBridge {
-    private readonly transport;
-    private targetOrigin;
-    private readonly listeners;
-    private readonly detach;
-    constructor(transport: PlayerTransport, initialTargetOrigin: string);
-    send(command: PlayerCommand): void;
-    subscribe(listener: (event: PlayerEvent) => void): () => void;
-    request<T>(command: PlayerCommand, timeoutMs?: number): Promise<T>;
-    dispose(): void;
-}

package/dist/bridge/player-transport.d.ts

@@ -1,5 +0,0 @@
-export interface PlayerTransport {
-    send(message: string, targetOrigin: string): void;
-    subscribe(handler: (message: string, origin: string) => void): () => void;
-}
-export declare const windowTransport: (iframe: HTMLIFrameElement) => PlayerTransport;

package/dist/bridge/protocol.d.ts

@@ -1,3 +0,0 @@
-import type { PlayerCommand, PlayerEvent } from './protocol.types';
-export declare const encode: (command: PlayerCommand) => string;
-export declare const decode: (raw: string) => PlayerEvent | null;

package/dist/bridge/protocol.types.d.ts

@@ -1,22 +0,0 @@
-export interface PlayerEventMap {
-    ready: unknown;
-    timeupdate: number;
-    play: unknown;
-    pause: unknown;
-    loadedmetadata: undefined;
-    ended: boolean;
-    volumechange: number;
-    error: unknown;
-}
-export declare const playerListenEvents: readonly ["ready", "timeupdate", "play", "pause", "loadedmetadata", "ended", "volumechange", "error"];
-export type PlayerEvents = (typeof playerListenEvents)[number];
-export type PlayerGetterEvents = 'is-muted' | 'get-video-current-time' | 'get-duration' | 'is-paused';
-export interface PlayerEvent {
-    type: PlayerEvents | PlayerGetterEvents;
-    value?: unknown;
-}
-export type PlayerCommandEvent = 'play' | 'pause' | 'mute' | 'unmute' | 'seekTo' | 'play-next' | 'play-prev';
-export interface PlayerCommand {
-    name: PlayerCommandEvent | PlayerGetterEvents;
-    params?: unknown;
-}

package/dist/embed/embed-frame.d.ts

@@ -1,7 +0,0 @@
-import type { EmbedFrameOptions } from './embed-frame.types';
-export declare const buildEmbedSrc: (options: EmbedFrameOptions) => string;
-export interface MountedFrame {
-    iframe: HTMLIFrameElement;
-    src: string;
-}
-export declare const mountEmbedFrame: (selector: string, options: EmbedFrameOptions) => MountedFrame;

package/dist/embed/embed-frame.types.d.ts

@@ -1,12 +0,0 @@
-export interface EmbedFrameOptions {
-    mediaId: string;
-    playerId?: string;
-    region?: 'eu';
-    audioLang?: string;
-    subtitleLang?: string;
-    embedOrigin?: string;
-    /** @deprecated Use {@link embedOrigin} instead. */
-    origin?: string;
-    width?: string;
-    height?: string;
-}

package/dist/pip/iframe-pip-plugin.d.ts

@@ -1,11 +0,0 @@
-export declare class IFramePiPPlugin {
-    containerSelector: string;
-    iframe: HTMLIFrameElement;
-    private observer;
-    private originalParentHeight;
-    private originalIframeStyle;
-    private parent;
-    constructor(containerSelector: string, iframe: HTMLIFrameElement);
-    init(): void;
-    destroy(): void;
-}

package/dist/player.d.ts

@@ -1,28 +0,0 @@
-import type { PlayerEvents } from './bridge/protocol.types';
-import type { JetstreamPlayerOptions, PlayerEventHandler } from './player.types';
-export declare class JetstreamPlayer {
-    private options;
-    private readonly listeners;
-    private iFramePiP;
-    private bridge;
-    constructor(el: string, options: JetstreamPlayerOptions);
-    private registerEvents;
-    private emit;
-    on<E extends PlayerEvents>(event: E, handler: PlayerEventHandler<E>): () => void;
-    off<E extends PlayerEvents>(event: E, handler?: PlayerEventHandler<E>): void;
-    private request;
-    play(): void;
-    pause(): void;
-    mute(): void;
-    unmute(): void;
-    seekTo(seconds: number): void;
-    playNext(): void;
-    playPrev(): void;
-    isMuted(): Promise<boolean>;
-    isPaused(): Promise<boolean>;
-    getCurrentTime(): Promise<number>;
-    /** @deprecated Use {@link getCurrentTime} instead. */
-    getVideoCurrentTime(): Promise<number>;
-    getDuration(): Promise<number>;
-    dispose(): void;
-}

package/dist/player.types.d.ts

@@ -1,10 +0,0 @@
-import type { PlayerEventMap, PlayerEvents } from './bridge/protocol.types';
-import type { EmbedFrameOptions } from './embed/embed-frame.types';
-export type PlayerEventHandler<E extends PlayerEvents = PlayerEvents> = (value: PlayerEventMap[E]) => void;
-export type PlayerEventHandlers = {
-    [E in PlayerEvents]?: PlayerEventHandler<E>;
-};
-export type JetstreamPlayerOptions = {
-    sticky?: boolean;
-    events?: PlayerEventHandlers;
-} & EmbedFrameOptions;