@meshstream/p2p-web 0.0.0-stage → 0.2.1

package/README.md

@@ -1,3 +1,498 @@
-# Temporary Holding Version
+# MeshStream P2P Web SDK
+
+Browser HLS and DASH P2P delivery SDK for MeshStream P2P-CDN. The SDK wraps
+`hls.js`, Shaka Player, and `p2p-media-loader`, fetches runtime configuration
+from Config API, joins a WebRTC tracker swarm, reports playback/P2P statistics,
+and keeps CDN playback as the fallback path.
+
+## Install
+
+```bash
+# SDK-managed player: MeshStream bundles its HLS, DASH, and P2P runtimes.
+npm install @meshstream/p2p-web
+```
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+For an application-managed `hls.js` instance, install the player in the
+application as well. MeshStream will bind P2P to that instance without taking
+over its configuration or lifecycle:
+
+```bash
+npm install @meshstream/p2p-web hls.js
+```
+
+In this monorepo the SDK is consumed as a workspace package:
+
+```bash
+npm run build:web-sdk
+npm run build -w @p2pcdn/web-demo
+```
+
+## Quick Start
+
+```ts
+import { attach } from "@meshstream/p2p-web";
+
+const player = attach({
+  key: "your_sdk_key",
+  url: "https://cdn.example.com/live/index.m3u8", // or .mpd / .mp4 / .mp3
+  video: document.querySelector("video"),
+});
+
+await player.start();
+
+window.addEventListener("pagehide", () => player.dispose(), { once: true });
+```
+
+The historic `video` option accepts any `HTMLMediaElement`; pass an `<audio>`
+element for progressive MP3 playback.
+
+The SDK fetches SaaS bootstrap configuration, selects trackers/reporting
+endpoints, detects browser capability, starts WebRTC P2P when possible, and
+keeps CDN playback as the automatic fallback path.
+
+When MeshStream creates hls.js, use `hlsConfig` to retain normal player tuning
+such as `maxBufferLength`, ABR limits, or low-latency settings:
+
+```ts
+const player = attach({
+  key,
+  url,
+  video,
+  hlsConfig: { maxBufferLength: 45, lowLatencyMode: true },
+});
+```
+
+MeshStream always reapplies its P2P loader and safe origin request settings
+after the instance is created. For `attachToHls`, configure the caller-owned
+hls.js instance directly instead.
+
+To display compatibility information before playback, call `getCapability()`.
+It returns only `mseSupported`, `webrtcSupported`, and `serviceWorkerSupported`;
+it does not override the SDK's playback or fallback decision.
+
+The web transport selects one content-affine Tracker for a playback session.
+Tracker nodes keep independent in-memory peer maps; switching or retrying a
+Tracker does not copy peers between nodes. If signaling becomes unavailable,
+the player continues through CDN rather than registering the same session with
+every shard. Configure tested hot-content buckets and same-region fallback
+nodes when a stream needs faster recovery.
+
+`player.statistics()` always returns the same complete counter shape. During
+startup and CDN fallback, P2P counters are `0` instead of being omitted, so
+application dashboards can use one schema for HLS, DASH, MP4/MP3, and RxPlayer.
+
+## Optional Service Worker Transport
+
+Service Worker support is an optional transport layer. MSE P2P remains the
+default and is preferred whenever it is available. To deploy the SW runtime,
+copy the published `dist/meshstream-sw.js` file to a same-origin HTTPS path
+such as `/meshstream-sw.js`, then opt in:
+
+```ts
+import { attach } from "@meshstream/p2p-web";
+
+const player = attach({
+  key,
+  url,
+  video,
+  transportPreference: "auto",
+  serviceWorker: {
+    url: "/meshstream-sw.js",
+    scope: "/",
+    autoRegister: true,
+    p2pTimeoutMs: 5000,
+    onSegmentStats: ({ source, bytes, url }) => {
+      console.debug("segment", source, bytes, url);
+    },
+  },
+});
+await player.start();
+```
+
+`auto` uses MSE P2P first. If MSE is unavailable and the page is controlled by
+the registered SW, playback uses a virtual manifest URL under
+`/__meshstream__/v1/`; failed or unavailable page-side P2P requests fall back
+to the original CDN URL. `transportPreference: "service-worker"` is available
+for explicit testing. When bootstrap returns a tracker configuration, the SDK
+also starts a page-side `p2p-media-loader-core` engine that works without MSE,
+indexes HLS master/media playlists, and answers SW segment requests from the
+WebRTC swarm with CDN fallback. A custom `segmentProvider` can still be passed
+to replace that engine for application-specific routing.
+
+For manual registration, import `registerMeshStreamServiceWorker()` and
+`createMeshStreamServiceWorkerSession()` from `@meshstream/p2p-web/service-worker`.
+Registration requires HTTPS (localhost is allowed by browsers), and the SW script
+must be same-origin with the page. Session metadata and rewritten resource mappings
+are kept in IndexedDB so a browser-restarted SW can recover a registered session;
+unregistering the player removes that metadata. `onSegmentStats` reports whether
+each media request was served by the page provider (`p2p`) or CDN (`cdn`).
+
+For a local browser smoke check after building, run
+`node sdks/web/test/sw-browser-fixture.mjs` and open the printed URL. The page
+reports the SW controller state, rewritten segment count, response bodies, and
+per-segment source statistics.
+
+For the real two-page WebRTC check, run the automated smoke from the repository
+root:
+
+```powershell
+npm run test:web-sw-real
+```
+
+It builds the SDK and Tracker, opens seed/follower Chromium pages, and fails
+unless the follower receives a non-empty segment through P2P. For manual
+inspection, build the SDK and start
+`node sdks/web/test/sw-real-p2p-browser-fixture.mjs`, then open the seed URL
+first (`?role=seed`) and the follower URL (`?role=follower`).
+
+### Staging rollout checklist
+
+1. Build the browser package with `npm run build:web-sdk:release` and publish the
+   generated npm tarball. Copy `dist/meshstream-sw.js` from the package to a stable
+   same-origin HTTPS URL such as `/meshstream-sw.js`; do not serve it from a CDN
+   origin or a path outside the intended registration scope.
+2. Deploy the page with `transportPreference: "auto"` and the SW `url` configured.
+   Confirm the normal browser path reports `p2p-hls`; test Safari/iOS or a forced
+   `transportPreference: "service-worker"` path and confirm `sw-hls-cdn`.
+3. Check the browser Network panel for the virtual manifest under
+   `/__meshstream__/v1/` and verify segment requests return either `p2p` or `cdn`
+   in the SDK `onSegmentStats` callback.
+4. Verify the configured report endpoint receives `reportType: "stats"` with
+   `p2pDownloaded`, `httpDownloaded`, `connectedPeers`, and tracker diagnostics.
+   The SDK sends an initial report, periodic reports, and a final `pagehide`
+   report; report failures must not interrupt playback.
+5. Roll back by removing the `serviceWorker` option or setting
+   `transportPreference: "mse"`; the SDK then keeps the existing MSE/CDN path.
+
+## Advanced Player Adapters
+
+Use `@meshstream/p2p-web/adapters` for an existing player instance. Controlled
+test environments that need to construct `MeshStreamHlsPlayer` directly can
+import it from `@meshstream/p2p-web/advanced`; standard integrations should
+continue to use root-level `attach`.
+
+For a plain video element:
+
+```ts
+import { attach } from "@meshstream/p2p-web";
+
+const player = attach({ key, url, video });
+await player.start();
+```
+
+### Choosing an HLS integration
+
+Both HLS modes use the same P2P scheduling, authorization, and telemetry.
+Use `attach` when the SDK should create and manage hls.js. Use `attachToHls`
+when the application already owns an hls.js instance and must retain its
+buffering, ABR, event, or plugin configuration. In the latter mode, the
+application remains responsible for `loadSource`, `attachMedia`, and
+`destroy`; call `session.start()` before `loadSource`. Do not use both modes
+for the same media element or playback URL.
+
+For an existing hls.js instance, bind MeshStream before the application starts
+media loading. This is a native HLS P2P integration: the SDK keeps the caller's
+hls.js configuration and P2P-enables that same instance. It never calls
+`loadSource`, `attachMedia`, or `destroy` on the caller-owned player.
+
+```ts
+import Hls from "hls.js";
+import { attachToHls } from "@meshstream/p2p-web";
+
+const hls = new Hls({ maxBufferLength: 30 });
+const session = attachToHls({ key, url, video, player: hls });
+
+await session.start(); // Bind P2P before hls.js makes media requests.
+hls.loadSource(url);
+hls.attachMedia(video);
+
+window.addEventListener("pagehide", () => {
+  session.dispose(); // Does not destroy hls.
+  hls.destroy();     // The application owns this lifecycle.
+}, { once: true });
+```
+
+For rotating signed URLs, pass a stable business identity so viewers join the
+same swarm. `mimeType` is useful when the media URL has no `.m3u8`, `.mpd`, `.mp4`, or `.mp3`
+suffix. `originHeaders` are sent only to same-origin manifest, segment, and key requests on the
+configured media origin. SDK-controlled headers such as `Range` and hop-by-hop headers are ignored;
+the browser still applies its own forbidden-header and CORS rules. For Shaka and dash.js
+adapter objects, the player must expose its request interception API; otherwise
+the SDK fails explicitly instead of starting without the requested headers.
+
+```ts
+const player = attach({
+  key,
+  url: signedManifestUrl,
+  video,
+  contentId: "live-channel-123",
+  mimeType: "m3u8",
+  originHeaders: { Authorization: "Bearer ...", "X-Playback-Session": "..." },
+});
+await player.start();
+```
+
+For tokens that rotate during a long playback session, provide the current
+value with a synchronous callback. The callback runs immediately before an
+eligible CDN-origin request; it must not refresh a token or return a Promise.
+Refresh credentials in application state first. Dynamic values override static
+headers with the same name and, like static values, are never sent to peers.
+
+```ts
+let playbackToken = initialToken;
+
+const player = attach({
+  key,
+  url: signedManifestUrl,
+  video,
+  originHeaders: { "X-Playback-Session": playbackSession },
+  originHeadersProvider: ({ kind }) =>
+    kind === "segment" ? { Authorization: `Bearer ${playbackToken}` } : undefined,
+});
+```
+
+For Video.js:
+
+```ts
+import { attachToVideoJs } from "@meshstream/p2p-web/adapters";
+
+const player = attachToVideoJs({
+  key,
+  url,
+  player: videojs("player"),
+});
+await player.start();
+```
+
+This adapter follows the Video.js instance lifecycle and disposes the
+MeshStream session automatically when Video.js is destroyed. It is a
+media-element bridge: MeshStream owns protocol-compatible playback for that
+element. For HLS, do not also load the same URL through Video.js VHS.
+
+For Video.js HLS playback that must retain VHS and Video.js ABR ownership, use
+the native VHS adapter instead. It gives VHS a same-origin virtual manifest and
+routes the resulting segment traffic through the Service Worker P2P path. The
+SDK releases its session automatically when Video.js is disposed; if the
+Service Worker cannot start, VHS continues with the original CDN manifest.
+
+```ts
+import { attachToVhs } from "@meshstream/p2p-web/adapters";
+
+const session = attachToVhs({
+  key,
+  url: "https://cdn.example.com/live/index.m3u8",
+  player: videojs("player"),
+  serviceWorker: { url: "/meshstream-sw.js" },
+});
+await session.start();
+```
+
+For players built on top of a standard `<video>` element:
+
+```ts
+import { attachToArtPlayer, attachToDPlayer, attachToPlyr } from "@meshstream/p2p-web/adapters";
+
+await attachToPlyr({ key, url, player: plyr }).start();
+await attachToDPlayer({ key, url, player: dplayer }).start();
+await attachToArtPlayer({ key, url, player: art }).start();
+```
+
+The named adapters resolve common `video` or `media` fields, or a `<video>` nested
+inside the player's root element, and then use the
+same automatic HLS, DASH, and progressive-media path as the plain video adapter. They are media-element bridges,
+not native Video.js, Plyr, DPlayer, or ArtPlayer engine plugins: MeshStream
+owns the playback instance used for the supplied media element.
+
+For DASH with the standard SDK path:
+
+```ts
+import { attach } from "@meshstream/p2p-web";
+
+const player = attach({
+  key,
+  url: "https://cdn.example.com/live/index.mpd",
+  video,
+});
+await player.start();
+```
+
+`attach` selects DASH for `.mpd` URLs and HLS for `.m3u8` URLs. Customers
+do not pass a protocol flag. DASH P2P uses Shaka Player internally for the
+standard SDK path.
+
+For an existing Shaka Player:
+
+```ts
+import { attachToShaka } from "@meshstream/p2p-web/adapters";
+
+const player = attachToShaka({
+  key,
+  url: "https://cdn.example.com/live/index.mpd",
+  player: shakaPlayer,
+});
+await player.start();
+```
+
+`attachToShaka()` binds and releases only the MeshStream P2P session. The
+application retains ownership of the supplied Shaka instance and must destroy
+it when appropriate.
+
+For an existing dash.js player:
+
+```ts
+import { attachToDashJs } from "@meshstream/p2p-web/adapters";
+
+const player = attachToDashJs({
+  key,
+  url: "https://cdn.example.com/live/index.mpd",
+  video,
+  player: dashJsPlayer,
+});
+await player.start();
+```
+
+`attachToDashJs` provides native DASH P2P for dash.js `>= 3.1.0 < 6`. Create
+the dash.js instance first, but do not initialize it or load the MPD before
+`session.start()`: MeshStream installs its `XHRLoader` extension first, then
+initializes the supplied instance. Regular audio/video initialization, index,
+and media segments use P2P with CDN fallback. MPD, DRM licenses, subtitles,
+low-latency partial segments, and credentialed cookie requests remain on the
+customer's dash.js/CDN path. When passing
+`originHeaders` to an existing dash.js or Shaka instance, its request interception
+API is required; native Safari HLS cannot accept arbitrary custom headers, so use
+hls.js or signed URLs for that case.
+
+### Adapter capability matrix
+
+| Player path | P2P integration | Notes |
+| --- | --- | --- |
+| `attach` with HLS | Native hls.js P2P | MeshStream creates and owns hls.js. |
+| `attachToHls` | Native existing hls.js P2P | Application keeps the hls.js lifecycle. |
+| `attach` with DASH; `attachToShaka` with HLS/DASH | Native Shaka P2P | Uses Shaka's networking integration. |
+| `attachToRxPlayer` with DASH | Native RxPlayer segment P2P | Regular DASH segments; same-origin origin headers are supported. |
+| `attachToDashJs` with dash.js `>= 3.1.0 < 6` | Native dash.js P2P | Installs a supported `XHRLoader` extension before dash.js initialization. |
+| `attachToVhs` with Video.js VHS | Native VHS via Service Worker | VHS retains player and ABR ownership; requires a same-origin Service Worker. |
+| `attachToVideoJs`, Plyr, DPlayer, ArtPlayer | Media-element bridge | Not a native plugin for the player's own media engine. |
+
+For an existing RxPlayer DASH instance:
+
+```ts
+import RxPlayer from "rx-player";
+import { attachToRxPlayer } from "@meshstream/p2p-web";
+
+const rxPlayer = new RxPlayer({ videoElement: video });
+const player = attachToRxPlayer({ key, url: dashMpdUrl, contentId: "asset-123", player: rxPlayer });
+await player.start();
+```
+
+`attachToRxPlayer` intercepts RxPlayer's actual DASH audio/video segment loader and sends those
+requests through MeshStream P2P. When `originHeaders` or
+`originHeadersProvider` are configured, same-origin MPD and regular
+audio/video fallback requests retain those headers; dynamic values override
+static values. Cross-origin media, text, DRM, non-contiguous ranges, and
+RxPlayer low-latency chunked loading remain on the customer's RxPlayer/CDN
+path without SDK-supplied headers.
+
+Telemetry keeps the playback host and path for diagnostics but strips query and fragment data,
+so signed playback credentials are not included in reports.
+
+## Runtime Contract
+
+- `key` is the customer-facing SDK Key and can be embedded in Web pages.
+- `homeRegion` is resolved from the SDK Key and identifies the tenant's registered data-home
+  region. It is returned by bootstrap for diagnostics and future regional routing; customer code
+  cannot override it.
+- Request-network GeoIP is used only for access-side Tracker/ICE locality and is not a data-residency
+  selection.
+- Customer integrations should only need `key`, the media `url`, and a `video`
+  element for the standard Web path.
+- The SaaS bootstrap endpoint, tracker pool, ICE servers, reporting route, and
+  scheduling policy are internal service configuration.
+- P2P, tracker, authorization, and reporting failures must not block `hls.js`
+  playback.
+- `detectWebP2pCapability` should be called before constructing the P2P client.
+  iOS Safari HLS without MSE is routed to native HLS CDN playback.
+- Fallback reporting uses the service-owned endpoint returned by bootstrap.
+- Signed CDN URL query fields such as `token`, `signature`, `expires`,
+  `x-amz-*`, `x-oss-*`, and `x-goog-*` are excluded from URL-derived swarm IDs.
+- `contentId` is optional. When supplied, the SDK derives the internal swarm ID
+  from it so rotating signed URL paths remain in the same swarm; otherwise it
+  derives identity from the canonical playback URL.
+- `swarmId` and rendition/quality identifiers are internal runtime values. They
+  are intentionally not part of the customer-facing configuration; the SDK
+  derives and manages them from the content and manifest.
+- Direct progressive `.mp4` and `.mp3` files use the same P2P Service Worker transport as a
+  byte-range stream. The SDK registers the Worker by default for this path and divides the file
+  into deterministic 1 MiB pieces. Large and open-ended ranges are returned as a backpressure-aware
+  stream, so they do not require buffering the whole response in the page. Full-file requests
+  without `Range`, suffix ranges, multi-range requests, and metadata remain on CDN.
+  Use a stable `contentId` when signed URLs have per-viewer path differences.
+- The direct-file origin must support byte ranges, expose `Content-Length`, `Content-Type`, and
+  `Accept-Ranges` through CORS, and allow `GET`, `HEAD`, `OPTIONS`, and the `Range` request header.
+  `HEAD` is recommended; if the origin explicitly returns `405` or `501`, extensionless URL detection
+  uses a one-byte range `GET` instead. Missing metadata or any P2P error falls back to the original CDN URL.
+
+## Public API
+
+```ts
+// Standard customer-facing entry point
+attach(options)
+
+// Advanced player adapters
+import { attachToShaka, attachToDashJs, attachToVhs, attachToVideoJs } from "@meshstream/p2p-web/adapters";
+
+// P2P runtime controls
+player.start()
+player.dispose()
+player.setP2pEnabled(enabled)
+player.addEventListener(listener) // returns unsubscribe
+player.statistics()
+player.diagnostics()
+player.qoe()
+```
+
+`setP2pEnabled(false)` may be called before `start()` to force a CDN-only
+session, or during playback to stop P2P without interrupting CDN delivery.
+Repeated `start()` calls share the active session; call `dispose()` before
+starting a fresh session for a different source or player lifecycle.
+
+`start()` returns `{ mode, capability, fallbackReason? }`. On a CDN fallback,
+`fallbackReason` is one of `CAPABILITY_UNSUPPORTED`, `P2P_DISABLED`,
+`SDK_CONFIG_UNAVAILABLE`, `TRACKER_UNAVAILABLE`, or
+`P2P_INITIALIZATION_FAILED`. It is intended for customer telemetry and does
+not expose the server bootstrap configuration.
+
+`addEventListener()` accepts `onPlaybackStateChanged`, `onP2pReady`,
+`onP2pUnavailable`, `onPeerCountChanged`, `onTrackerError`,
+`onPeerConnectError`, `onCdnFallback`, and `onStatistics`. Register before `start()` when the
+initial connection state matters. Startup CDN fallbacks emit `UNSUPPORTED`,
+`DISABLED`, `CONFIG_UNAVAILABLE`, `TRACKER_ERROR`, or
+`INITIALIZATION_FAILED`; call the returned function during cleanup.
+
+`onPlaybackStateChanged` reports `idle`, `initializing`, `connecting`,
+`p2p-ready`, `cdn-fallback`, and `disposed`. `qoe()` returns a safe
+application-telemetry snapshot: total/P2P/CDN download bytes, P2P download
+ratio, connected peers, first-peer latency when available, cold-start CDN
+bytes, and fallback count. It intentionally excludes Tracker, ICE, and peer
+identifiers.
+
+Low-latency HLS/DASH partial CMAF segment requests remain on the player CDN
+path. P2P only distributes complete segments: sharing a response before its
+partial body is complete breaks player cancellation semantics and causes
+latency jitter. Playback continues normally through CDN for those parts.
+
+## Release Checks
+
+```bash
+npm test -w @meshstream/p2p-web
+npm run build:web-sdk:release
+npm run pack:dry-run -w @meshstream/p2p-web
+```
+
+`prepack` runs the SDK test suite, bundles the runtime dependencies into the
+public entry points, and then minifies the release output before package
+creation. The published package contains only bundled JavaScript, `.d.ts`
+types, the Service Worker, README, and licenses; customers do not need to
+install the internal player or P2P packages separately. Public exports and
+object property names remain stable, while readable formatting and source maps
+are omitted from the published JavaScript.

package/dist/adapters.d.ts

@@ -0,0 +1,140 @@
+import type { ShakaPlayerLike } from "./dash-p2p.js";
+import { type HlsLike, type MeshStreamP2pFallbackReason, type MeshStreamServiceWorkerTransportOptions, type MeshStreamTransportPreference } from "./player.js";
+import type { P2pEventListener } from "./hls.js";
+import { type P2pStats } from "./report.js";
+import type { WebP2pCapabilityResult } from "./capabilities.js";
+import { type MeshStreamQoeSnapshot } from "./qoe.js";
+import { type OriginHeadersProvider } from "./origin-headers.js";
+import { type MeshStreamRxPlayerOptions } from "./rx-player.js";
+export interface MeshStreamAttachToVideoOptions {
+    key: string;
+    url: string;
+    video: HTMLMediaElement;
+    contentId?: string;
+    mimeType?: "m3u8" | "mpd" | "mp4" | "mp3";
+    /** Optional Config API bootstrap endpoint, mainly for private deployments. */
+    bootstrapUrl?: string;
+    originHeaders?: Record<string, string>;
+    /** Resolves request headers immediately before an origin CDN request. */
+    originHeadersProvider?: OriginHeadersProvider;
+    autoplay?: boolean;
+    /** Set `false` to start this session on CDN without creating P2P transport. */
+    p2pEnabled?: boolean;
+    httpDownloadInitialTimeoutMs?: number;
+    /** hls.js options used only when MeshStream creates the HLS instance. */
+    hlsConfig?: Record<string, unknown>;
+    transportPreference?: MeshStreamTransportPreference;
+    serviceWorker?: MeshStreamServiceWorkerTransportOptions;
+}
+export type MeshStreamAttachToMediaOptions = MeshStreamAttachToVideoOptions;
+/** Standard customer-facing configuration for MeshStream Web playback. */
+export type MeshStreamAttachOptions = MeshStreamAttachToMediaOptions;
+/** Playback state and transfer callbacks shared by every MeshStream adapter. */
+export type MeshStreamP2pEventListener = P2pEventListener;
+/** A common, configuration-safe result returned by every public media adapter. */
+export interface MeshStreamPlaybackStartResult {
+    mode: string;
+    capability?: WebP2pCapabilityResult;
+    fallbackReason?: MeshStreamP2pFallbackReason;
+}
+export type { MeshStreamP2pFallbackReason } from "./player.js";
+export interface MeshStreamMediaPlayer {
+    start(): Promise<MeshStreamPlaybackStartResult>;
+    setP2pEnabled(enabled: boolean): void;
+    /**
+     * Subscribes to P2P playback events. The returned function removes this
+     * listener and is safe to call more than once.
+     */
+    addEventListener(listener: MeshStreamP2pEventListener): () => void;
+    statistics(): P2pStats;
+    diagnostics(): {
+        lastPeerError?: string;
+        lastTrackerError?: string;
+    };
+    qoe(): MeshStreamQoeSnapshot;
+    dispose(): void;
+}
+type MeshStreamMediaMimeType = NonNullable<MeshStreamAttachToVideoOptions["mimeType"]>;
+export interface MeshStreamAttachToVideoJsOptions extends Omit<MeshStreamAttachToVideoOptions, "video"> {
+    player: VideoJsLikePlayer;
+}
+/** Native Video.js VHS path. VHS retains player and ABR ownership. */
+export interface MeshStreamAttachToVhsOptions extends Omit<MeshStreamAttachToVideoOptions, "video" | "mimeType"> {
+    mimeType?: "m3u8";
+    player: VideoJsVhsLikePlayer;
+}
+/**
+ * Binds P2P to an existing hls.js instance without taking over its lifecycle.
+ * Call start() before the application calls hls.loadSource().
+ */
+export interface MeshStreamAttachToHlsOptions extends Omit<MeshStreamAttachToVideoOptions, "mimeType" | "hlsConfig"> {
+    player: HlsLike;
+}
+export interface MeshStreamAttachToDashJsOptions extends Omit<MeshStreamAttachToVideoOptions, "video" | "mimeType"> {
+    /** Required before dash.js initialization; otherwise resolved from the player. */
+    video?: HTMLMediaElement;
+    mimeType?: "mpd";
+    player: DashJsLikePlayer;
+}
+export interface MeshStreamAttachToShakaOptions extends Omit<MeshStreamAttachToVideoOptions, "video" | "mimeType"> {
+    mimeType?: "m3u8" | "mpd";
+    player: ShakaLikePlayer;
+}
+export interface MeshStreamAttachToWrappedPlayerOptions extends Omit<MeshStreamAttachToVideoOptions, "video"> {
+    player: WrappedVideoPlayer;
+}
+export type MeshStreamAttachToRxPlayerOptions = MeshStreamRxPlayerOptions;
+export interface VideoJsLikePlayer {
+    el?: () => unknown;
+    tech?: (safe?: boolean) => unknown;
+    on?: (event: string, listener: () => void) => void;
+    off?: (event: string, listener: () => void) => void;
+}
+export interface VideoJsVhsLikePlayer extends VideoJsLikePlayer {
+    src?: (source: {
+        src: string;
+        type?: string;
+    } | string) => unknown;
+}
+export interface WrappedVideoPlayer {
+    video?: unknown;
+    media?: unknown;
+    el?: unknown;
+    element?: unknown;
+}
+export interface DashJsLikePlayer {
+    getVideoElement?: () => unknown;
+    initialize?: (video: HTMLMediaElement, url: string, autoplay?: boolean) => void;
+    addRequestInterceptor?(interceptor: Function): void;
+    removeRequestInterceptor?(interceptor: Function): void;
+    reset?: () => void;
+}
+export interface ShakaLikePlayer extends ShakaPlayerLike {
+    getMediaElement?: () => HTMLMediaElement | null;
+}
+export declare function attachToVideo(options: MeshStreamAttachToVideoOptions): MeshStreamMediaPlayer;
+export declare function attachToHls(options: MeshStreamAttachToHlsOptions): MeshStreamMediaPlayer;
+/** Standard integration entry point. Selects HLS or DASH from the manifest URL. */
+export declare function attach(options: MeshStreamAttachOptions): MeshStreamMediaPlayer;
+export declare function attachToMedia(options: MeshStreamAttachToMediaOptions): MeshStreamMediaPlayer;
+/**
+ * Probes extensionless media URLs without replaying customer headers. A small
+ * range GET is used only when the origin explicitly does not support HEAD.
+ */
+export declare function probeMediaType(url: string, fetcher?: typeof fetch, signal?: AbortSignal): Promise<MeshStreamMediaMimeType | undefined>;
+export declare function attachToDashJs(options: MeshStreamAttachToDashJsOptions): MeshStreamMediaPlayer;
+export declare function attachToShaka(options: MeshStreamAttachToShakaOptions): MeshStreamMediaPlayer;
+export declare function attachToVideoJs(options: MeshStreamAttachToVideoJsOptions): MeshStreamMediaPlayer;
+/**
+ * Uses the Video.js VHS engine with MeshStream's Service Worker transport.
+ * Do not combine this with attachToVideoJs(), which creates a separate hls.js
+ * playback path for the same media element.
+ */
+export declare function attachToVhs(options: MeshStreamAttachToVhsOptions): MeshStreamMediaPlayer;
+export declare function attachToPlyr(options: MeshStreamAttachToWrappedPlayerOptions): MeshStreamMediaPlayer;
+export declare function attachToDPlayer(options: MeshStreamAttachToWrappedPlayerOptions): MeshStreamMediaPlayer;
+export declare function attachToArtPlayer(options: MeshStreamAttachToWrappedPlayerOptions): MeshStreamMediaPlayer;
+/** Attach a DASH-capable RxPlayer through its real segment-loader API. */
+export declare function attachToRxPlayer(options: MeshStreamAttachToRxPlayerOptions): MeshStreamMediaPlayer;
+export declare function resolveVideoJsElement(player: VideoJsLikePlayer): HTMLMediaElement | undefined;
+export declare function resolveWrappedVideoElement(player: WrappedVideoPlayer): HTMLMediaElement | undefined;