@meshstream/p2p-web 0.0.0-stage → 0.2.1

package/dist/service-worker-p2p.d.ts

@@ -0,0 +1,166 @@
+import type { SdkConfigResponse } from "./config.js";
+import type { P2pEventListener } from "./hls.js";
+import { type OriginHeaders, type OriginHeadersProvider } from "./origin-headers.js";
+import type { P2pConnectionMetric, P2pStats } from "./report.js";
+import type { MeshStreamSwSegmentProvider } from "./service-worker.js";
+export interface MeshStreamServiceWorkerP2pEngineOptions {
+    manifestUrl: string;
+    /** `direct-file` enables bounded Range-based P2P for progressive media. */
+    resourceKind?: "hls" | "direct-file";
+    swarmId: string;
+    trackerUrl: string;
+    trackerUrls?: string[];
+    originHeaders?: OriginHeaders;
+    originHeadersProvider?: OriginHeadersProvider;
+    iceServers?: RTCIceServer[];
+    sdkConfig?: Pick<SdkConfigResponse, "iceServers">;
+    requestTimeoutMs?: number;
+}
+export interface MeshStreamServiceWorkerP2pDiagnostics {
+    /** Whether the page-side engine is currently accepting P2P requests. */
+    p2pEnabled: boolean;
+    /** Whether direct-file metadata has been indexed for Range requests. */
+    directFileReady: boolean;
+    connectedPeers: number;
+    /** Info hashes of currently connected stream swarms, for transport diagnostics. */
+    peerInfoHashes: string[];
+    trackerErrors: number;
+    lastTrackerError?: string;
+    peerConnectErrors: number;
+    /** Time from engine creation until the first usable P2P peer. */
+    firstPeerConnectMs?: number;
+    /** CDN segment completions observed while no P2P peer was connected. */
+    fallbackCount: number;
+    lastPeerError?: string;
+    lastErrorAtMs?: number;
+    /** Cumulative terminal ICE outcomes emitted by p2p-media-loader Core. */
+    ice: P2pConnectionMetric;
+    /** Number of announcements received from connected peers. */
+    peerSegmentAnnouncements: number;
+    /** Loaded segment count reported by the latest peer announcement. */
+    peerAnnouncedSegments: number;
+    /** HTTP-loading segment count reported by the latest peer announcement. */
+    peerHttpLoadingSegments: number;
+    p2pAttempts: number;
+    httpAttempts: number;
+    p2pErrors: number;
+    httpErrors: number;
+    p2pUploaded: number;
+    p2pSegmentUploadSuccesses: number;
+    p2pSegmentUploadFailures: number;
+    lastLoadedBytes: number;
+    segmentRequests: number;
+    runtimeIdMisses: number;
+    segmentLoadSuccesses: number;
+    segmentLoadTimeouts: number;
+    indexedSegments: number;
+}
+/**
+ * Page-side P2P engine used by the Service Worker bridge. It deliberately uses
+ * p2p-media-loader-core directly, so native-HLS playback does not require MSE.
+ */
+export declare class MeshStreamServiceWorkerP2pEngine {
+    /** Actual Tracker swarm, including its configured hot-content bucket. */
+    readonly swarmId: string;
+    private core;
+    private readonly trackerCandidates;
+    private readonly createCore;
+    private readonly streamIdFactory;
+    private readonly manifestUrl;
+    private readonly resourceKind;
+    private readonly requestTimeoutMs;
+    /** HLS playlists update this after each parse; progressive media is known VOD. */
+    private playbackIsLive;
+    private readonly manifestRequestSetup;
+    private readonly originHeaders;
+    private readonly originHeadersProvider;
+    private readonly streams;
+    private readonly segmentIdsByRequestKey;
+    private readonly playbackPositionsByRuntimeId;
+    private readonly completedSources;
+    private readonly eventListeners;
+    private readonly startedAtMs;
+    private eventTimer;
+    private p2pReady;
+    private readonly stats;
+    private readonly pendingSegmentLoads;
+    private readonly directChunks;
+    private directFile;
+    private disposed;
+    private peerCount;
+    private readonly peerInfoHashes;
+    private trackerErrors;
+    private lastTrackerError;
+    private peerConnectErrors;
+    private firstPeerConnectMs;
+    private fallbackCount;
+    private lastPeerError;
+    private lastErrorAtMs;
+    private readonly ice;
+    private peerSegmentAnnouncements;
+    private peerAnnouncedSegments;
+    private peerHttpLoadingSegments;
+    private p2pAttempts;
+    private httpAttempts;
+    private p2pErrors;
+    private httpErrors;
+    private p2pUploaded;
+    private p2pSegmentUploadSuccesses;
+    private p2pSegmentUploadFailures;
+    private lastLoadedBytes;
+    private segmentRequests;
+    private runtimeIdMisses;
+    private segmentLoadSuccesses;
+    private segmentLoadTimeouts;
+    private indexedSegments;
+    private activeTrackerIndex;
+    private failoverInFlight;
+    private coreReady;
+    private coreGeneration;
+    private coreRebuildInFlight;
+    private coreRebuildGeneration;
+    private lastCoreRebuildAttemptAtMs;
+    private p2pEnabled;
+    /** Core has a single foreground engine request, so direct-file ranges queue here. */
+    private directFileLoadQueue;
+    /** Reset Core just before its first request so its P2P bootstrap window is usable. */
+    private hasIssuedCoreLoad;
+    private constructor();
+    private bindCoreEvents;
+    static create(options: MeshStreamServiceWorkerP2pEngineOptions): Promise<MeshStreamServiceWorkerP2pEngine>;
+    private failoverTracker;
+    private rebuildCoreState;
+    private scheduleCoreRebuild;
+    private ensureCoreState;
+    initialize(): Promise<void>;
+    createSegmentProvider(): MeshStreamSwSegmentProvider;
+    addEventListener(listener: P2pEventListener): void;
+    removeEventListener(listener: P2pEventListener): void;
+    /** Stops or recreates the Core while leaving the virtual media URL on CDN. */
+    setP2pEnabled(enabled: boolean): void;
+    diagnostics(): MeshStreamServiceWorkerP2pDiagnostics;
+    statistics(): P2pStats;
+    isLive(): boolean;
+    isPlaybackModeKnown(): boolean;
+    dispose(): void;
+    private notifyUnavailable;
+    private notify;
+    private notifyPlaybackState;
+    private elapsedSinceStartMs;
+    private provideSegment;
+    private loadSegmentResponse;
+    private initializeDirectFile;
+    private fetchDirectFileMetadata;
+    private createDirectFileMetadataRequest;
+    private rebuildDirectFileStream;
+    private loadDirectFileRange;
+    private isLargeDirectFileRange;
+    private streamDirectFileRange;
+    private loadDirectFileChunk;
+    private enqueueDirectFileLoad;
+    private resetInitialCoreRequestWindow;
+    private ensureDirectFileChunk;
+    private loadSegmentFromCore;
+    private refreshPlaylists;
+    private indexPlaylist;
+}

package/dist/service-worker.d.ts

@@ -0,0 +1,113 @@
+import type { OriginHeadersProvider } from "./origin-headers.js";
+export declare const MESHSTREAM_SW_PROTOCOL_VERSION = 1;
+export declare const MESHSTREAM_SW_PATH_PREFIX = "/__meshstream__/v1/";
+export type MeshStreamServiceWorkerMessage = {
+    type: "MESHSTREAM_SW_PING";
+    protocolVersion: number;
+} | {
+    type: "MESHSTREAM_SW_REGISTER_SESSION";
+    protocolVersion: number;
+    sessionId: string;
+    manifestUrl: string;
+    resourceKind?: "hls" | "direct-file";
+    originHeaders?: Record<string, string>;
+    p2pTimeoutMs: number;
+} | {
+    type: "MESHSTREAM_SW_UNREGISTER_SESSION";
+    protocolVersion: number;
+    sessionId: string;
+};
+export interface MeshStreamServiceWorkerRegistrationOptions {
+    url?: string;
+    scope?: string;
+    registration?: ServiceWorkerRegistration;
+    readyTimeoutMs?: number;
+}
+export interface MeshStreamServiceWorkerSessionOptions {
+    serviceWorker?: MeshStreamServiceWorkerClient;
+    sessionId?: string;
+    manifestUrl: string;
+    /** `direct-file` proxies one progressive media resource without playlist rewriting. */
+    resourceKind?: "hls" | "direct-file";
+    originHeaders?: Record<string, string>;
+    originHeadersProvider?: OriginHeadersProvider;
+    p2pTimeoutMs?: number;
+    segmentProvider?: MeshStreamSwSegmentProvider;
+    onSegmentStats?: (stats: MeshStreamSwSegmentStats) => void;
+}
+export interface MeshStreamSwSegmentRequest {
+    sessionId: string;
+    resourceId: string;
+    url: string;
+    headers: Headers;
+}
+export interface MeshStreamSwSegmentResponse {
+    /** A bounded response body. Exactly one of `body` or `stream` is required. */
+    body?: ArrayBuffer;
+    /** A backpressure-aware response for large progressive-media byte ranges. */
+    stream?: ReadableStream<Uint8Array>;
+    /** Total response bytes. Required when `stream` is used. */
+    bytes?: number;
+    status?: number;
+    statusText?: string;
+    headers?: Record<string, string>;
+    source?: "p2p" | "cdn";
+    /** Exact byte attribution for a response assembled from multiple chunks. */
+    p2pBytes?: number;
+    /** Exact byte attribution for a response assembled from multiple chunks. */
+    cdnBytes?: number;
+    /** Mutable counters used while a progressive-media stream is consumed. */
+    transferStats?: MeshStreamSwSegmentTransferStats;
+}
+export interface MeshStreamSwSegmentTransferStats {
+    p2pBytes: number;
+    cdnBytes: number;
+}
+export interface MeshStreamSwSegmentStats {
+    sessionId: string;
+    resourceId: string;
+    url: string;
+    source: "p2p" | "cdn";
+    bytes: number;
+    status: number;
+    p2pBytes?: number;
+    cdnBytes?: number;
+}
+export type MeshStreamSwSegmentProvider = (request: MeshStreamSwSegmentRequest) => Promise<MeshStreamSwSegmentResponse | undefined>;
+export interface MeshStreamServiceWorkerSession {
+    readonly sessionId: string;
+    readonly manifestUrl: string;
+    dispose(): Promise<void>;
+}
+export declare class MeshStreamServiceWorkerClient {
+    readonly registration: ServiceWorkerRegistration;
+    private readonly messageListener;
+    private readonly segmentProviders;
+    private readonly originHeadersProviders;
+    private readonly statsListeners;
+    private readonly sessionBridgePorts;
+    private bridgeRequests;
+    private bridgeUnavailableResponses;
+    constructor(registration: ServiceWorkerRegistration);
+    registerSession(options: {
+        sessionId: string;
+        manifestUrl: string;
+        resourceKind?: "hls" | "direct-file";
+        originHeaders?: Record<string, string>;
+        originHeadersProvider?: OriginHeadersProvider;
+        p2pTimeoutMs?: number;
+        segmentProvider?: MeshStreamSwSegmentProvider;
+        onSegmentStats?: (stats: MeshStreamSwSegmentStats) => void;
+    }): Promise<MeshStreamServiceWorkerSession>;
+    dispose(): void;
+    diagnostics(): {
+        serviceWorkerBridgeRequests: number;
+        serviceWorkerBridgeUnavailableResponses: number;
+    };
+    private removeSession;
+    private closeSessionBridge;
+}
+export declare function isMeshStreamServiceWorkerSupported(): boolean;
+export declare function registerMeshStreamServiceWorker(options?: MeshStreamServiceWorkerRegistrationOptions): Promise<MeshStreamServiceWorkerClient>;
+export declare function createMeshStreamServiceWorkerSession(options: MeshStreamServiceWorkerSessionOptions): Promise<MeshStreamServiceWorkerSession | undefined>;
+export declare function buildMeshStreamServiceWorkerUrl(sessionId: string, resourceId: string): string;

package/dist/service-worker.js

@@ -0,0 +1 @@
+var e=1,s="/__meshstream__/v1/",t=new Map,r=class{registration;messageListener;segmentProviders=new Map;originHeadersProviders=new Map;statsListeners=new Map;sessionBridgePorts=new Map;bridgeRequests=0;bridgeUnavailableResponses=0;constructor(e){this.registration=e,this.messageListener=e=>{const s=e.data;if("MESHSTREAM_SW_SEGMENT_RESULT"===s?.type&&s.sessionId){const e=this.statsListeners.get(s.sessionId);if(!e)return;const t={sessionId:s.sessionId,resourceId:s.resourceId??"",url:s.url??"",source:"p2p"===s.source?"p2p":"cdn",bytes:Number.isFinite(s.bytes)?Math.max(0,s.bytes):0,status:Number.isFinite(s.status)?s.status:200,p2pBytes:Number.isFinite(s.p2pBytes)?Math.max(0,s.p2pBytes):void 0,cdnBytes:Number.isFinite(s.cdnBytes)?Math.max(0,s.cdnBytes):void 0};try{e(t)}catch{}return}const r=e.ports?.[0];if("MESHSTREAM_SW_ORIGIN_HEADERS_REQUEST"===s?.type&&s.sessionId&&r){let e;try{e=this.originHeadersProviders.get(s.sessionId)?.({url:s.url??"",kind:(i=s.kind,"manifest"===i||"segment"===i||"key"===i||"direct-file"===i||"unknown"===i?s.kind:"unknown")})}catch{}return void r.postMessage({type:"MESHSTREAM_SW_ORIGIN_HEADERS_RESPONSE",headers:e??{}})}var i;if("MESHSTREAM_SW_SEGMENT_REQUEST"!==s?.type||!s.sessionId||!r)return;this.bridgeRequests+=1;const o=this.segmentProviders.get(s.sessionId);if(!o)return a=s.sessionId,void((t.get(a)??0)>0||(this.bridgeUnavailableResponses+=1,r.postMessage({type:"MESHSTREAM_SW_SEGMENT_UNAVAILABLE"})));var a;o({sessionId:s.sessionId,resourceId:s.resourceId??"",url:s.url??"",headers:new Headers(s.headers??{})}).then(e=>{if(!e)return this.bridgeUnavailableResponses+=1,void r.postMessage({type:"MESHSTREAM_SW_SEGMENT_UNAVAILABLE"});e.stream?function(e,s){const t=s.stream;if(!t||!Number.isFinite(s.bytes)||(s.bytes??0)<0)return void e.postMessage({type:"MESHSTREAM_SW_SEGMENT_UNAVAILABLE"});const r=t.getReader();let i=!1;const o=(t=!1,o=!1)=>{if(i)return;i=!0,t&&r.cancel().catch(()=>{});const a=s.transferStats?.p2pBytes??s.p2pBytes,c=s.transferStats?.cdnBytes??s.cdnBytes,d=(a??0)+(c??0);e.postMessage({type:o?"MESHSTREAM_SW_SEGMENT_STREAM_ERROR":"MESHSTREAM_SW_SEGMENT_STREAM_COMPLETE",source:n(a,c,s.source),bytes:d>0?d:s.bytes,p2pBytes:a,cdnBytes:c});try{e.close()}catch{}};e.onmessage=async s=>{const t=s.data;if("MESHSTREAM_SW_SEGMENT_STREAM_CANCEL"!==t?.type){if("MESHSTREAM_SW_SEGMENT_STREAM_PULL"===t?.type&&!i)try{const s=await r.read();if(s.done)return void o();const t=function(e){const s=new ArrayBuffer(e.byteLength);return new Uint8Array(s).set(e),s}(s.value);e.postMessage({type:"MESHSTREAM_SW_SEGMENT_STREAM_CHUNK",body:t},[t])}catch{o(!0,!0)}}else o(!0)},e.postMessage({type:"MESHSTREAM_SW_SEGMENT_STREAM_START",status:s.status,statusText:s.statusText,headers:s.headers,source:s.source,bytes:s.bytes})}(r,e):e.body?r.postMessage({type:"MESHSTREAM_SW_SEGMENT_RESPONSE",status:e.status,statusText:e.statusText,headers:e.headers,source:e.source,bytes:e.bytes??e.body.byteLength,p2pBytes:e.p2pBytes,cdnBytes:e.cdnBytes,body:e.body},[e.body]):r.postMessage({type:"MESHSTREAM_SW_SEGMENT_UNAVAILABLE"})}).catch(()=>{this.bridgeUnavailableResponses+=1,r.postMessage({type:"MESHSTREAM_SW_SEGMENT_UNAVAILABLE"})})},navigator.serviceWorker.addEventListener("message",this.messageListener)}async registerSession(e){const s=e.sessionId,r=this.segmentProviders.has(s);this.segmentProviders.set(s,e.segmentProvider??(async()=>{})),e.originHeadersProvider?this.originHeadersProviders.set(s,e.originHeadersProvider):this.originHeadersProviders.delete(s),r||function(e){t.set(e,(t.get(e)??0)+1)}(s),e.onSegmentStats&&this.statsListeners.set(s,e.onSegmentStats);const o=new MessageChannel;o.port1.onmessage=this.messageListener,o.port1.start?.(),this.closeSessionBridge(s),this.sessionBridgePorts.set(s,o.port1);try{await g(this.registration,{type:"MESHSTREAM_SW_REGISTER_SESSION",protocolVersion:1,sessionId:s,manifestUrl:e.manifestUrl,resourceKind:e.resourceKind,originHeaders:e.originHeaders,p2pTimeoutMs:(n=e.p2pTimeoutMs,Number.isFinite(n)?Math.max(100,Math.floor(n)):5e3)},[o.port2])}catch(e){throw this.closeSessionBridge(s),r||i(s),this.segmentProviders.delete(s),this.originHeadersProviders.delete(s),this.statsListeners.delete(s),e}var n;const a=S(s,"manifest");let c=!1;return{sessionId:s,manifestUrl:a,dispose:async()=>{c||(c=!0,this.removeSession(s),this.statsListeners.delete(s),await g(this.registration,{type:"MESHSTREAM_SW_UNREGISTER_SESSION",protocolVersion:1,sessionId:s}))}}}dispose(){navigator.serviceWorker.removeEventListener("message",this.messageListener);for(const e of this.segmentProviders.keys())i(e);this.segmentProviders.clear(),this.originHeadersProviders.clear(),this.statsListeners.clear();for(const e of this.sessionBridgePorts.values())o(e);this.sessionBridgePorts.clear()}diagnostics(){return{serviceWorkerBridgeRequests:this.bridgeRequests,serviceWorkerBridgeUnavailableResponses:this.bridgeUnavailableResponses}}removeSession(e){this.closeSessionBridge(e),this.segmentProviders.delete(e)&&(this.originHeadersProviders.delete(e),i(e))}closeSessionBridge(e){const s=this.sessionBridgePorts.get(e);s&&(this.sessionBridgePorts.delete(e),o(s))}};function i(e){const s=t.get(e)??0;s<=1?t.delete(e):t.set(e,s-1)}function o(e){try{e.close()}catch{}}function n(e,s,t){return(e??0)>0&&0===(s??0)||"p2p"===t?"p2p":"cdn"}function a(){return"undefined"!=typeof navigator&&"serviceWorker"in navigator&&!("undefined"!=typeof isSecureContext&&!isSecureContext)}async function c(e={}){if(!a())throw new Error("MeshStream Service Worker requires a secure context and navigator.serviceWorker");const s=e.registration??await navigator.serviceWorker.register(e.url??"/meshstream-sw.js",e.scope?{scope:e.scope}:void 0),t=e.readyTimeoutMs??1e4,i=await async function(e){return function(e,s){return new Promise((t,r)=>{const i=setTimeout(()=>r(new Error("Service Worker activation timed out")),s);e.then(e=>{clearTimeout(i),t(e)},e=>{clearTimeout(i),r(e)})})}(navigator.serviceWorker.ready,e)}(t);return await async function(e,s){!navigator.serviceWorker.controller&&s.active&&await new Promise((s,t)=>{const r=setTimeout(()=>{navigator.serviceWorker.removeEventListener("controllerchange",i),t(new Error("MeshStream Service Worker controller claim timed out"))},e),i=()=>{clearTimeout(r),navigator.serviceWorker.removeEventListener("controllerchange",i),s()};navigator.serviceWorker.addEventListener("controllerchange",i,{once:!0}),navigator.serviceWorker.controller&&i()})}(t,i),await E(s,t),new r(s)}async function d(e){const s=!e.serviceWorker,t=e.serviceWorker??await async function(){if(!a()||!navigator.serviceWorker.controller)return;const e=await navigator.serviceWorker.ready;try{return await E(e,750),new r(e)}catch{return}}();if(!t)return;const i=await t.registerSession({sessionId:e.sessionId??(o="sw",`${o}-${globalThis.crypto?.randomUUID?.()??Math.random().toString(36).slice(2)}`),manifestUrl:e.manifestUrl,resourceKind:e.resourceKind,originHeaders:e.originHeaders,originHeadersProvider:e.originHeadersProvider,p2pTimeoutMs:e.p2pTimeoutMs,segmentProvider:e.segmentProvider,onSegmentStats:e.onSegmentStats});var o;if(!s)return i;const n=i.dispose;return{sessionId:i.sessionId,manifestUrl:i.manifestUrl,dispose:async()=>{try{await n()}finally{t.dispose()}}}}function S(e,t){return"undefined"==typeof location?`${s}${encodeURIComponent(e)}/${t}`:new URL(`${s}${encodeURIComponent(e)}/${t}`,location.origin).toString()}async function E(e,s){const t=navigator.serviceWorker.controller??e.active??e.waiting??e.installing;if(!t)throw new Error("MeshStream Service Worker has no active worker");await new Promise((e,r)=>{const i=new MessageChannel,o=()=>{try{i.port1.close()}catch{}},n=setTimeout(()=>{o(),r(new Error("MeshStream Service Worker handshake timed out"))},s);i.port1.onmessage=s=>{clearTimeout(n),o(),"MESHSTREAM_SW_READY"===s.data?.type?e():r(new Error("Invalid MeshStream Service Worker handshake"))},t.postMessage({type:"MESHSTREAM_SW_PING",protocolVersion:1},[i.port2])})}async function g(e,s,t=[]){const r=navigator.serviceWorker.controller??e.active??e.waiting??e.installing;if(!r)throw new Error("MeshStream Service Worker is not active");await new Promise((e,i)=>{const o=new MessageChannel,n=()=>{try{o.port1.close()}catch{}},a=setTimeout(()=>{n(),i(new Error("MeshStream Service Worker session acknowledgement timed out"))},2e3);o.port1.onmessage=s=>{clearTimeout(a),n(),"MESHSTREAM_SW_SESSION_READY"===s.data?.type||"MESHSTREAM_SW_SESSION_REMOVED"===s.data?.type?e():i(new Error("Invalid MeshStream Service Worker session acknowledgement"))},r.postMessage(s,[o.port2,...t])})}export{s as MESHSTREAM_SW_PATH_PREFIX,e as MESHSTREAM_SW_PROTOCOL_VERSION,r as MeshStreamServiceWorkerClient,S as buildMeshStreamServiceWorkerUrl,d as createMeshStreamServiceWorkerSession,a as isMeshStreamServiceWorkerSupported,c as registerMeshStreamServiceWorker};

package/dist/session-token.d.ts

@@ -0,0 +1,47 @@
+export interface WebSessionTokenRequest {
+    accessUrl?: string;
+    appId: string;
+    keyId?: string;
+    sessionId: string;
+    platform: "web";
+}
+export interface WebSessionTokenManagerOptions {
+    fetcher?: typeof fetch;
+    now?: () => number;
+    timeoutMs?: number;
+}
+export declare const DEFAULT_ACCESS_TIMEOUT_MS = 3000;
+export interface SessionTokenDiagnostics {
+    attempts: number;
+    successes: number;
+    failures: number;
+    durationMs: number;
+}
+export declare class WebSessionTokenManager {
+    private readonly accessUrl?;
+    private readonly appId;
+    private readonly keyId?;
+    private readonly sessionId;
+    private readonly platform;
+    private readonly fetcher;
+    private readonly now;
+    private readonly timeoutMs;
+    private token?;
+    private refreshAfterMs;
+    private expiresAtMs;
+    private refreshTimer;
+    private inFlight?;
+    private activeAbortController?;
+    private disposed;
+    private readonly authMetrics;
+    constructor(request: WebSessionTokenRequest, options?: WebSessionTokenManagerOptions);
+    getSessionToken(): Promise<string | undefined>;
+    getAuthorizationHeader(): Promise<string | undefined>;
+    getTrackerUrl(url: string): Promise<string | undefined>;
+    diagnostics(): SessionTokenDiagnostics;
+    dispose(): void;
+    private refreshToken;
+    private fetchSessionToken;
+    private scheduleRefresh;
+}
+export declare function createSessionId(prefix: string): string;

package/dist/url.d.ts

@@ -0,0 +1,39 @@
+export declare function selectTrackerUrl(fallbackUrl: string | undefined, trackerUrls: string[] | undefined, appId: string | undefined, swarmId: string, keyId?: string, primaryTrackerUrl?: string): string | undefined;
+/**
+ * Orders the Config API tracker pool with its authoritative primary first and
+ * keeps the remaining nodes as reconnect fallbacks. Identity and local proxy
+ * rewriting are applied consistently to every URL in the returned pool.
+ */
+export declare function selectTrackerUrls(fallbackUrl: string | undefined, trackerUrls: string[] | undefined, appId: string | undefined, swarmId: string, keyId?: string, primaryTrackerUrl?: string, scheduling?: TrackerSchedulingHints): string[];
+export interface TrackerSchedulingHints {
+    /**
+     * A Tracker-only playback-window hint. `auto` asks MeshStream Tracker to
+     * derive a rolling live window on every announce, so long-running live
+     * sessions remain comparable without reconnecting their WebSocket.
+     */
+    liveWindowBucket?: string;
+}
+export declare function browserProxyUrl(url: string | undefined, kind: "tracker" | "report"): string | undefined;
+export declare function isPrivateOrLocalHostname(hostname: string): boolean;
+export declare function browserProxyReportUrl(url: string | undefined): string | undefined;
+export declare function deriveReportUrl(trackerUrl?: string): string | undefined;
+export declare function withTrackerIdentity(url: string | undefined, config: {
+    appId?: string;
+    keyId?: string;
+} & TrackerSchedulingHints): string | undefined;
+export declare function withSessionToken(url: string | undefined, sessionToken: string | undefined): string | undefined;
+export declare function deriveSwarmIdFromUrl(url: string): string;
+export declare function deriveSwarmIdFromContentId(contentId: string): string;
+/**
+ * Resolves the stable identity sent to bootstrap for tracker affinity.
+ * Customer-provided IDs take precedence; otherwise the canonical playback
+ * URL is reduced to an opaque, stable URL identity that excludes volatile
+ * signing parameters.
+ */
+export declare function resolveBootstrapContentId(contentId: string | undefined, streamUrl: string): string;
+export declare function deriveReportContentId(contentId: string | undefined, streamUrl: string): string;
+export declare function redactPlaybackUrl(input: string): string;
+export declare function deriveSwarmBucketId(seed: string, bucketCount: number): number;
+export declare function getBucketedSwarmId(swarmId: string, bucketCount: number, bucketId: number): string;
+export declare function deriveBucketedSwarmIdFromUrl(url: string, seed: string, bucketCount?: number, bucketId?: number): string;
+export declare function canonicalizePlaybackUrl(input: string): string;