@glassly/engine 0.1.0-dev.0

package/build/services/PhoneStreamCoordinator.js

@@ -0,0 +1,740 @@
+/**
+ * PhoneStreamCoordinator — owns all local-miniapp streaming on the phone.
+ *
+ * Architecture:
+ *   miniapp → SDK → LocalMiniappRuntime → coordinator
+ *           coordinator → BluetoothSdk (BLE → glasses publisher)
+ *           coordinator ↔ cloudStreamApi (managed only, cloud-v2 runtime provisioning)
+ *           coordinator ↔ StreamLifecycleController (keep-alive heartbeat)
+ *           coordinator → status listeners → routed back to miniapp(s)
+ *
+ * Single-stream constraint:
+ *   At most ONE stream is active across all miniapps. The exception is that
+ *   multiple miniapps can subscribe to a single managed stream that's already
+ *   running — Cloudflare muxes one ingest into many viewers, so subscribers
+ *   share the same playback URLs. Refcounted; teardown happens when the last
+ *   subscriber releases.
+ *
+ * Status routing:
+ *   Glasses publisher status arrives over BLE as `stream_status` events with
+ *   a `streamId`. The coordinator's `owns(streamId)` lookup lets MantleManager
+ *   route phone-owned status events here (not to cloud). For managed streams,
+ *   we additionally poll Cloudflare's live-input status every 5s to surface
+ *   what the OTHER end of the pipe sees.
+ *
+ * Important: this is the ONLY place that mints `streamId`s for phone-owned
+ * streams. We use a `phone-` prefix so they're trivially distinguishable from
+ * cloud-minted IDs in logs and from cloud-SDK app streams that flow through
+ * the legacy path.
+ */
+import BluetoothSdk from "@glassly/bluetooth-sdk/internal";
+import { isGlassesConnected } from "./GlassesReadiness";
+import { useGlassesStore } from "../stores/glasses";
+import { StreamLifecycleController } from "./StreamLifecycleController";
+import { slimStreamStatusEvent, streamStatusSignature } from "./slimStreamStatus";
+import { getManagedStreamStatus, provisionManagedStream, teardownManagedStream, } from "./cloudStreamApi";
+/**
+ * Default cadence + thresholds. Exposed via {@link CoordinatorTimings} so tests
+ * can shorten them; production code should never override these.
+ */
+const DEFAULT_TIMINGS = {
+    keepAliveIntervalMs: 15_000,
+    ackTimeoutMs: 10_000,
+    maxMissedAcks: 3,
+    cloudflareStatusPollMs: 5_000,
+    // During WHIP startup, probe quickly so readiness is not quantized to the
+    // steady-state 5s monitoring cadence. The delay backs off on each miss.
+    cloudflareStartupPollInitialMs: 500,
+    // Cloudflare typically needs ~5-10s after first frame before HLS is live.
+    hlsReadinessInitialDelayMs: 5_000,
+    hlsReadinessPollMs: 2_000,
+    hlsReadinessMaxAttempts: 30,
+};
+// Console-backed minimal logger; replaces pino on the phone.
+const consoleLogger = {
+    child: (bindings) => ({
+        ...consoleLogger,
+        debug: (...args) => console.debug("[STREAM]", bindings, ...args),
+        warn: (...args) => console.warn("[STREAM]", bindings, ...args),
+        error: (...args) => console.error("[STREAM]", bindings, ...args),
+    }),
+    debug: (...args) => console.debug("[STREAM]", ...args),
+    warn: (...args) => console.warn("[STREAM]", ...args),
+    error: (...args) => console.error("[STREAM]", ...args),
+};
+export class StreamConflictError extends Error {
+    code;
+    stage;
+    transport;
+    constructor(code, message, 
+    /** Pipeline stage that failed (provision | command | publish | playback). */
+    stage, 
+    /** Transport in play at the failure (cloud-rest | ble | wifi). */
+    transport) {
+        super(message);
+        this.code = code;
+        this.stage = stage;
+        this.transport = transport;
+        this.name = "StreamConflictError";
+    }
+}
+/**
+ * Fail fast if glasses aren't connected — BEFORE provisioning. Without this a
+ * managed start would create a provider live input, fail the BLE command, and
+ * tear the input down again: a slow, billable no-op with a confusing error.
+ */
+function assertGlassesConnected() {
+    if (!isGlassesConnected(useGlassesStore.getState().connection)) {
+        throw new StreamConflictError("GLASSES_NOT_CONNECTED", "Glasses are not connected", "command", "ble");
+    }
+}
+export class PhoneStreamCoordinator {
+    current = null;
+    lifecycle = null;
+    statusSubscriber = null;
+    idCounter = 0;
+    timings;
+    /**
+     * Serializes state transitions (start, stop, teardown). Without it, a
+     * second `start*` racing with the first can pass the `this.current === null`
+     * pre-check while the first is still awaiting its provision/BLE work, and
+     * end up provisioning two separate streams. A teardown racing with a start
+     * can clear `current` mid-stop and let the start fire BLE writes that
+     * collide with the in-flight stopStream.
+     */
+    inFlight = Promise.resolve();
+    /** Drop identical stream_status fanouts within one session. */
+    lastFanoutSignature = null;
+    /** Send full resolvedConfig only once per stream session. */
+    resolvedConfigForwarded = false;
+    constructor(timings = {}) {
+        this.timings = { ...DEFAULT_TIMINGS, ...timings };
+    }
+    /**
+     * Run `work` under the transition lock. Each call awaits the previous
+     * transition before re-evaluating preconditions, so e.g. two concurrent
+     * `startManaged` calls are observed sequentially.
+     */
+    async runExclusive(work) {
+        const prev = this.inFlight;
+        let release;
+        this.inFlight = new Promise((r) => (release = r));
+        try {
+            await prev;
+            return await work();
+        }
+        finally {
+            release();
+        }
+    }
+    /**
+     * Register the function that routes status updates to miniapps.
+     * LocalMiniappRuntime wires this so updates become EVENT envelopes on the
+     * `stream_status` stream for every subscribing miniapp.
+     */
+    setStatusSubscriber(cb) {
+        this.statusSubscriber = cb;
+    }
+    /**
+     * True when a phone-owned stream currently uses this streamId. For managed
+     * streams, all subscribers share the same streamId so a single equality
+     * check covers the multi-subscriber case.
+     */
+    owns(streamId) {
+        return this.current !== null && this.current.streamId === streamId;
+    }
+    /** Report-safe stream ownership snapshot for incident diagnostics. */
+    getDiagnosticSnapshot() {
+        if (!this.current)
+            return { active: false };
+        return this.current.kind === "managed"
+            ? {
+                active: true,
+                kind: this.current.kind,
+                streamId: this.current.streamId,
+                subscribers: [...this.current.subscribers].sort(),
+                mode: this.current.mode,
+                playbackReady: this.current.hlsReady,
+            }
+            : {
+                active: true,
+                kind: this.current.kind,
+                streamId: this.current.streamId,
+                ownerPackageName: this.current.packageName,
+            };
+    }
+    async startUnmanaged(packageName, opts) {
+        // Pre-check the obvious-bad input before queueing — the lock is for
+        // serializing state transitions, not for validating arguments.
+        if (!opts.streamUrl || typeof opts.streamUrl !== "string") {
+            throw new StreamConflictError("STREAM_URL_REQUIRED", "streamUrl is required");
+        }
+        assertGlassesConnected();
+        return this.runExclusive(async () => {
+            if (this.current) {
+                throw new StreamConflictError("STREAM_ALREADY_ACTIVE", `A ${this.current.kind} stream is already active. Stop it before starting a new one.`);
+            }
+            const streamId = this.mintId("u");
+            const entry = {
+                kind: "unmanaged",
+                streamId,
+                packageName,
+                streamUrl: opts.streamUrl,
+            };
+            // Claim the slot BEFORE the BLE call so a concurrent caller waiting on
+            // the lock sees the in-progress entry and rejects with the conflict.
+            this.current = entry;
+            try {
+                const event = await BluetoothSdk.startExternallyManagedStream({
+                    type: "start_stream",
+                    streamUrl: opts.streamUrl,
+                    streamId,
+                    sound: opts.sound ?? true,
+                    // The native bridge rejects explicit `undefined` values ("Value is
+                    // undefined, expected an Object") — only include what was provided.
+                    ...(opts.video !== undefined ? { video: opts.video } : {}),
+                    ...(opts.audio !== undefined ? { audio: opts.audio } : {}),
+                    ...(opts.authToken ? { authToken: opts.authToken } : {}),
+                });
+                const result = publisherStartResult(streamId, event);
+                this.startLifecycle(streamId);
+                return result;
+            }
+            catch (err) {
+                this.current = null;
+                throw err;
+            }
+        });
+    }
+    async startManaged(packageName, opts) {
+        const startupStartedAtMs = Date.now();
+        // streamId doesn't exist yet — it's minted a few lines below, once we
+        // know this is a fresh provision rather than a join onto an existing one.
+        console.info("[STREAM_STARTUP]", {
+            stage: "requested",
+            packageName,
+            ingest: opts.ingest,
+            elapsedMs: 0,
+        });
+        // Two-phase: the entry-claim runs under the transition lock; the wait for
+        // HLS readiness happens AFTER the lock releases so a long warm-up doesn't
+        // block subsequent start/stop transitions on this coordinator.
+        assertGlassesConnected();
+        const decision = await this.runExclusive(async () => {
+            if (this.current && this.current.kind === "unmanaged") {
+                throw new StreamConflictError("STREAM_ALREADY_ACTIVE", "An unmanaged stream is already active. Stop it before starting a managed stream.");
+            }
+            // Join an existing managed stream if one is already running.
+            if (this.current && this.current.kind === "managed") {
+                const existing = this.current;
+                // Restream destinations are immutable after provision — a second
+                // caller trying to dictate destinations on an already-live stream
+                // is a likely bug or a feature we don't yet support.
+                if (opts.restreamDestinations && opts.restreamDestinations.length > 0) {
+                    throw new StreamConflictError("STREAM_DESTINATIONS_LOCKED", "Restream destinations cannot be modified on an already-running managed stream.");
+                }
+                existing.subscribers.add(packageName);
+                const immediate = existing.hlsReady ? managedStartResult(existing) : null;
+                return { kind: "join", entry: existing, immediate };
+            }
+            // Fresh provision — claim slot BEFORE awaiting Cloudflare so a
+            // concurrent caller queued behind us sees a managed stream in flight
+            // and joins instead of double-provisioning.
+            const provision = await provisionManagedStream(opts.restreamDestinations);
+            const streamId = this.mintId("m");
+            const ingestUrl = pickIngestUrl(provision, opts.ingest);
+            const mode = ingestUrl === provision.webrtcPublishUrl ? "webrtc" : "hls";
+            const entry = {
+                kind: "managed",
+                streamId,
+                liveInputId: provision.liveInputId,
+                ingestUrl,
+                mode,
+                hlsUrl: provision.hlsUrl,
+                dashUrl: provision.dashUrl,
+                webrtcUrl: provision.webrtcUrl,
+                subscribers: new Set([packageName]),
+                hlsReady: false,
+                hlsReadyResolvers: [],
+                hlsReadyRejecters: [],
+                hlsAttempts: 0,
+                cloudflareAttempts: 0,
+                startupStartedAtMs,
+            };
+            this.current = entry;
+            console.info("[STREAM_STARTUP]", {
+                streamId,
+                stage: "provisioned",
+                mode,
+                elapsedMs: Date.now() - startupStartedAtMs,
+            });
+            try {
+                const event = await BluetoothSdk.startExternallyManagedStream({
+                    type: "start_stream",
+                    streamUrl: ingestUrl,
+                    streamId,
+                    sound: opts.sound ?? true,
+                    // See startUnmanaged: the native bridge rejects explicit `undefined`.
+                    ...(opts.video !== undefined ? { video: opts.video } : {}),
+                    ...(opts.audio !== undefined ? { audio: opts.audio } : {}),
+                });
+                entry.publisherStart = publisherStartResult(streamId, event);
+                console.info("[STREAM_STARTUP]", {
+                    streamId,
+                    stage: "publisher_ready",
+                    mode,
+                    elapsedMs: Date.now() - startupStartedAtMs,
+                });
+            }
+            catch (err) {
+                this.current = null;
+                await teardownManagedStream(provision.liveInputId).catch(() => undefined);
+                throw err;
+            }
+            this.startLifecycle(streamId);
+            this.startCloudflareStatusPoll(entry);
+            // hls mode: readiness = a real HLS manifest exists. webrtc mode: HLS
+            // never materializes (Cloudflare WHIP limitation) — readiness resolves
+            // off the status poll's first "connected" instead.
+            if (entry.mode === "hls") {
+                this.startHlsReadinessPoll(entry);
+            }
+            return { kind: "fresh", entry };
+        });
+        if (decision.kind === "join" && decision.immediate) {
+            return decision.immediate;
+        }
+        // The first Cloudflare probe runs immediately and can complete before the
+        // transition lock releases. Avoid stranding this caller after readiness
+        // resolvers have already been drained.
+        if (decision.entry.hlsReady) {
+            return managedStartResult(decision.entry);
+        }
+        // Wait for playback readiness OUTSIDE the lock — readiness can take ~10s
+        // and we don't want to block other transitions for that long.
+        return new Promise((resolve, reject) => {
+            decision.entry.hlsReadyResolvers.push(resolve);
+            decision.entry.hlsReadyRejecters.push(reject);
+        });
+    }
+    async stop(packageName, streamId) {
+        await this.runExclusive(async () => {
+            if (!this.current)
+                return;
+            // If a streamId was passed but doesn't match, ignore — silent no-op
+            // matches the cloud's tolerant behavior.
+            if (streamId && this.current.streamId !== streamId)
+                return;
+            if (this.current.kind === "managed") {
+                const entry = this.current;
+                entry.subscribers.delete(packageName);
+                if (entry.subscribers.size > 0) {
+                    // Other miniapps still subscribed; keep the stream alive.
+                    return;
+                }
+            }
+            else if (this.current.packageName !== packageName) {
+                // Unmanaged stream: only the owner can stop it.
+                return;
+            }
+            await this.teardownLocked("explicit_stop");
+        });
+    }
+    /**
+     * Called by MantleManager when a `stream_status` event arrives from glasses
+     * and the registry says it's phone-owned.
+     */
+    handleGlassesStatus(event) {
+        if (!this.current)
+            return;
+        if (event.streamId && event.streamId !== this.current.streamId)
+            return;
+        this.lifecycle?.recordActivity();
+        const includeResolvedConfig = !this.resolvedConfigForwarded && !!event.resolvedConfig;
+        if (includeResolvedConfig)
+            this.resolvedConfigForwarded = true;
+        const slimData = slimStreamStatusEvent(event, { includeResolvedConfig });
+        const signature = streamStatusSignature(slimData);
+        if (signature === this.lastFanoutSignature)
+            return;
+        this.lastFanoutSignature = signature;
+        this.fanout({
+            streamId: this.current.streamId,
+            source: "glasses",
+            status: event.status,
+            data: slimData,
+        });
+        // Glasses-reported TERMINAL states unwind the coordinator. Terminal means
+        // the publisher gave up or stopped — NOT a transient `kind:"error"`: the
+        // glasses publisher auto-recovers (error → reconnecting → reconnected),
+        // and tearing down on the first hiccup deletes the live input out from
+        // under a publisher that comes right back (it then retries into a dead
+        // input forever). A publisher that errors and never recovers is reaped by
+        // the keep-alive ack timeout. Queue the teardown through the transition
+        // lock so it serializes with any start/stop currently in flight.
+        const isStopped = (event.kind === "lifecycle" && event.status === "stopped") ||
+            (event.kind === "snapshot" && event.status === "stopped");
+        const isGiveUp = event.kind === "reconnect" && event.status === "reconnect_failed";
+        if (isGiveUp || isStopped) {
+            const reason = isGiveUp ? "glasses_gave_up" : "glasses_stopped";
+            const targetStreamId = this.current.streamId;
+            void this.runExclusive(async () => {
+                // The stream we wanted to tear down may already be gone (e.g. another
+                // teardown won the lock and unwound it). Guard before acting.
+                if (this.current?.streamId !== targetStreamId)
+                    return;
+                await this.teardownLocked(reason, { sendBleStop: false });
+            });
+        }
+    }
+    /** Called by MantleManager when a phone-owned keep_alive_ack arrives. */
+    handleKeepAliveAck(event) {
+        if (!event.ackId)
+            return;
+        this.lifecycle?.handleAck(event.ackId);
+    }
+    // ===========================================================================
+    // Internal
+    // ===========================================================================
+    mintId(prefix) {
+        this.idCounter += 1;
+        return `phone-${prefix}-${Date.now().toString(36)}-${this.idCounter}`;
+    }
+    startLifecycle(streamId) {
+        this.lifecycle?.dispose();
+        const ctrl = new StreamLifecycleController({
+            logger: consoleLogger,
+            streamId,
+            keepAliveIntervalMs: this.timings.keepAliveIntervalMs,
+            ackTimeoutMs: this.timings.ackTimeoutMs,
+            maxMissedAcks: this.timings.maxMissedAcks,
+        }, {
+            sendKeepAlive: async (ackId) => {
+                await BluetoothSdk.sendExternallyManagedStreamKeepAlive({
+                    type: "keep_stream_alive",
+                    streamId,
+                    ackId,
+                });
+            },
+            onTimeout: async () => {
+                this.fanout({
+                    streamId,
+                    source: "coordinator",
+                    status: "error",
+                    data: { reason: "keep_alive_timeout" },
+                });
+                await this.runExclusive(async () => {
+                    // The stream this timeout was bound to may already be gone.
+                    if (this.current?.streamId !== streamId)
+                        return;
+                    await this.teardownLocked("keep_alive_timeout");
+                });
+            },
+        });
+        ctrl.setActive(true);
+        this.lifecycle = ctrl;
+    }
+    startCloudflareStatusPoll(entry) {
+        // Keep the existing ~60s readiness budget while decoupling it from probe
+        // count. Startup probes begin immediately and back off to the normal 5s
+        // monitoring cadence, so a just-connected publisher is noticed quickly
+        // without increasing steady-state traffic.
+        const connectTimeoutMs = Math.max(1, this.timings.hlsReadinessMaxAttempts * this.timings.hlsReadinessPollMs);
+        const pollingStartedAtMs = Date.now();
+        const scheduleNext = () => {
+            if (this.current !== entry)
+                return;
+            const waitingForWebRtc = entry.mode === "webrtc" && !entry.hlsReady;
+            const elapsedMs = Date.now() - pollingStartedAtMs;
+            const remainingMs = Math.max(0, connectTimeoutMs - elapsedMs);
+            const startupDelayMs = Math.min(this.timings.cloudflareStatusPollMs, this.timings.cloudflareStartupPollInitialMs * 2 ** Math.min(Math.max(0, entry.cloudflareAttempts - 1), 10));
+            const delayMs = waitingForWebRtc ? Math.min(startupDelayMs, remainingMs) : this.timings.cloudflareStatusPollMs;
+            entry.cloudflareTimer = setTimeout(() => void poll(), delayMs);
+        };
+        const poll = async () => {
+            if (this.current !== entry)
+                return;
+            const requestStartedAtMs = Date.now();
+            let keepPolling = true;
+            entry.cloudflareAttempts += 1;
+            try {
+                const status = await getManagedStreamStatus(entry.liveInputId);
+                console.debug("[STREAM_STARTUP]", {
+                    streamId: entry.streamId,
+                    stage: "cloudflare_probe",
+                    connected: status.isConnected,
+                    attempt: entry.cloudflareAttempts,
+                    requestMs: Date.now() - requestStartedAtMs,
+                    elapsedMs: Date.now() - entry.startupStartedAtMs,
+                });
+                this.fanout({
+                    streamId: entry.streamId,
+                    source: "cloudflare",
+                    status: status.isConnected ? "connected" : "disconnected",
+                    data: status,
+                });
+                // webrtc mode readiness: first "connected" means WHEP playback is
+                // available (WebRTC playback follows the ingest directly; there is no
+                // manifest to probe).
+                if (entry.mode === "webrtc" && !entry.hlsReady) {
+                    if (status.isConnected) {
+                        entry.hlsReady = true;
+                        console.info("[STREAM_STARTUP]", {
+                            streamId: entry.streamId,
+                            stage: "playback_ready",
+                            mode: entry.mode,
+                            probes: entry.cloudflareAttempts,
+                            elapsedMs: Date.now() - entry.startupStartedAtMs,
+                        });
+                        const result = managedStartResult(entry);
+                        for (const r of entry.hlsReadyResolvers)
+                            r(result);
+                        entry.hlsReadyResolvers = [];
+                        entry.hlsReadyRejecters = [];
+                        this.fanout({
+                            streamId: entry.streamId,
+                            source: "coordinator",
+                            status: "webrtc_ready",
+                            data: result,
+                        });
+                    }
+                    else {
+                        if (Date.now() - pollingStartedAtMs >= connectTimeoutMs) {
+                            const err = new Error(`WebRTC ingest never reached Cloudflare after ${connectTimeoutMs}ms`);
+                            for (const reject of entry.hlsReadyRejecters)
+                                reject(err);
+                            entry.hlsReadyResolvers = [];
+                            entry.hlsReadyRejecters = [];
+                            this.fanout({
+                                streamId: entry.streamId,
+                                source: "coordinator",
+                                status: "error",
+                                data: { reason: "webrtc_not_connected" },
+                            });
+                            const targetStreamId = entry.streamId;
+                            void this.runExclusive(async () => {
+                                if (this.current?.streamId !== targetStreamId)
+                                    return;
+                                await this.teardownLocked("webrtc_not_connected");
+                            });
+                            keepPolling = false;
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                console.warn("[STREAM] cloudflare status poll failed:", err);
+                if (entry.mode === "webrtc" && !entry.hlsReady && Date.now() - pollingStartedAtMs >= connectTimeoutMs) {
+                    const timeoutErr = new Error(`WebRTC ingest status could not be confirmed after ${connectTimeoutMs}ms`);
+                    for (const reject of entry.hlsReadyRejecters)
+                        reject(timeoutErr);
+                    entry.hlsReadyResolvers = [];
+                    entry.hlsReadyRejecters = [];
+                    const targetStreamId = entry.streamId;
+                    void this.runExclusive(async () => {
+                        if (this.current?.streamId !== targetStreamId)
+                            return;
+                        await this.teardownLocked("webrtc_status_unavailable");
+                    });
+                    keepPolling = false;
+                }
+            }
+            finally {
+                if (keepPolling)
+                    scheduleNext();
+            }
+        };
+        // The glasses publisher has already reported streaming, so the first
+        // status request is useful now. Most starts avoid the old blind 5s wait.
+        void poll();
+    }
+    startHlsReadinessPoll(entry) {
+        // Skip the first few seconds — Cloudflare doesn't have first-frame yet,
+        // and the HEAD requests would all 404 and burn battery.
+        const tick = async () => {
+            if (this.current !== entry)
+                return;
+            entry.hlsAttempts += 1;
+            try {
+                // Require a real manifest (200 with a body), not just res.ok — the
+                // playback edge returns 204 No Content while the input has no
+                // HLS-capable frames (e.g. WebRTC ingest), and 204 is "ok".
+                const res = await fetch(entry.hlsUrl, { method: "HEAD" });
+                if (res.status === 200) {
+                    entry.hlsReady = true;
+                    console.info("[STREAM_STARTUP]", {
+                        streamId: entry.streamId,
+                        stage: "playback_ready",
+                        mode: entry.mode,
+                        probes: entry.hlsAttempts,
+                        elapsedMs: Date.now() - entry.startupStartedAtMs,
+                    });
+                    if (entry.hlsTimer) {
+                        clearInterval(entry.hlsTimer);
+                        entry.hlsTimer = undefined;
+                    }
+                    const result = managedStartResult(entry);
+                    for (const r of entry.hlsReadyResolvers)
+                        r(result);
+                    entry.hlsReadyResolvers = [];
+                    entry.hlsReadyRejecters = [];
+                    this.fanout({
+                        streamId: entry.streamId,
+                        source: "coordinator",
+                        status: "hls_ready",
+                        data: result,
+                    });
+                    return;
+                }
+            }
+            catch {
+                // 404 / network blip is expected while Cloudflare warms up.
+            }
+            if (entry.hlsAttempts >= this.timings.hlsReadinessMaxAttempts) {
+                if (entry.hlsTimer) {
+                    clearInterval(entry.hlsTimer);
+                    entry.hlsTimer = undefined;
+                }
+                const err = new Error(`HLS playback URL did not become ready after ${this.timings.hlsReadinessMaxAttempts} attempts`);
+                for (const reject of entry.hlsReadyRejecters)
+                    reject(err);
+                entry.hlsReadyResolvers = [];
+                entry.hlsReadyRejecters = [];
+                this.fanout({
+                    streamId: entry.streamId,
+                    source: "coordinator",
+                    status: "error",
+                    data: { reason: "hls_not_ready" },
+                });
+                const targetStreamId = entry.streamId;
+                void this.runExclusive(async () => {
+                    if (this.current?.streamId !== targetStreamId)
+                        return;
+                    await this.teardownLocked("hls_not_ready");
+                });
+            }
+        };
+        setTimeout(() => {
+            // Guard: stream may have been torn down during the initial delay.
+            if (this.current !== entry)
+                return;
+            entry.hlsTimer = setInterval(tick, this.timings.hlsReadinessPollMs);
+        }, this.timings.hlsReadinessInitialDelayMs);
+    }
+    fanout(update) {
+        if (!this.current || !this.statusSubscriber)
+            return;
+        const targets = this.current.kind === "managed" ? Array.from(this.current.subscribers) : [this.current.packageName];
+        for (const pkg of targets) {
+            try {
+                this.statusSubscriber(pkg, update);
+            }
+            catch (err) {
+                console.warn("[STREAM] statusSubscriber threw:", err);
+            }
+        }
+    }
+    /**
+     * Run teardown of the currently-active stream. Caller must hold the
+     * transition lock (see {@link runExclusive}). Keeps `this.current`
+     * populated until BluetoothSdk.stopStream resolves so a concurrent caller
+     * waiting on the lock can't claim the slot mid-stop and have its
+     * startStream BLE write collide with our in-flight stopStream.
+     */
+    async teardownLocked(reason, options = {}) {
+        const entry = this.current;
+        if (!entry)
+            return;
+        const sendBleStop = options.sendBleStop !== false;
+        this.lastFanoutSignature = null;
+        this.resolvedConfigForwarded = false;
+        // Dispose the lifecycle controller immediately so it doesn't fire one
+        // more keep-alive against a stream we're tearing down. The transition
+        // lock guarantees no new lifecycle is started concurrently.
+        this.lifecycle?.dispose();
+        this.lifecycle = null;
+        if (entry.kind === "managed") {
+            if (entry.cloudflareTimer)
+                clearTimeout(entry.cloudflareTimer);
+            if (entry.hlsTimer)
+                clearInterval(entry.hlsTimer);
+            // Reject any still-pending HLS readiness waiters.
+            const pendingErr = new Error(`Stream torn down: ${reason}`);
+            for (const reject of entry.hlsReadyRejecters)
+                reject(pendingErr);
+            entry.hlsReadyResolvers = [];
+            entry.hlsReadyRejecters = [];
+            // Cloudflare DELETE is fire-and-forget — failing it doesn't undo the
+            // BLE stop we're about to do, and Cloudflare's idle-input scavenger
+            // will eventually clean up leaked inputs.
+            teardownManagedStream(entry.liveInputId).catch((err) => {
+                console.warn("[STREAM] teardownManagedStream failed:", err);
+            });
+        }
+        try {
+            if (sendBleStop) {
+                await BluetoothSdk.stopStream();
+            }
+        }
+        catch (err) {
+            console.warn("[STREAM] BluetoothSdk.stopStream failed:", err);
+        }
+        finally {
+            // Release the slot AFTER the BLE stop finished, so the next start can
+            // safely write its own start_stream without colliding with ours.
+            // Only clear if we're still the active entry (defensive — runExclusive
+            // serializes us, so this should always be true).
+            if (this.current === entry)
+                this.current = null;
+        }
+    }
+}
+function pickIngestUrl(p, preference) {
+    // Glasses' StreamCommandHandler detects protocol from URL prefix.
+    //
+    // Default priority: SRT > RTMP > WHIP. SRT first: Cloudflare's WebRTC (WHIP)
+    // ingest does NOT feed HLS/DASH playback or recording — a WHIP-ingested
+    // managed stream reports "connected" while its hlsUrl serves 204 forever,
+    // which breaks the managed contract (subscribers share HLS playback). SRT
+    // also survives office firewalls that kill RTMPS:443 mid-handshake.
+    //
+    // "whip" preference flips the trade: sub-second WHEP playback for
+    // live-monitor use cases, accepting no HLS and no recording.
+    // "rtmp" prefers TCP 443 ingest so networks that drop WHIP/SRT UDP still
+    // get HLS playback. Callers must request it explicitly; WHIP starts do not
+    // fall back to RTMP.
+    //
+    // Throw if none resolved so the caller's Promise rejects with a clear
+    // message rather than the glasses' "unknown protocol" error.
+    const url = preference === "whip"
+        ? p.webrtcPublishUrl || p.srtUrl || p.rtmpUrl
+        : preference === "rtmp"
+            ? p.rtmpUrl || p.srtUrl || p.webrtcPublishUrl
+            : p.srtUrl || p.rtmpUrl || p.webrtcPublishUrl;
+    if (!url) {
+        throw new Error("Cloudflare provision returned no usable ingest URL");
+    }
+    return url;
+}
+function publisherStartResult(streamId, event) {
+    return {
+        streamId: event?.streamId || streamId,
+        status: event?.status ?? "streaming",
+        ...(event?.resolvedConfig ? { resolvedConfig: event.resolvedConfig } : {}),
+    };
+}
+function managedStartResult(entry) {
+    const publisher = entry.publisherStart ?? publisherStartResult(entry.streamId);
+    return {
+        ...publisher,
+        streamId: entry.streamId,
+        liveInputId: entry.liveInputId,
+        mode: entry.mode,
+        hlsUrl: entry.hlsUrl,
+        dashUrl: entry.dashUrl,
+        webrtcUrl: entry.webrtcUrl,
+    };
+}
+// Singleton — coordinator's single-stream constraint is process-wide.
+export const phoneStreamCoordinator = new PhoneStreamCoordinator();
+//# sourceMappingURL=PhoneStreamCoordinator.js.map