@meshstream/p2p-web 1.0.0 → 1.0.1

package/README.md

@@ -1,501 +1,501 @@
-# MeshStream P2P Web SDK
-
-SDK-owned console diagnostics respect the client `logLevel` (default `none`), with redaction and
-repeated-error limiting. Web does not write local log files. See the [logging guide](../../docs/sdk-logging.md).
-
-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
-```
-
-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.
+# MeshStream P2P Web SDK
+
+SDK-owned console diagnostics respect the client `logLevel` (default `none`), with redaction and
+repeated-error limiting. Web does not write local log files. See the [logging guide](../../docs/sdk-logging.md).
+
+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
+```
+
+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.