@mentra/engine 3.2.0-dev.221 → 3.2.0-dev.222

package/build/services/SoftapCallTransport.js

@@ -0,0 +1,722 @@
+/**
+ * @fileoverview Sequences a SoftAP call. Sequencing only — no sockets, no peers, no BLE.
+ *
+ * The glasses open a hotspot, the phone joins it without giving up its cellular route, and the
+ * glasses publish WebRTC straight to a listener on the phone. Cloudflare is not involved at all.
+ *
+ * The order below is the whole point of this file, and one step in it is load-bearing:
+ *
+ *   hotspot on -> scoped join -> ACS join (binds the listener and arms the raw outputs)
+ *     -> glasses publish -> WHIP negotiation -> first frame -> LIVE
+ *
+ * Publishing must come after the ACS join, not before. `LIVE` means a frame reached ACS, so if the
+ * glasses start publishing first, decoded video and audio can arrive before the raw outgoing
+ * streams exist and the first frames are dropped by whatever happens to be null at the time. That
+ * is not a lifecycle anyone designed; making the order explicit is what removes it.
+ *
+ * Ownership is deliberately narrow. This object owns the *sequence* and nothing else: the meeting
+ * session owns the WHIP listener and the peer, `PhoneStreamCoordinator` owns the publisher, and
+ * `localNetworkTransport` owns the scoped network. Every step therefore has exactly one owner that
+ * can tear it down, which is what makes leaving mid-join safe.
+ */
+import { softapTrace, softapTraceFailure, beginSoftapTrace, resetSoftapTrace } from "../utils/softapTrace";
+/** Steps in order. Also the teardown order, reversed. */
+export const SOFTAP_STEPS = ["hotspot", "scopedJoin", "acsJoin", "publish", "live"];
+/** A failure, named by the step that produced it so the UI and the logs agree on the cause. */
+export class SoftapCallError extends Error {
+    step;
+    code;
+    cause;
+    constructor(step, code, message, cause) {
+        super(message);
+        this.step = step;
+        this.code = code;
+        this.cause = cause;
+        this.name = "SoftapCallError";
+    }
+}
+/** Gallery sync already learned this: glasses report enabled before the SSID is in the phone scan. */
+export const HOTSPOT_BROADCAST_WAIT_MS = 3_000;
+/**
+ * Android's WifiNetworkSpecifier called onUnavailable. The native message lists three causes
+ * because the callback does not say which one happened; on the 18:02 Samsung path the SSID was
+ * in scan and the join sheet was bypassed — assoc rejected after leaving another AP.
+ */
+function isScopedJoinUnavailable(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /SOFTAP_UNAVAILABLE|ScopedNetworkError\$Unavailable|SSID not in scan, Wi-Fi off, or the system join prompt/i.test(message);
+}
+function freshSteps() {
+    return SOFTAP_STEPS.map((step) => ({ step, status: "pending" }));
+}
+/** See {@link SoftapCallOptions.initialSteps}. */
+function seededSteps(initial) {
+    if (!initial?.length)
+        return freshSteps();
+    return freshSteps().map((step) => {
+        const seed = initial.find((entry) => entry.step === step.step);
+        return seed?.detail ? { ...step, detail: seed.detail } : step;
+    });
+}
+/** A promise plus the function that settles it. */
+function deferred() {
+    let resolve;
+    const promise = new Promise((settle) => {
+        resolve = settle;
+    });
+    return { promise, resolve };
+}
+export class SoftapEndNotSupportedError extends Error {
+    constructor() {
+        super("This host cannot end a meeting for everyone");
+        this.name = "SoftapEndNotSupportedError";
+    }
+}
+export class SoftapCallTransport {
+    deps;
+    phase = "idle";
+    /**
+     * Steps completed and not yet undone, in the order they succeeded. Teardown walks this
+     * backwards, so a failure halfway through unwinds exactly what was built and nothing else.
+     */
+    completed = [];
+    /**
+     * Bumped by every start and stop. A step that resolves after the caller has moved on must not
+     * write to the new attempt's state, which is the leave-during-join race.
+     */
+    generation = 0;
+    stopping = null;
+    /**
+     * The step currently in flight, and a promise that settles only after its body *and* the undo it
+     * runs when it finds itself cancelled are both finished.
+     *
+     * This is what [stop] waits on. A step that resolves late still owns a resource — a hotspot that
+     * came up after the wearer left — and its release happens inside the step, out of the teardown's
+     * sight. Without this wait, `stop()` resolves while that release is still pending and the next
+     * call brings a hotspot up straight into it.
+     */
+    running = null;
+    /** True once [start] has been called at least once, so [stop] can tell "cancelled" from "reusable". */
+    startedEver = false;
+    /**
+     * A [stop] that landed before the sequence ever began.
+     *
+     * There is nothing to unwind in that case, so the flag is the only thing that can carry the
+     * cancellation forward: a `start()` arriving afterwards belongs to the attempt that was just
+     * cancelled and must refuse rather than build a call nobody is waiting for.
+     */
+    cancelledBeforeStart = false;
+    /** Failed undos for this attempt, retained across repeated stops. See [lastTeardownFailures]. */
+    teardownFailures = [];
+    /**
+     * Raised the instant a teardown is decided, before any resource is touched.
+     *
+     * Everything that watches the call for failure — a lost hotspot above all — has to be able to ask
+     * "was this supposed to happen?". Without the flag, releasing the scoped network during a
+     * successful Leave looks exactly like the glasses walking out of range, and the wearer gets an
+     * error screen for a call that ended the way they asked.
+     */
+    terminating = false;
+    /** How this teardown ends the meeting. Read by the `acsJoin` undo. */
+    teardownMode = "leave";
+    /** Set when `stop({mode: "end"})` could not end for everyone. The caller must not claim it did. */
+    endFailure = null;
+    hotspot = null;
+    ingestUrl = null;
+    steps = freshSteps();
+    stepStartedAt = new Map();
+    startedAt = 0;
+    traceId = "";
+    onProgress;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    currentPhase() {
+        return this.phase;
+    }
+    /**
+     * True once a teardown has been decided. Anything that would otherwise report a failure — a lost
+     * hotspot, a dropped ACS call — must check this first: after the wearer asks to leave, those are
+     * the sound of it working.
+     */
+    isTerminating() {
+        return this.terminating;
+    }
+    /** What the UI should show right now. Safe to call in any phase. */
+    progress() {
+        return {
+            traceId: this.traceId,
+            phase: this.phase,
+            steps: this.steps.map((step) => ({ ...step })),
+            elapsedMs: this.startedAt ? Date.now() - this.startedAt : 0,
+        };
+    }
+    emitProgress() {
+        const listener = this.onProgress;
+        if (!listener)
+            return;
+        try {
+            listener(this.progress());
+        }
+        catch (error) {
+            softapTraceFailure("softap_progress_listener_threw", {
+                reason: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    setStep(step, patch) {
+        this.steps = this.steps.map((entry) => (entry.step === step ? { ...entry, ...patch } : entry));
+        this.emitProgress();
+    }
+    /** Narration for a running step: what the phone or the glasses just reported. */
+    note(generation, step, detail) {
+        if (generation !== this.generation) {
+            // A step that is still narrating after the sequence moved on. The detail is dropped rather
+            // than written onto the new attempt's checklist, and the drop is said out loud because a
+            // step that goes quiet here is usually one that is still holding a native call open.
+            softapTrace("softap_step_note_dropped", { step, generation, current: this.generation, detail });
+            return;
+        }
+        softapTrace("softap_step_note", { step, detail });
+        this.setStep(step, { detail });
+    }
+    /** Steps currently built up, oldest first. Empty when nothing needs tearing down. */
+    activeSteps() {
+        return [...this.completed];
+    }
+    /** The URL handed to the glasses, for diagnostics. Null outside a live attempt. */
+    currentIngestUrl() {
+        return this.ingestUrl;
+    }
+    /**
+     * Steps whose undo threw during the last teardown, so the caller can refuse the next call.
+     *
+     * Teardown deliberately swallows these to keep unwinding — but a hotspot that would not turn off
+     * is exactly the state the next call cannot be built on, and starting anyway is what produced
+     * "Cannot start glasses hotspot" followed by a scoped join that never found the SSID.
+     */
+    lastTeardownFailures() {
+        // Logged on read rather than only on write, because this is the moment the list turns into a
+        // refusal for the next call: a wearer told to power-cycle the hotspot needs the reason to be
+        // findable, and the write happened somewhere in the middle of a noisy teardown.
+        if (this.teardownFailures.length > 0) {
+            softapTraceFailure("softap_teardown_failures_read", { steps: this.teardownFailures.join(",") });
+        }
+        return [...this.teardownFailures];
+    }
+    /**
+     * Runs the sequence. On any failure the partial sequence is torn down before the error is
+     * rethrown, so a failed start never leaves a hotspot up or a publisher running.
+     */
+    async start(options = {}) {
+        if (this.cancelledBeforeStart) {
+            // The wearer's Cancel landed before the sequence began, so there is no step to name and no
+            // trace id yet. This line is the only evidence that the flag did its job rather than the
+            // join having silently never been asked for.
+            softapTraceFailure("softap_call_refused", { reason: "cancelled before start" });
+            throw new SoftapCallError("hotspot", "CANCELLED", "SoftAP call was cancelled before it started");
+        }
+        if (this.phase !== "idle" && this.phase !== "failed") {
+            softapTraceFailure("softap_call_refused", { reason: "already active", phase: this.phase });
+            throw new SoftapCallError("hotspot", "ALREADY_ACTIVE", `A SoftAP call is already ${this.phase}`);
+        }
+        this.startedEver = true;
+        const generation = ++this.generation;
+        this.phase = "starting";
+        this.terminating = false;
+        this.teardownMode = "leave";
+        this.endFailure = null;
+        this.completed = [];
+        this.ingestUrl = null;
+        this.hotspot = null;
+        this.teardownFailures = [];
+        this.steps = seededSteps(options.initialSteps);
+        this.stepStartedAt.clear();
+        this.startedAt = Date.now();
+        this.onProgress = options.onProgress;
+        const traceId = beginSoftapTrace(options.traceId);
+        this.traceId = traceId;
+        softapTrace("softap_call_start", { traceId });
+        this.emitProgress();
+        try {
+            await this.step(generation, "hotspot", "HOTSPOT_FAILED", async (report) => {
+                report("Asking the glasses to turn on their hotspot");
+                const hotspot = await this.deps.startHotspot(report);
+                if (!hotspot.ssid) {
+                    throw new Error("the glasses reported no hotspot SSID");
+                }
+                this.hotspot = hotspot;
+                // The passphrase never reaches the log; softapTrace redacts it by key, and only the SSID
+                // is useful for matching against the phone's Wi-Fi state anyway.
+                softapTrace("hotspot_enabled", { ssid: hotspot.ssid });
+                report(`Hotspot ${hotspot.ssid} is on; waiting for it to broadcast`);
+                await this.deps.waitUntilHotspotJoinable?.(report);
+                softapTrace("hotspot_broadcast_wait_done", { ssid: hotspot.ssid });
+                report(`Hotspot ${hotspot.ssid}`);
+            });
+            const hotspot = this.requireHotspot();
+            let bindAddress;
+            await this.step(generation, "scopedJoin", "SCOPED_JOIN_FAILED", async (report) => {
+                report(`Phone joining ${hotspot.ssid}. Turn Wi-Fi on if a panel opens — Teams stays on cellular.`);
+                bindAddress = await this.deps.joinScopedNetwork(hotspot.ssid, hotspot.passphrase, report);
+                softapTrace("scoped_network_joined", { bindAddress: bindAddress ?? "unknown" });
+                if (bindAddress)
+                    report(`Phone is ${bindAddress} on ${hotspot.ssid}`);
+            });
+            await this.step(generation, "acsJoin", "ACS_JOIN_FAILED", async (report) => {
+                report(bindAddress ? `Opening video receiver on ${bindAddress}, then joining Teams` : "Joining Teams");
+                const { ingestUrl } = await this.deps.joinMeeting({
+                    ssid: hotspot.ssid,
+                    passphrase: hotspot.passphrase,
+                    bindAddress,
+                }, report);
+                if (!ingestUrl) {
+                    // Without a bound listener there is nowhere for the glasses to publish, and telling them
+                    // to publish anyway produces a failure several seconds later on the wrong device.
+                    throw new Error("the meeting reported no ingest URL");
+                }
+                this.ingestUrl = ingestUrl;
+                softapTrace("acs_joined", { ingestUrl });
+                report(`Receiver ready at ${ingestUrl}`);
+            });
+            const ingestUrl = this.requireIngestUrl();
+            await this.step(generation, "publish", "PUBLISH_FAILED", async (report) => {
+                report("Telling the glasses to start the camera and publish to the phone");
+                await this.deps.startPublishing({ ingestUrl, traceId }, report);
+                softapTrace("glasses_publishing", { ingestUrl });
+                report("Glasses camera is streaming to the phone");
+            });
+            await this.step(generation, "live", "NO_FIRST_FRAME", async (report) => {
+                report("Waiting for the first video frame to reach Teams");
+                await this.deps.awaitFirstFrame(report);
+                softapTrace("first_frame_in_acs");
+                report("Video is live in the meeting");
+            });
+            if (generation !== this.generation) {
+                // Every step succeeded and the call is nevertheless not this transport's any more. The
+                // steps released themselves on the way past, so there is nothing to undo — but a join
+                // that got all the way to a frame and then vanished is otherwise a log that simply stops.
+                softapTraceFailure("softap_call_abandoned_at_live", { generation, current: this.generation });
+                return;
+            }
+            this.phase = "live";
+            softapTrace("softap_call_live");
+            this.emitProgress();
+        }
+        catch (error) {
+            // Unwind before rethrowing. A caller that sees a rejection is entitled to assume nothing was
+            // left running, and a hotspot left up is both a battery cost and a second call's failure.
+            await this.stop({ keepProgress: true });
+            this.phase = "failed";
+            this.emitProgress();
+            throw error;
+        }
+    }
+    /**
+     * Tears down in exact reverse order, and only what was built.
+     *
+     * Every step is attempted even if an earlier one throws: a failure to stop the publisher must
+     * not leave the hotspot on. Concurrent calls share one teardown rather than racing each other
+     * through the same resources, and a second `stop()` after one finished is a no-op — this is the
+     * only SoftAP exit, so every terminal path can call it without checking whether another already
+     * did.
+     *
+     * `mode: "end"` swaps the meeting verb and nothing else. If ending for everyone fails, the rest of
+     * the teardown still runs and the failure is rethrown at the end, so the caller can tell the
+     * wearer they left a meeting that may still be live rather than inventing a clean end.
+     */
+    async stop(options = {}) {
+        // Intent before action, always: a watcher must be able to tell a deliberate teardown from a
+        // failure even during the very first await below.
+        this.terminating = true;
+        if (options.mode)
+            this.teardownMode = options.mode;
+        if (this.stopping) {
+            softapTrace("softap_stop_joined_in_flight", { mode: this.teardownMode });
+            return this.stopping;
+        }
+        const running = this.running;
+        if (this.completed.length === 0 && this.phase === "idle" && !running) {
+            // Nothing was built, so there is nothing to unwind — but a start() that has not run yet
+            // still has to be refused, and a generation bump still has to invalidate anything holding
+            // the old one.
+            this.generation++;
+            if (!this.startedEver)
+                this.cancelledBeforeStart = true;
+            softapTrace("softap_stop_nothing_built", {
+                // The distinction the next `start()` turns on: a transport that was never started refuses
+                // outright, one that has already run is reusable.
+                cancelledBeforeStart: this.cancelledBeforeStart,
+                generation: this.generation,
+            });
+            return;
+        }
+        this.generation++;
+        this.phase = "stopping";
+        this.endFailure = null;
+        softapTrace("softap_call_stop", { steps: this.completed.join(","), mode: this.teardownMode });
+        this.emitProgress();
+        this.stopping = (async () => {
+            // The generation bump above has already told the in-flight step to release whatever it
+            // produced. Waiting for that release is what makes a resolved `stop()` mean "nothing from
+            // this call is still coming". Deliberately unbounded: a native call that never returns must
+            // hold the next call back, never let it race this one's cleanup.
+            if (running) {
+                softapTrace("softap_stop_waiting_for_step", { step: running.step });
+                const waitStartedAt = Date.now();
+                await running.settled;
+                // This wait is unbounded by design, so its duration is the difference between "the leave
+                // was slow" and "the leave was held by a native call that had not returned".
+                softapTrace("softap_stop_step_settled", { step: running.step, waitedMs: Date.now() - waitStartedAt });
+            }
+            // The late step may have recorded a failed self-undo while we waited. Preserve it,
+            // and any earlier teardown result, until start() explicitly begins a new attempt.
+            const failures = [...this.teardownFailures];
+            for (const step of [...this.completed].reverse()) {
+                const undoStartedAt = Date.now();
+                try {
+                    await this.undo(step);
+                    softapTrace("softap_step_undone", { step, durationMs: Date.now() - undoStartedAt });
+                }
+                catch (error) {
+                    // Recorded, not rethrown: the remaining steps still have to be undone. The caller reads
+                    // them back through [lastTeardownFailures] and refuses the next call, because a hotspot
+                    // that would not turn off is exactly the state the next call cannot build on.
+                    failures.push(step);
+                    softapTraceFailure("softap_step_undo_failed", {
+                        step,
+                        durationMs: Date.now() - undoStartedAt,
+                        reason: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+            this.completed = [];
+            this.hotspot = null;
+            this.ingestUrl = null;
+            this.phase = "idle";
+            this.teardownFailures = failures;
+            softapTrace("softap_call_stopped", { undoFailures: failures.join(",") });
+            resetSoftapTrace();
+            // A failed start keeps its checklist so the UI can show which step broke; a deliberate
+            // leave wipes it, because there is nothing left to explain.
+            if (!options.keepProgress) {
+                this.steps = freshSteps();
+                this.emitProgress();
+            }
+        })();
+        try {
+            await this.stopping;
+        }
+        finally {
+            this.stopping = null;
+        }
+        // Rethrown last, after every resource is released. An End that could not terminate the meeting
+        // has still taken this device out; only the claim about the others is wrong.
+        const endFailure = this.endFailure;
+        this.endFailure = null;
+        if (endFailure)
+            throw endFailure;
+    }
+    async undo(step) {
+        switch (step) {
+            // `live` is an observation, not a resource — there is nothing to release.
+            case "live":
+                return;
+            case "publish":
+                return this.deps.stopPublishing();
+            case "acsJoin":
+                return this.leaveOrEndMeeting();
+            case "scopedJoin":
+                return this.deps.leaveScopedNetwork();
+            case "hotspot":
+                return this.deps.stopHotspot();
+        }
+    }
+    /**
+     * The one step End changes.
+     *
+     * A failed End falls back to leaving, so the wearer is out either way, and the original failure is
+     * kept for [stop] to rethrow. Recording it rather than throwing here is what keeps the hotspot
+     * teardown — the steps after this one — unconditional.
+     */
+    async leaveOrEndMeeting() {
+        if (this.teardownMode !== "end")
+            return this.deps.leaveMeeting();
+        const endMeeting = this.deps.endMeeting;
+        if (!endMeeting) {
+            this.endFailure = new SoftapEndNotSupportedError();
+            return this.deps.leaveMeeting();
+        }
+        try {
+            await endMeeting();
+            softapTrace("softap_meeting_ended_for_everyone");
+        }
+        catch (error) {
+            this.endFailure = error;
+            softapTraceFailure("softap_end_for_everyone_failed", {
+                reason: error instanceof Error ? error.message : String(error),
+            });
+            // Native ends the local call even when the hang-up is refused, so this is a belt-and-braces
+            // leave rather than a second teardown: it must not resurrect the failure it is covering for.
+            await this.deps.leaveMeeting().catch(() => undefined);
+        }
+    }
+    /**
+     * Runs one step, records it as undoable, and maps any throw to a [SoftapCallError] naming the
+     * step. The generation check is what makes leaving mid-step safe: a step that resolves after the
+     * caller gave up is not recorded, so teardown does not try to undo it twice.
+     */
+    async step(generation, step, code, run) {
+        if (generation !== this.generation) {
+            // The sequence stopped between two steps. Named here because the caller only ever sees one
+            // CANCELLED error, and which step it never reached is the thing worth knowing.
+            softapTraceFailure("softap_step_skipped_after_cancel", { step, generation, current: this.generation });
+            throw new SoftapCallError(step, "CANCELLED", `SoftAP call was cancelled before ${step}`);
+        }
+        // Published before the first await so a `stop()` on the very next tick can see it. Settled in
+        // the `finally`, after any self-undo, so waiting on it means the step owns nothing any more.
+        const settle = deferred();
+        this.running = { step, settled: settle.promise };
+        try {
+            await this.runStep(generation, step, code, run);
+        }
+        finally {
+            if (this.running?.settled === settle.promise)
+                this.running = null;
+            settle.resolve();
+        }
+    }
+    /** The step body itself. Split out so [step] can publish and settle {@link running} around it. */
+    async runStep(generation, step, code, run) {
+        softapTrace("softap_step_begin", { step });
+        const startedAt = Date.now();
+        this.stepStartedAt.set(step, startedAt);
+        this.setStep(step, { status: "running", error: undefined });
+        const report = (detail) => this.note(generation, step, detail);
+        try {
+            await run(report);
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            softapTraceFailure("softap_step_failed", { step, code, reason });
+            if (generation === this.generation) {
+                this.setStep(step, { status: "failed", error: reason, durationMs: Date.now() - startedAt });
+            }
+            throw new SoftapCallError(step, code, error instanceof Error ? error.message : `${step} failed`, error);
+        }
+        if (generation !== this.generation) {
+            // The step succeeded after the caller gave up. Release it here rather than recording it for
+            // the teardown to find: that teardown may already have walked past this step, or finished
+            // altogether, in which case nothing else ever would. This is the leak the generation guard
+            // exists to close — a meeting joined a few milliseconds after the user left.
+            softapTrace("softap_step_completed_after_cancel", { step });
+            await this.undoSafely(step);
+            throw new SoftapCallError(step, "CANCELLED", `SoftAP call was cancelled during ${step}`);
+        }
+        this.completed.push(step);
+        softapTrace("softap_step_done", { step, durationMs: Date.now() - startedAt });
+        this.setStep(step, { status: "done", durationMs: Date.now() - startedAt });
+    }
+    /** Undo that reports rather than throws, for the cancellation path where there is no caller. */
+    async undoSafely(step) {
+        try {
+            await this.undo(step);
+        }
+        catch (error) {
+            if (!this.teardownFailures.includes(step))
+                this.teardownFailures.push(step);
+            softapTraceFailure("softap_step_undo_failed", {
+                step,
+                reason: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    requireHotspot() {
+        const hotspot = this.hotspot;
+        if (!hotspot)
+            throw new SoftapCallError("hotspot", "HOTSPOT_FAILED", "no hotspot credentials");
+        return hotspot;
+    }
+    requireIngestUrl() {
+        const url = this.ingestUrl;
+        if (!url)
+            throw new SoftapCallError("acsJoin", "ACS_JOIN_FAILED", "no ingest URL");
+        return url;
+    }
+}
+/**
+ * Binds the sequence to the real subsystems.
+ *
+ * Kept separate from the class so the ordering above is tested against fakes rather than against
+ * BLE and ACS. The only logic here is adapting shapes; anything that needs a decision belongs in
+ * the class.
+ *
+ * @param packageName the miniapp that owns the call
+ * @param meeting the meeting to join, and how to observe its media health
+ */
+export function createSoftapCallDeps(args) {
+    const { packageName, subsystems } = args;
+    const hotspotBroadcastWaitMs = args.hotspotBroadcastWaitMs ?? HOTSPOT_BROADCAST_WAIT_MS;
+    return {
+        startHotspot: async (report) => {
+            const enable = async () => {
+                const status = await subsystems.setHotspotState(true);
+                if (status.state !== "enabled" || !status.ssid) {
+                    throw new Error(`the glasses hotspot did not start (state=${status.state})`);
+                }
+                if (!status.password) {
+                    throw new Error("the glasses hotspot reported no password");
+                }
+                report?.(`Glasses report hotspot ${status.ssid} enabled`);
+                return { ssid: status.ssid, passphrase: status.password };
+            };
+            try {
+                return await enable();
+            }
+            catch (error) {
+                if (error instanceof Error && /no password/.test(error.message))
+                    throw error;
+                // Cancel-then-start races the previous disable: the glasses report disabled (or no SSID)
+                // and the UI said "Couldn't start glasses hotspot" before step 2 ran on a leftover AP.
+                softapTraceFailure("hotspot_enable_retry", {
+                    reason: error instanceof Error ? error.message : String(error),
+                });
+                report?.("Glasses hotspot did not start; turning it off and trying again");
+                await subsystems.setHotspotState(false);
+                if (hotspotBroadcastWaitMs > 0) {
+                    await new Promise(resolve => setTimeout(resolve, Math.min(1_000, hotspotBroadcastWaitMs)));
+                }
+                return await enable();
+            }
+        },
+        waitUntilHotspotJoinable: async (report) => {
+            if (hotspotBroadcastWaitMs <= 0)
+                return;
+            softapTrace("hotspot_broadcast_wait", { ms: hotspotBroadcastWaitMs });
+            report?.(`Giving the hotspot ${Math.round(hotspotBroadcastWaitMs / 1000)}s to start broadcasting`);
+            await new Promise(resolve => setTimeout(resolve, hotspotBroadcastWaitMs));
+        },
+        stopHotspot: async () => {
+            await subsystems.setHotspotState(false);
+        },
+        joinScopedNetwork: async (ssid, passphrase, report) => {
+            const joinOnce = (nextSsid, nextPassphrase) => subsystems.joinScopedNetwork(nextSsid, nextPassphrase);
+            let address;
+            try {
+                address = await joinOnce(ssid, passphrase);
+            }
+            catch (error) {
+                if (!isScopedJoinUnavailable(error))
+                    throw error;
+                // First specifier left the phone's previous Wi-Fi and assoc-rejected the glasses AP.
+                // Cycle the AP and join again from an idle STA — the radio is free now.
+                softapTraceFailure("scoped_join_unavailable_retry", { ssid });
+                report?.("Phone couldn't join; cycling the glasses hotspot and trying again");
+                await subsystems.setHotspotState(false);
+                const status = await subsystems.setHotspotState(true);
+                if (status.state !== "enabled" || !status.ssid || !status.password)
+                    throw error;
+                if (hotspotBroadcastWaitMs > 0) {
+                    report?.(`Giving the hotspot ${Math.round(hotspotBroadcastWaitMs / 1000)}s to start broadcasting`);
+                    await new Promise(resolve => setTimeout(resolve, hotspotBroadcastWaitMs));
+                }
+                address = await joinOnce(status.ssid, status.password);
+            }
+            if (subsystems.probeGateway) {
+                report?.(`Phone is ${address ?? "on the hotspot"}; checking it can reach the glasses`);
+                try {
+                    const probe = await subsystems.probeGateway();
+                    softapTrace(probe.reachable ? "gateway_probe_ok" : "gateway_probe_failed", { detail: probe.detail });
+                    report?.(probe.reachable
+                        ? `Phone ${address ?? ""} ↔ glasses OK (${probe.detail})`
+                        : `Phone ${address ?? ""} joined, but cannot reach the glasses: ${probe.detail}`);
+                }
+                catch (error) {
+                    softapTraceFailure("gateway_probe_threw", {
+                        reason: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+            return address;
+        },
+        leaveScopedNetwork: () => subsystems.leaveScopedNetwork(),
+        joinMeeting: async ({ ssid, passphrase, bindAddress }, report) => {
+            // The hotspot join just took this phone off Wi-Fi, so the route Teams needs is whatever
+            // Android promoted in its place. Waiting for it to validate is what stopped the ACS join
+            // from burning its whole timeout on DNS that could not resolve yet.
+            if (subsystems.awaitValidatedDefaultNetwork) {
+                report?.("Waiting for this phone's mobile data to take over so Teams can connect");
+                try {
+                    const network = await subsystems.awaitValidatedDefaultNetwork();
+                    if (network) {
+                        softapTrace(network.usable ? "default_network_ok" : "default_network_unvalidated", {
+                            detail: network.detail,
+                        });
+                        report?.(network.usable
+                            ? `Internet is on ${network.detail}`
+                            : `Internet is not confirmed yet (${network.detail}); joining Teams anyway`);
+                    }
+                }
+                catch (error) {
+                    softapTraceFailure("default_network_check_threw", {
+                        reason: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+            report?.("Binding the video receiver and joining Teams over cellular");
+            await subsystems.joinMeeting(packageName, {
+                meetingUrl: args.meetingUrl,
+                token: args.token,
+                videoSource: { type: "softap", ssid, passphrase, bindAddress },
+                displayName: args.displayName,
+            });
+            // The listener binds during the join, so the URL only exists now.
+            return { ingestUrl: subsystems.ingestUrl() ?? "" };
+        },
+        leaveMeeting: () => subsystems.leaveMeeting(packageName),
+        ...(subsystems.endMeeting ? { endMeeting: () => subsystems.endMeeting(packageName) } : {}),
+        startPublishing: async ({ ingestUrl, traceId }, report) => {
+            // Narrate the glasses side while the BLE start command is in flight. `initializing` means
+            // the glasses accepted the command and are opening the camera; `streaming` means the WHIP
+            // offer was answered and ICE connected; anything else is the reason it did not.
+            const unsubscribe = subsystems.onGlassesStreamStatus?.((event) => {
+                if (event.status === "initializing") {
+                    report?.("Glasses accepted the command: camera starting, gathering ICE, posting offer to the phone");
+                }
+                else if (event.status === "streaming") {
+                    report?.("Glasses are streaming to the phone");
+                }
+                else if (event.status === "error") {
+                    report?.(`Glasses reported: ${event.error ?? event.reason ?? "stream error"}`);
+                }
+                else if (event.status === "reconnecting") {
+                    report?.(`Glasses reconnecting: ${event.reason ?? ""}`);
+                }
+            });
+            // Decided before the command goes out, never after: the glasses cannot drop an audio track
+            // they already negotiated, and two live copies of the wearer's voice in one call is worse
+            // than either one alone.
+            const lc3Uplink = subsystems.glassesLc3Uplink?.() ?? false;
+            softapTrace("publish_audio_decision", { captureAudio: !lc3Uplink, micTransport: lc3Uplink ? "ble-lc3" : "whip" });
+            report?.(lc3Uplink
+                ? "Publishing video only; the wearer's voice comes over Bluetooth LC3"
+                : "Publishing video and the glasses microphone");
+            try {
+                await subsystems.startPublishing(packageName, {
+                    streamUrl: ingestUrl,
+                    // Empty STUN server means host-only: there is no route from the hotspot to a STUN server,
+                    // so a configured one would add doomed gathering to every call.
+                    ice: { stun: "" },
+                    traceId,
+                    captureAudio: !lc3Uplink,
+                });
+            }
+            finally {
+                unsubscribe?.();
+            }
+        },
+        stopPublishing: () => subsystems.stopPublishing(packageName),
+        awaitFirstFrame: args.awaitFirstFrame,
+    };
+}
+//# sourceMappingURL=SoftapCallTransport.js.map