@meshstream/p2p-web 0.0.0-stage → 0.2.1

package/dist/meshstream-sw.js

@@ -0,0 +1 @@
+(()=>{const e="/__meshstream__/v1/",t="sessions",s=globalThis,n=new Map,r=new Set(["connection","content-length","host","proxy-connection","range","transfer-encoding","upgrade"]);async function o(e,t,s,n=s.manifestUrl){const r=await d(e,t,n,s);if(!r.ok)return r;const o=function(e,t,s){return e.split(/\r?\n/).map(e=>!e||e.startsWith("#")?e.replace(/URI="([^"]+)"/g,(e,n)=>`URI="${i(n,t,s)}"`):i(e,t,s)).join("\n")}(await r.text(),s,n);await f(s);const a=new Headers(r.headers);return a.delete("content-length"),new Response(o,{status:r.status,statusText:r.statusText,headers:a})}function i(t,s,n){const r=new URL(t,n).toString();let o=[...s.resources.entries()].find(e=>e[1]===r)?.[0];return o||(o=`r${s.resources.size+1}`,s.resources.set(o,r)),`${e}${encodeURIComponent(s.sessionId)}/${o}`}async function a(e,t,s,n){const r=t.pageBridge,o=r?void 0:await S(e,t);if(!r&&!o)return;const i=new MessageChannel,a=e.request,d=new Promise(e=>{let s,n,r=!1,o=!1,a=!1;const d=new Promise(e=>{n=e}),u=()=>{if(!o){o=!0;try{i.port1.close()}catch{}}},p=t=>{r||(r=!0,clearTimeout(l),t||u(),e(t))},l=setTimeout(()=>{p(void 0)},t.p2pTimeoutMs);i.port1.onmessage=e=>{const t=e.data||{};if("MESHSTREAM_SW_SEGMENT_RESPONSE"===t.type&&t.body){const e=new Headers(t.headers||{}),s="cdn"===t.source?"cdn":"p2p";"cdn"===s&&e.set("x-meshstream-source","cdn");const n=Number.isFinite(t.bytes)?Math.max(0,t.bytes):t.body.byteLength;return e.has("content-length")||e.set("content-length",String(n)),p({response:new Response(t.body,{status:t.status||200,statusText:t.statusText||"",headers:e}),completion:Promise.resolve({source:s,bytes:n,status:t.status||200,p2pBytes:c(t.p2pBytes),cdnBytes:c(t.cdnBytes)})}),void u()}if("MESHSTREAM_SW_SEGMENT_STREAM_START"===t.type){const e=c(t.bytes);if(void 0===e||r)return void p(void 0);const n=new Headers(t.headers||{});"cdn"===t.source&&n.set("x-meshstream-source","cdn"),n.has("content-length")||n.set("content-length",String(e));const u=new ReadableStream({pull(e){s=e,a||o||(a=!0,i.port1.postMessage({type:"MESHSTREAM_SW_SEGMENT_STREAM_PULL"}))},cancel(){i.port1.postMessage({type:"MESHSTREAM_SW_SEGMENT_STREAM_CANCEL"})}});return void p({response:new Response(u,{status:t.status||200,statusText:t.statusText||"",headers:n}),completion:d})}if("MESHSTREAM_SW_SEGMENT_STREAM_CHUNK"===t.type&&t.body instanceof ArrayBuffer)return a=!1,void s?.enqueue(new Uint8Array(t.body));"MESHSTREAM_SW_SEGMENT_STREAM_COMPLETE"!==t.type&&"MESHSTREAM_SW_SEGMENT_STREAM_ERROR"!==t.type?r||p(void 0):((e,t=!1)=>{if(r){try{t?s?.error(new Error("MeshStream progressive-media stream failed")):s?.close()}catch{}n?.(e),u()}else p(void 0)})({source:"p2p"===t.source?"p2p":"cdn",bytes:c(t.bytes)??0,status:t.status||200,p2pBytes:c(t.p2pBytes),cdnBytes:c(t.cdnBytes)},"MESHSTREAM_SW_SEGMENT_STREAM_ERROR"===t.type)}});try{const e={type:"MESHSTREAM_SW_SEGMENT_REQUEST",protocolVersion:1,sessionId:t.sessionId,resourceId:s,url:n,headers:Object.fromEntries(a.headers.entries())};r?r.postMessage(e,[i.port2]):o?.postMessage(e,[i.port2])}catch{try{i.port1.close()}catch{}return}return d}function c(e){return"number"==typeof e&&Number.isFinite(e)?Math.max(0,e):void 0}async function d(e,t,n,r){const o=new Headers(t.headers),i=new URL(n.toString(),s.location?.origin||void 0);return i.origin===r.manifestUrl.origin&&(u(o,r.originHeaders),u(o,await async function(e,t,s){const n=t.pageBridge??await S(e,t);if(!n)return{};const r=new MessageChannel;return new Promise(e=>{let o=!1;const i=t=>{if(!o){o=!0,clearTimeout(a);try{r.port1.close()}catch{}var s;e((s=t)&&"object"==typeof s&&Object.values(s).every(e=>"string"==typeof e)?t:{})}},a=setTimeout(()=>i({}),750);r.port1.onmessage=e=>{const t=e.data||{};"MESHSTREAM_SW_ORIGIN_HEADERS_RESPONSE"===t.type?i(t.headers):i({})};try{n.postMessage({type:"MESHSTREAM_SW_ORIGIN_HEADERS_REQUEST",sessionId:t.sessionId,url:s,kind:p(s)},[r.port2])}catch{i({})}})}(e,r,i.toString()))),fetch(i,{method:t.method,headers:o,redirect:"follow",referrer:t.referrer,referrerPolicy:t.referrerPolicy})}function u(e,t){for(const[s,n]of Object.entries(t||{})){const t=s.trim().toLowerCase();if(t&&!r.has(t)&&!t.startsWith("proxy-")&&n.trim())try{e.set(s,n)}catch{}}}function p(e){const t=new URL(e,s.location?.origin||void 0).pathname.toLowerCase();return/\.(m3u8|mpd)$/.test(t)?"manifest":/\.(key|lic)$/.test(t)?"key":/\.(mp4|mp3)$/.test(t)?"direct-file":/\.(ts|m4s|m4a|aac|mp4a|cmfv|cmfa|webm)$/.test(t)?"segment":"unknown"}async function l(e,t,s,n,r,o,i,a,c){try{const d={type:"MESHSTREAM_SW_SEGMENT_RESULT",sessionId:t.sessionId,resourceId:s,url:n,source:r,bytes:o,status:i,...void 0!==a?{p2pBytes:a}:{},...void 0!==c?{cdnBytes:c}:{}};if(t.pageBridge)return void t.pageBridge.postMessage(d);const u=await S(e,t);u?.postMessage(d)}catch{}}async function S(e,t){const n=e.clientId||t.ownerClientId;if(n)try{return await s.clients.get(n)}catch{return}}async function E(e,t="GET"){if("HEAD"===t.toUpperCase())return 0;const s=e.headers.get("content-length");if(s&&Number.isFinite(Number(s)))return Math.max(0,Number(s));try{return(await e.clone().arrayBuffer()).byteLength}catch{return 0}}async function f(e){try{const s=await m();await y(s.transaction(t,"readwrite").objectStore(t).put({sessionId:e.sessionId,manifestUrl:e.manifestUrl.toString(),resourceKind:e.resourceKind,originHeaders:e.originHeaders,p2pTimeoutMs:e.p2pTimeoutMs,ownerClientId:e.ownerClientId,resources:[...e.resources.entries()]}))}catch{}}function m(){const e=s.indexedDB;return e?new Promise((s,n)=>{const r=e.open("meshstream-sw",1);r.onupgradeneeded=()=>{r.result.createObjectStore(t,{keyPath:"sessionId"})},r.onsuccess=()=>s(r.result),r.onerror=()=>n(r.error||new Error("IndexedDB open failed"))}):Promise.reject(new Error("IndexedDB is unavailable"))}function y(e){return new Promise((t,s)=>{e.onsuccess=()=>t(e.result),e.onerror=()=>s(e.error||new Error("IndexedDB request failed"))})}s.addEventListener("install",e=>{e.waitUntil?.(s.skipWaiting())}),s.addEventListener("activate",e=>{e.waitUntil?.(s.clients.claim())}),s.addEventListener("message",e=>{const r=e.data||{};if(1===r.protocolVersion)if("MESHSTREAM_SW_PING"!==r.type){if("MESHSTREAM_SW_REGISTER_SESSION"===r.type&&r.sessionId&&r.manifestUrl){const t={sessionId:r.sessionId,manifestUrl:new URL(r.manifestUrl,s.location?.origin||void 0),resourceKind:"direct-file"===r.resourceKind?"direct-file":"hls",originHeaders:r.originHeaders||{},p2pTimeoutMs:Number.isFinite(r.p2pTimeoutMs)?r.p2pTimeoutMs:5e3,ownerClientId:"string"==typeof e.source?.id?e.source.id:void 0,pageBridge:e.ports?.[1],resources:new Map};n.set(r.sessionId,t);const o=f(t).finally(()=>{e.ports?.[0]?.postMessage({type:"MESHSTREAM_SW_SESSION_READY",sessionId:r.sessionId})});return e.waitUntil?.(o),void e.waitUntil}if("MESHSTREAM_SW_UNREGISTER_SESSION"===r.type&&r.sessionId){n.delete(r.sessionId);const s=async function(e){try{const s=await m();await y(s.transaction(t,"readwrite").objectStore(t).delete(e))}catch{}}(r.sessionId).finally(()=>{e.ports?.[0]?.postMessage({type:"MESHSTREAM_SW_SESSION_REMOVED",sessionId:r.sessionId})});e.waitUntil?.(s),e.waitUntil}}else e.ports?.[0]?.postMessage({type:"MESHSTREAM_SW_READY",protocolVersion:1})}),s.addEventListener("fetch",s=>{s.request&&s.respondWith&&new URL(s.request.url).pathname.startsWith(e)&&s.respondWith(async function(s){const r=s.request,i=function(t){if(!t.startsWith(e))return;const s=t.slice(19).split("/");return s.length<2?void 0:{sessionId:decodeURIComponent(s[0]),resourceId:s.slice(1).join("/")}}(new URL(r.url).pathname);if(!i)return new Response("MeshStream Service Worker request unavailable",{status:400});const c=await async function(e){const s=n.get(e);if(s)return s;const r=await async function(e){try{const s=await m(),n=await y(s.transaction(t,"readonly").objectStore(t).get(e));if(!n?.manifestUrl)return;return{sessionId:e,manifestUrl:new URL(n.manifestUrl),resourceKind:"direct-file"===n.resourceKind?"direct-file":"hls",originHeaders:n.originHeaders||{},p2pTimeoutMs:Number.isFinite(n.p2pTimeoutMs)?n.p2pTimeoutMs:5e3,ownerClientId:"string"==typeof n.ownerClientId?n.ownerClientId:void 0,resources:new Map(Array.isArray(n.resources)?n.resources:[])}}catch{return}}(e);return r?(n.set(e,r),r):void 0}(i.sessionId);if(!c)return new Response("MeshStream Service Worker session unavailable",{status:503});if("manifest"===i.resourceId)return"direct-file"===c.resourceKind?async function(e,t){const s=e.request,n=t.manifestUrl.toString(),r=await a(e,t,"direct",n);if(r){r.response.headers.delete("x-meshstream-source");const s=r.completion.then(s=>l(e,t,"direct",n,s.source,s.bytes,s.status,s.p2pBytes,s.cdnBytes));return e.waitUntil?.(s),r.response}const o=await d(e,s,t.manifestUrl,t),i=l(e,t,"direct",n,"cdn",await E(o,s.method),o.status);return e.waitUntil?.(i),o}(s,c):o(s,r,c);const u=c.resources.get(i.resourceId);if(!u)return new Response("MeshStream resource unavailable",{status:404});if(/\.m3u8(?:$|[?#])/i.test(u))return o(s,r,c,new URL(u));const p=await a(s,c,i.resourceId,u);if(p){p.response.headers.delete("x-meshstream-source");const e=p.completion.then(e=>l(s,c,i.resourceId,u,e.source,e.bytes,e.status,e.p2pBytes,e.cdnBytes));return s.waitUntil?.(e),p.response}const S=await d(s,r,u,c),f=l(s,c,i.resourceId,u,"cdn",await E(S,r.method),S.status);return s.waitUntil?.(f),S}(s))})})();

package/dist/origin-headers.d.ts

@@ -0,0 +1,36 @@
+export type OriginHeaders = Record<string, string>;
+/** Media request classes exposed to the origin-header callback. */
+export type OriginRequestKind = "manifest" | "segment" | "key" | "direct-file" | "unknown";
+/**
+ * Resolves origin-only request headers immediately before a CDN request.
+ * The callback is synchronous by design: media loaders cannot safely pause an
+ * in-flight request while an application refreshes credentials. Keep a fresh
+ * token in application state and return it here. These headers are never sent
+ * over a WebRTC peer connection.
+ */
+export type OriginHeadersProvider = (request: {
+    url: string;
+    kind: OriginRequestKind;
+}) => OriginHeaders | undefined;
+export interface SegmentByteRange {
+    start: number;
+    end?: number;
+}
+export type OriginHttpRequestSetup = (segmentUrl: string, segmentByteRange: SegmentByteRange | undefined, requestAbortSignal: AbortSignal | undefined, requestByteRange: SegmentByteRange | undefined) => Promise<Request | undefined>;
+export declare function hasOriginHeaders(headers?: OriginHeaders, provider?: OriginHeadersProvider): boolean;
+export declare function createOriginRequestSetup(headers?: OriginHeaders, provider?: OriginHeadersProvider, mediaUrl?: string): OriginHttpRequestSetup | undefined;
+export declare function applyOriginHeadersToXhrSetup(config: {
+    xhrSetup?: (xhr: XMLHttpRequest, url: string) => void;
+}, headers?: OriginHeaders, provider?: OriginHeadersProvider): void;
+export declare function applyOriginHeadersToShaka(player: {
+    getNetworkingEngine?: () => unknown;
+}, headers?: OriginHeaders, mediaUrl?: string, provider?: OriginHeadersProvider): boolean;
+export interface DashRequest {
+    url?: string;
+    headers?: Record<string, string>;
+}
+export type DashRequestInterceptor = (request: DashRequest) => Promise<DashRequest>;
+export declare function createDashOriginHeadersInterceptor(headers?: OriginHeaders, mediaUrl?: string, provider?: OriginHeadersProvider): DashRequestInterceptor | undefined;
+/** Resolves static and callback headers with callback values taking precedence. */
+export declare function resolveOriginHeaders(headers: OriginHeaders | undefined, provider: OriginHeadersProvider | undefined, url: string, kind?: OriginRequestKind): OriginHeaders;
+export declare function inferOriginRequestKind(url: string): OriginRequestKind;

package/dist/playback-auth.d.ts

@@ -0,0 +1,14 @@
+import type { SdkPlaybackAuthPolicy } from "./config.js";
+export type PlaybackAuthMode = "none" | "signed-url" | string;
+export type PlaybackAuthStatus = "none" | "valid" | "missing-signature" | "expired-url" | "invalid-url";
+export interface PlaybackAuthDiagnostics {
+    mode: PlaybackAuthMode;
+    status: PlaybackAuthStatus;
+    signatureKey?: string;
+    expiresKey?: string;
+    expiresAtSeconds?: number;
+}
+export interface EvaluatePlaybackAuthOptions {
+    nowSeconds?: () => number;
+}
+export declare function evaluatePlaybackAuth(playbackUrl: string, policy: SdkPlaybackAuthPolicy | undefined, options?: EvaluatePlaybackAuthOptions): PlaybackAuthDiagnostics;

package/dist/playback-lifecycle.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Guards asynchronous player startup against a component being disposed or
+ * replaced while configuration, token, or player setup is still in flight.
+ */
+export declare class MeshStreamPlaybackLifecycle {
+    private generation;
+    begin(): number;
+    cancel(): void;
+    isCurrent(generation: number): boolean;
+    assertCurrent(generation: number): void;
+}

package/dist/player.d.ts

@@ -0,0 +1,160 @@
+import type { WebP2pCapabilityResult } from "./capabilities.js";
+import type { OriginHeadersProvider } from "./origin-headers.js";
+import type { LoadSdkConfigOptions, SdkConfigRequest, SdkConfigResponse } from "./config.js";
+import { reportWebP2pFallback } from "./fallback.js";
+import type { HlsP2pConfig, P2pEventListener, P2pUnavailableReason } from "./hls.js";
+import { type P2pDiagnostics, type P2pStats } from "./report.js";
+import { type MeshStreamServiceWorkerClient, type MeshStreamServiceWorkerRegistrationOptions, type MeshStreamServiceWorkerSession, type MeshStreamServiceWorkerSessionOptions, type MeshStreamSwSegmentProvider, type MeshStreamSwSegmentStats } from "./service-worker.js";
+import { type MeshStreamServiceWorkerP2pDiagnostics } from "./service-worker-p2p.js";
+import { type MeshStreamQoeSnapshot } from "./qoe.js";
+export type MeshStreamPlaybackMode = "p2p-hls" | "sw-hls-p2p" | "sw-hls-cdn" | "cdn-hls" | "native-hls-cdn" | "sw-direct-p2p" | "sw-direct-cdn" | "cdn-direct" | "unsupported";
+export type MeshStreamTransportPreference = "auto" | "mse" | "service-worker" | "cdn";
+export type MeshStreamP2pFallbackReason = "CAPABILITY_UNSUPPORTED" | "P2P_DISABLED" | "SDK_CONFIG_UNAVAILABLE" | "KEY_P2P_DISABLED" | "QUOTA_EXHAUSTED" | "QUOTA_DISABLED" | "TRACKER_UNAVAILABLE" | "P2P_INITIALIZATION_FAILED";
+export declare function toP2pUnavailableReason(fallbackReason: MeshStreamP2pFallbackReason | undefined): P2pUnavailableReason | undefined;
+export declare function sdkConfigFallbackReason(config: SdkConfigResponse | undefined): MeshStreamP2pFallbackReason;
+export interface MeshStreamServiceWorkerTransportOptions extends Omit<MeshStreamServiceWorkerRegistrationOptions, "registration"> {
+    autoRegister?: boolean;
+    p2pTimeoutMs?: number;
+    segmentProvider?: MeshStreamSwSegmentProvider;
+    onSegmentStats?: (stats: MeshStreamSwSegmentStats) => void;
+}
+export interface MeshStreamHlsPlayerOptions {
+    url: string;
+    video: HTMLMediaElement;
+    contentId?: string;
+    mimeType?: "m3u8" | "mpd" | "mp4" | "mp3";
+    originHeaders?: Record<string, string>;
+    /** Resolves dynamic headers for CDN-origin media requests only. */
+    originHeadersProvider?: OriginHeadersProvider;
+    bootstrapUrl?: string;
+    key?: string;
+    networkType?: string;
+    liveWindowBucket?: string;
+    autoplay?: boolean;
+    p2pEnabled?: boolean;
+    httpDownloadInitialTimeoutMs?: number;
+    /**
+     * hls.js options for SDK-owned HLS playback. MeshStream always overrides its
+     * loader settings afterwards so P2P and CDN fallback remain intact.
+     */
+    hlsConfig?: Record<string, unknown>;
+    iceServers?: RTCIceServer[];
+    logLevel?: "none" | "error" | "warn" | "info" | "debug";
+    transportPreference?: MeshStreamTransportPreference;
+    serviceWorker?: MeshStreamServiceWorkerTransportOptions;
+    /**
+     * An existing hls.js instance. MeshStream binds P2P to it but never loads a
+     * source, attaches media, or destroys the caller-owned instance.
+     */
+    hlsjsInstance?: HlsLike;
+    /**
+     * Internal adapter hook for an external HLS engine such as Video.js VHS.
+     * The owner keeps playback and ABR control while MeshStream supplies either
+     * a virtual Service Worker manifest or the original CDN manifest.
+     */
+    loadExternalHls?: (url: string) => void | Promise<void>;
+    onHlsCreated?: (hls: HlsLike) => void;
+    dependencies?: MeshStreamHlsPlayerDependencies;
+}
+export interface MeshStreamHlsStartResult {
+    mode: MeshStreamPlaybackMode;
+    capability: WebP2pCapabilityResult;
+    sdkConfig?: SdkConfigResponse;
+    fallbackReason?: MeshStreamP2pFallbackReason;
+}
+export interface MeshStreamHlsPlayerDependencies {
+    loadSdkConfig?: (request: SdkConfigRequest, options?: LoadSdkConfigOptions) => Promise<SdkConfigResponse | undefined>;
+    detectCapability?: () => WebP2pCapabilityResult;
+    createHls?: (config?: Record<string, unknown>) => HlsLike | Promise<HlsLike>;
+    createP2pClient?: (config: HlsP2pConfig) => HlsP2pClientLike | Promise<HlsP2pClientLike>;
+    createServiceWorkerSession?: (options: MeshStreamServiceWorkerSessionOptions) => Promise<MeshStreamServiceWorkerSession | undefined>;
+    registerServiceWorker?: (options?: MeshStreamServiceWorkerRegistrationOptions) => Promise<MeshStreamServiceWorkerClient>;
+    isServiceWorkerSupported?: () => boolean;
+    reportFallback?: typeof reportWebP2pFallback;
+    hlsIsSupported?: () => boolean | Promise<boolean>;
+}
+export interface HlsP2pClientLike {
+    swarmId: string;
+    addEventListener(listener: P2pEventListener): void;
+    removeEventListener(listener: P2pEventListener): void;
+    getHlsConfig(): Record<string, unknown>;
+    statistics(): P2pStats;
+    diagnostics(): Partial<P2pDiagnostics>;
+    setP2pEnabled(enabled: boolean): void;
+    dispose(): void;
+}
+export interface HlsLike {
+    config: Record<string, unknown>;
+    loadSource(url: string): void;
+    attachMedia(video: HTMLMediaElement): void;
+    on(event: string, listener: (...args: unknown[]) => void): void;
+    destroy(): void;
+}
+export declare class MeshStreamHlsPlayer {
+    readonly key: string;
+    readonly url: string;
+    readonly video: HTMLMediaElement;
+    private readonly options;
+    private readonly ownsHlsInstance;
+    private hls?;
+    private p2p?;
+    private serviceWorkerClient?;
+    private serviceWorkerSession?;
+    private serviceWorkerP2pEngine?;
+    private serviceWorkerStats;
+    private serviceWorkerReportUrl?;
+    private serviceWorkerReportTimer?;
+    private serviceWorkerReportInFlight;
+    private serviceWorkerReportTask?;
+    private serviceWorkerTeardownTask?;
+    private serviceWorkerHasReportedContext;
+    private serviceWorkerTrackerUrl?;
+    private serviceWorkerAppId?;
+    private serviceWorkerKeyId?;
+    private serviceWorkerSwarmId?;
+    private serviceWorkerUploadSlots;
+    private serviceWorkerDownloadSlots;
+    private readonly serviceWorkerPagehideHandler;
+    private sessionId;
+    private sessionTokenManager?;
+    private mode;
+    private p2pEnabledOverride?;
+    private readonly eventListeners;
+    private playbackState;
+    private readonly lifecycle;
+    private startPromise?;
+    private startResult?;
+    constructor(options: MeshStreamHlsPlayerOptions);
+    get p2pClient(): HlsP2pClientLike | undefined;
+    get playbackMode(): MeshStreamPlaybackMode;
+    start(): Promise<MeshStreamHlsStartResult>;
+    private startInternal;
+    statistics(): P2pStats;
+    diagnostics(): Partial<P2pDiagnostics> & Partial<MeshStreamServiceWorkerP2pDiagnostics>;
+    qoe(): MeshStreamQoeSnapshot;
+    setP2pEnabled(enabled: boolean): void;
+    addEventListener(listener: P2pEventListener): () => void;
+    dispose(): void;
+    private teardown;
+    private startServiceWorkerReporting;
+    private bindEventListeners;
+    private bindServiceWorkerEventListeners;
+    private completeFallbackStart;
+    private removeEventListener;
+    private setPlaybackState;
+    private resolveQoePlaybackState;
+    private stopServiceWorkerReporting;
+    private flushServiceWorkerReport;
+    private reportServiceWorkerStats;
+    private startDirectFilePlayback;
+    private startDirectFileCdnFallback;
+    private recordServiceWorkerSegmentStats;
+    private startServiceWorkerFallback;
+    private createServiceWorkerP2pEngine;
+    private resolveServiceWorkerSwarmId;
+    private startCdnFallback;
+    private attachHls;
+    private autoplay;
+    private canPlayNativeHls;
+    private effectiveP2pEnabled;
+}

package/dist/public-capabilities.d.ts

@@ -0,0 +1,11 @@
+/** Browser capabilities exposed to customer code before starting playback. */
+export interface MeshStreamCapability {
+    mseSupported: boolean;
+    webrtcSupported: boolean;
+    serviceWorkerSupported: boolean;
+}
+/**
+ * Returns the browser capabilities that affect MeshStream Web transport choice.
+ * This is informational only; attach().start() still owns the final fallback decision.
+ */
+export declare function getCapability(): MeshStreamCapability;

package/dist/qoe.d.ts

@@ -0,0 +1,25 @@
+import type { P2pDiagnostics, P2pStats } from "./report.js";
+/** Stable customer-facing lifecycle for a single playback session. */
+export type MeshStreamPlaybackState = "idle" | "initializing" | "connecting" | "p2p-ready" | "cdn-fallback" | "disposed";
+/**
+ * Compact playback-health snapshot. It intentionally excludes Tracker, ICE,
+ * and peer identifiers so it is safe to send to application telemetry.
+ */
+export interface MeshStreamQoeSnapshot {
+    state: MeshStreamPlaybackState;
+    downloadedBytes: number;
+    p2pDownloadedBytes: number;
+    cdnDownloadedBytes: number;
+    /** `0..1`; zero when no media bytes have been downloaded yet. */
+    p2pDownloadRatio: number;
+    connectedPeers: number;
+    firstPeerConnectMs?: number;
+    fallbackCount: number;
+    coldStartCdnBytes?: number;
+    /** Present for live HLS after the first parsed media playlist. */
+    liveLatencyMs?: number;
+    liveTargetLatencyMs?: number;
+    liveMaxLatencyMs?: number;
+    liveLatencyOverMax?: boolean;
+}
+export declare function buildMeshStreamQoe(state: MeshStreamPlaybackState, stats: P2pStats, diagnostics: Partial<P2pDiagnostics>): MeshStreamQoeSnapshot;

package/dist/report.d.ts

@@ -0,0 +1,140 @@
+import type { WebP2pCapabilityResult } from "./capabilities.js";
+import type { PlaybackAuthDiagnostics } from "./playback-auth.js";
+export interface P2pStats {
+    httpDownloaded: number;
+    p2pDownloaded: number;
+    p2pUploaded: number;
+    httpSegmentDownloadSuccesses: number;
+    httpSegmentDownloadFailures: number;
+    p2pSegmentDownloadSuccesses: number;
+    p2pSegmentDownloadFailures: number;
+    p2pSegmentUploadSuccesses: number;
+    p2pSegmentUploadFailures: number;
+    connectedPeers: number;
+    peerConnectErrors: number;
+    trackerErrors: number;
+    p2pAttempts?: number;
+    httpAttempts?: number;
+    p2pErrors?: number;
+    httpErrors?: number;
+    lastLoadedBytes?: number;
+}
+/**
+ * Returns the stable customer-facing statistics shape. Playback on CDN has
+ * valid zero P2P counters, so dashboards do not need adapter-specific null
+ * handling while a session is starting or falling back.
+ */
+export declare function normalizeP2pStats(stats: Partial<P2pStats> | undefined): P2pStats;
+export interface P2pDiagnostics {
+    firstPeerConnectMs?: number;
+    /** Bytes received before the first usable P2P peer is connected. */
+    coldStart?: {
+        p2pDownloaded: number;
+        httpDownloaded: number;
+    };
+    /**
+     * HLS live-edge observations accumulated by the SDK. The three duration
+     * fields are sums in milliseconds; the `last*` values are a current local
+     * snapshot for `qoe()` and are not used for aggregation.
+     */
+    liveLatency?: {
+        samples: number;
+        latencyDurationMs: number;
+        targetLatencyDurationMs: number;
+        maxLatencyDurationMs: number;
+        overMaxLatencySamples: number;
+        lastLatencyMs?: number;
+        lastTargetLatencyMs?: number;
+        lastMaxLatencyMs?: number;
+    };
+    /** Live-only deterministic cohort used to retain an extra uploadable fragment. */
+    liveSeed?: {
+        cohort: boolean;
+        active: boolean;
+    };
+    fallbackCount: number;
+    lastTrackerError?: string;
+    lastPeerError?: string;
+    lastErrorAtMs?: number;
+    playbackAuth?: PlaybackAuthDiagnostics;
+    ice?: {
+        attempts: number;
+        successes: number;
+        failures: number;
+        durationMs: number;
+    };
+    auth?: P2pConnectionMetric;
+    websocket?: P2pConnectionMetric;
+}
+/**
+ * Captures diagnostics before asynchronous authorization or transport work.
+ * A client may be disposed while its final report is waiting for a token.
+ */
+export declare function snapshotP2pDiagnostics(diagnostics: P2pDiagnostics, auth?: P2pConnectionMetric): P2pDiagnostics;
+/** Cumulative request/connection metric collected for this playback session. */
+export interface P2pConnectionMetric {
+    attempts: number;
+    successes: number;
+    failures: number;
+    /** Present only when the integration can measure each attempt boundary. */
+    durationMs: number;
+}
+export interface P2pReportLoad {
+    uploadSlots: number;
+    activeUploadPeers: number;
+    downloadSlots: number;
+    activeDownloadPeers: number;
+}
+export interface P2pReportInput {
+    platform: string;
+    /** Explicit playback class supplied by the integrator; never inferred from a URL. */
+    playbackMode: "live" | "vod";
+    /** Actual client delivery runtime, independent from the requested preference. */
+    runtimeMode?: "mse" | "service-worker" | "cdn" | "unknown";
+    protocol?: "hls" | "dash" | "mp4" | "mp3";
+    playerType?: "hlsjs" | "shaka" | "dashjs" | "native" | string;
+    appId?: string;
+    keyId?: string;
+    sdkVersion: string;
+    sessionId: string;
+    contentId?: string;
+    swarmId: string;
+    playbackUrl: string;
+    stats: P2pStats;
+    load: P2pReportLoad;
+    diagnostics: P2pDiagnostics;
+    capability?: WebP2pCapabilityResult;
+}
+/** A usage snapshot, not a transport keepalive or peer heartbeat. */
+export interface P2pReportPayload {
+    reportType: "stats";
+    reportId: string;
+    reportSeq: number;
+    /** Client wall-clock timestamp fixed for this cumulative report snapshot. */
+    reportedAtMs: number;
+    platform: string;
+    playbackMode: "live" | "vod";
+    runtimeMode?: P2pReportInput["runtimeMode"];
+    appId?: string;
+    keyId?: string;
+    sessionId: string;
+    stats: P2pStats;
+    load: Partial<P2pReportLoad>;
+    diagnostics: P2pDiagnostics;
+    protocol?: P2pReportInput["protocol"];
+    playerType?: string;
+    sdkVersion?: string;
+    contentId?: string;
+    swarmId?: string;
+    playbackUrl?: string;
+    capability?: WebP2pCapabilityResult;
+}
+export declare const DEFAULT_REPORT_INTERVAL_MS = 30000;
+export declare const MIN_REPORT_INTERVAL_MS = 20000;
+export declare function normalizeReportIntervalMs(value: number | undefined): number;
+export interface PostP2pReportOptions {
+    fetcher?: typeof fetch;
+    authorizationHeader?: string;
+}
+export declare function buildP2pReportPayload(input: P2pReportInput, includeContext?: boolean): P2pReportPayload;
+export declare function postP2pReport(reportUrl: string | undefined, payload: P2pReportPayload, options?: PostP2pReportOptions): Promise<Response | undefined>;

package/dist/rx-player.d.ts

@@ -0,0 +1,163 @@
+import { type WebP2pCapabilityResult } from "./capabilities.js";
+import { type LoadSdkConfigOptions, type SdkConfigRequest, type SdkConfigResponse } from "./config.js";
+import { type P2pEventListener } from "./hls.js";
+import { type OriginHeaders, type OriginHeadersProvider } from "./origin-headers.js";
+import { type MeshStreamP2pFallbackReason } from "./player.js";
+import { type P2pDiagnostics, type P2pStats } from "./report.js";
+import { type MeshStreamQoeSnapshot } from "./qoe.js";
+import { WebSessionTokenManager } from "./session-token.js";
+import { reportWebP2pFallback } from "./fallback.js";
+export type MeshStreamRxPlayerPlaybackMode = "p2p-rxplayer" | "cdn-rxplayer";
+export interface RxPlayerSegmentLoaderContext {
+    url?: string;
+    timeout?: number;
+    isInit?: boolean;
+    byteRanges?: Array<[number, number]>;
+    trackType: "video" | "audio" | "text";
+}
+export interface RxPlayerSegmentLoaderCallbacks {
+    resolve(result: {
+        data: ArrayBuffer | Uint8Array;
+        sendingTime?: number;
+        receivingTime?: number;
+        size?: number;
+        duration?: number;
+    }): void;
+    reject(error?: unknown): void;
+    /** Use RxPlayer's built-in CDN loader for this request. */
+    fallback(): void;
+    progress(info: {
+        duration: number;
+        size: number;
+        totalSize?: number;
+    }): void;
+}
+export type RxPlayerSegmentLoader = (context: RxPlayerSegmentLoaderContext, callbacks: RxPlayerSegmentLoaderCallbacks) => (() => void) | void;
+export interface RxPlayerManifestLoaderContext {
+    url?: string;
+    timeout?: number;
+}
+export interface RxPlayerManifestLoaderCallbacks {
+    resolve(result: {
+        data: ArrayBuffer | string;
+        url?: string;
+        sendingTime?: number;
+        receivingTime?: number;
+        size?: number;
+        duration?: number;
+    }): void;
+    reject(error?: Error): void;
+    /** Use RxPlayer's built-in CDN loader for this request. */
+    fallback(): void;
+}
+export type RxPlayerManifestLoader = (context: RxPlayerManifestLoaderContext, callbacks: RxPlayerManifestLoaderCallbacks) => (() => void) | void;
+export interface RxPlayerLoadVideoOptions {
+    transport: "dash";
+    url: string;
+    autoPlay?: boolean;
+    /** Low-latency chunk streaming bypasses RxPlayer's custom segment loader. */
+    lowLatencyMode?: false;
+    manifestLoader?: RxPlayerManifestLoader;
+    segmentLoader?: RxPlayerSegmentLoader;
+}
+/** Structural subset of RxPlayer's public player API. No RxPlayer runtime dependency is imposed on the SDK. */
+export interface RxPlayerLike {
+    getVideoElement?: () => HTMLMediaElement | null;
+    loadVideo: (options: RxPlayerLoadVideoOptions) => void;
+    stop?: () => void;
+}
+export interface MeshStreamRxPlayerOptions {
+    key: string;
+    url: string;
+    player: RxPlayerLike;
+    contentId?: string;
+    originHeaders?: OriginHeaders;
+    /** Resolves dynamic headers immediately before a same-origin CDN request. */
+    originHeadersProvider?: OriginHeadersProvider;
+    bootstrapUrl?: string;
+    autoplay?: boolean;
+    p2pEnabled?: boolean;
+    iceServers?: RTCIceServer[];
+    dependencies?: MeshStreamRxPlayerDependencies;
+}
+export interface MeshStreamRxPlayerStartResult {
+    mode: MeshStreamRxPlayerPlaybackMode;
+    capability: WebP2pCapabilityResult;
+    sdkConfig?: SdkConfigResponse;
+    fallbackReason?: MeshStreamP2pFallbackReason;
+}
+export interface MeshStreamRxPlayerDependencies {
+    loadSdkConfig?: (request: SdkConfigRequest, options?: LoadSdkConfigOptions) => Promise<SdkConfigResponse | undefined>;
+    detectCapability?: () => WebP2pCapabilityResult;
+    createP2pClient?: (config: RxP2pClientConfig) => RxP2pClientLike | Promise<RxP2pClientLike>;
+    reportFallback?: typeof reportWebP2pFallback;
+}
+export interface RxP2pClientLike {
+    swarmId: string;
+    createSegmentLoader(originFallbackLoader?: RxPlayerSegmentLoader): RxPlayerSegmentLoader;
+    addEventListener(listener: P2pEventListener): void;
+    removeEventListener(listener: P2pEventListener): void;
+    statistics(): Partial<P2pStats>;
+    diagnostics(): Partial<P2pDiagnostics>;
+    /** Internal manifest callback. Customer integrations do not call this. */
+    setLiveMode?(isLive: boolean): void;
+    setP2pEnabled(enabled: boolean): void;
+    dispose(): void;
+}
+export interface RxP2pClientConfig {
+    streamUrl: string;
+    contentId?: string;
+    sdkConfig: Pick<SdkConfigResponse, "applicationId" | "keyId" | "reportUrl" | "trackerUrls" | "primaryTrackerUrl" | "iceServers" | "playbackAuth" | "defaults">;
+    appId?: string;
+    sessionId: string;
+    trackerUrls: string[];
+    iceServers?: RTCIceServer[];
+    p2pEnabled?: boolean;
+    originHeaders?: OriginHeaders;
+    originHeadersProvider?: OriginHeadersProvider;
+    capability?: WebP2pCapabilityResult;
+    sessionTokenManager?: WebSessionTokenManager;
+}
+/**
+ * Attach MeshStream P2P loading to an existing RxPlayer instance.
+ *
+ * RxPlayer provides a real segment-loader interception point for DASH. We use
+ * that point instead of running a second player on the same video element.
+ */
+export declare function attachToRxPlayer(options: MeshStreamRxPlayerOptions): MeshStreamRxPlayer;
+export declare class MeshStreamRxPlayer {
+    readonly key: string;
+    readonly url: string;
+    readonly player: RxPlayerLike;
+    private readonly options;
+    private p2p?;
+    private sessionTokenManager?;
+    private mode;
+    private p2pEnabledOverride?;
+    private readonly eventListeners;
+    private playbackState;
+    private readonly lifecycle;
+    private startPromise?;
+    private startResult?;
+    constructor(options: MeshStreamRxPlayerOptions);
+    get p2pClient(): RxP2pClientLike | undefined;
+    get playbackMode(): MeshStreamRxPlayerPlaybackMode;
+    start(): Promise<MeshStreamRxPlayerStartResult>;
+    private startInternal;
+    statistics(): P2pStats;
+    diagnostics(): Partial<P2pDiagnostics>;
+    qoe(): MeshStreamQoeSnapshot;
+    setP2pEnabled(enabled: boolean): void;
+    addEventListener(listener: P2pEventListener): () => void;
+    dispose(): void;
+    private teardown;
+    private startCdn;
+    private effectiveP2pEnabled;
+    private createOriginManifestLoader;
+    private createOriginSegmentLoader;
+    private completeFallbackStart;
+    private bindEventListeners;
+    private removeEventListener;
+    private setPlaybackState;
+    private resolveQoePlaybackState;
+}

package/dist/segment-storage.d.ts

@@ -0,0 +1,31 @@
+import type { CommonCoreConfig, StreamConfig, StreamType } from "p2p-media-loader-core";
+type StorageUsage = {
+    totalCapacity: number;
+    usedCapacity: number;
+};
+export declare class MeshStreamSegmentStorage {
+    private limitBytes;
+    private usedBytes;
+    private mainLiveRetentionSeconds;
+    private secondaryLiveRetentionSeconds;
+    private playbackPosition;
+    private readonly cache;
+    private segmentChangeCallback;
+    initialize(coreConfig: Pick<CommonCoreConfig, "segmentMemoryStorageLimit">, mainStreamConfig: Pick<StreamConfig, "highDemandTimeWindow">, secondaryStreamConfig: Pick<StreamConfig, "highDemandTimeWindow">): Promise<void>;
+    onPlaybackUpdated(position: number, _rate: number): void;
+    onSegmentRequested(_swarmId: string, _streamId: string, _segmentId: number, _startTime: number, _endTime: number, _streamType: StreamType, _isLiveStream: boolean): void;
+    storeSegment(_swarmId: string, streamId: string, segmentId: number, data: ArrayBuffer, _startTime: number, endTime: number, streamType: StreamType, isLiveStream: boolean): Promise<void>;
+    getSegmentData(_swarmId: string, streamId: string, segmentId: number): Promise<ArrayBuffer | undefined>;
+    getUsage(): StorageUsage;
+    hasSegment(_swarmId: string, streamId: string, segmentId: number): boolean;
+    getStoredSegmentIds(_swarmId: string, streamId: string): number[];
+    setSegmentChangeCallback(callback: ((streamId: string) => void) | undefined): void;
+    destroy(): void;
+    private trimToLimit;
+    private trimExpiredLiveSegments;
+    private liveRetentionSeconds;
+    private notifyChanged;
+    private publishDebugSnapshot;
+}
+export declare function createMeshStreamSegmentStorage(_isLive?: boolean): MeshStreamSegmentStorage;
+export {};