@joewinke/jatui 0.58.0 → 0.60.0

package/dist/ambience/shared.js

@@ -0,0 +1,744 @@
+/**
+ * The cross-tab shared player (jatui-lm1mf): exactly ONE tab owns the
+ * AudioContext and plays; every other tab is a REMOTE that renders the same
+ * live state and sends commands. Open MOS in ten tabs and the tab playing
+ * ambience is no longer unfindable — any tab's rail toggle shows and controls
+ * the one that's sounding.
+ *
+ * Leader election:
+ *   - Web Locks API (`navigator.locks.request(lockName)`) when available —
+ *     the lock IS the leadership, so the browser guarantees mutual exclusion.
+ *   - Fallback (no Web Locks): a BroadcastChannel heartbeat. The leader
+ *     heartbeats every HEARTBEAT_MS; a tab that hears no beat for STALE_MS
+ *     may claim, guarded by a short window in which a live leader reasserts.
+ *
+ * Transport (always BroadcastChannel 'jatui:ambience'):
+ *   - `state` / `heartbeat` — the leader publishes the live shared state
+ *     (playing scape, volume, muted, track attribution, its tab id).
+ *   - `cmd` — a remote tells the leader to stop / pause / resume / skip / go
+ *     back / setVolume / toggleMute / play (play only when the fallback
+ *     election defers to a live leader).
+ *   - `want` / `claim` — the heartbeat election.
+ *   - `gone` — the leader's pagehide: remotes immediately mark the leader
+ *     gone (playback stops — never a surprise autoplay in a background tab).
+ *
+ * Starting a scape in tab B while tab A plays makes B the leader: with
+ * Web Locks, B's user-gesture play STEALS the lock, A's held request promise
+ * rejects (AbortError) and A fades out — never two tabs audible. Playlist
+ * scapes hand over their track position (published by the leader, applied
+ * by the new leader via PlaylistScape.startAt).
+ *
+ * Resuming after the leader tab closes/reloads: playback is stopped and no
+ * remote autoplays; pressing play (the toggle's existing button — a user
+ * gesture, satisfying the autoplay policy) claims leadership and plays.
+ *
+ * Volume and mute persist in localStorage (shared by all tabs of the
+ * origin). The `storage` event is deliberately NOT the transport — it skips
+ * the writer tab; BroadcastChannel delivers to every OTHER tab.
+ *
+ * NO UI here. Hosts get everything through createAmbience({ shared: true }) —
+ * the Ambience interface is unchanged, so AmbienceToggle needs no structural
+ * changes beyond reading the shared now-playing line.
+ */
+import { createAmbience as createLocalEngine } from './engine';
+import { isPlaylistScape } from './scapes/playlist';
+import { loadPersisted, savePersisted } from './persist';
+/** BroadcastChannel name — the ambience control channel for the origin. */
+export const AMBIENCE_CHANNEL = 'jatui:ambience';
+/** Web Locks lock name — holding it IS being the leader. */
+export const AMBIENCE_LOCK = 'jatui:ambience:leader';
+export const SHARED_TIMING = Object.freeze({
+    /** Leader heartbeat (ms) — also the fallback-election liveness proof. */
+    HEARTBEAT_MS: 1000,
+    /** A leader silent this long (ms) counts as gone. */
+    STALE_MS: 3000,
+    /** After broadcasting `claim`, wait this long (ms) for a live leader's
+     *  heartbeat reassert before taking over. */
+    CLAIM_GUARD_MS: 300,
+    /** A remote play command waits this long (ms) for the leader's echo. */
+    REMOTE_PLAY_TIMEOUT_MS: 2500
+});
+function randomTabId() {
+    try {
+        return `tab-${crypto.randomUUID?.() ?? Math.random().toString(36).slice(2)}`;
+    }
+    catch {
+        return `tab-${Math.random().toString(36).slice(2)}`;
+    }
+}
+/** The browser truth for a local user gesture (mirrors engine.ts default). */
+function defaultGesture() {
+    const nav = typeof navigator !== 'undefined' ? navigator : undefined;
+    return nav?.userActivation ? nav.userActivation.isActive : true;
+}
+/**
+ * Build a shared (cross-tab) ambience engine. Every tab runs one; only the
+ * leader's local engine ever sounds. See the module doc for the protocol.
+ */
+export function createSharedAmbience(options = {}) {
+    const channelName = options.channelName ?? AMBIENCE_CHANNEL;
+    const lockName = options.lockName ?? AMBIENCE_LOCK;
+    const tabId = options.tabId ?? randomTabId();
+    const heartbeatMs = options.heartbeatMs ?? SHARED_TIMING.HEARTBEAT_MS;
+    const staleMs = options.staleMs ?? SHARED_TIMING.STALE_MS;
+    const storageKey = options.storageKey ?? 'jatui:ambience';
+    // A remote command carries the ORIGINATING tab's gesture, not this one's —
+    // the leader must be allowed to apply it (its context, if running, needs
+    // no new activation; if it can't start, the play just fails loudly).
+    let remoteCommand = false;
+    const gestureProbe = () => remoteCommand ? true : options.isGesture ? options.isGesture() : defaultGesture();
+    const local = createLocalEngine({ ...options, isGesture: gestureProbe });
+    const createChannel = options.createChannel ??
+        ((name) => typeof BroadcastChannel !== 'undefined' ? new BroadcastChannel(name) : null);
+    const locks = 'locks' in options ? (options.locks ?? null) : defaultLocks();
+    function defaultLocks() {
+        const nav = typeof navigator !== 'undefined' ? navigator : undefined;
+        return nav && typeof nav.locks?.request === 'function' ? nav.locks : null;
+    }
+    const bc = createChannel(channelName);
+    if (bc)
+        bc.onmessage = (e) => {
+            const msg = e.data;
+            if (msg && (msg.t === 'heartbeat' || msg.t === 'state' || msg.t === 'claim'))
+                lastBeatTab = msg.from;
+            onMsg(msg);
+        };
+    // --- state ---------------------------------------------------------------
+    const persisted = loadPersisted(storageKey);
+    /** The user's volume — independent of mute (the engine runs 0 while muted). */
+    let userVolume = Math.min(1, Math.max(0, persisted.volume ?? 0.6));
+    let muted = persisted.muted ?? false;
+    let role = 'unknown';
+    let leaderGone = false;
+    /** Last state published by a leader (remotes only). */
+    let remoteS = null;
+    let lastBeatAt = 0;
+    /** The leader's now-playing line, published via setNowPlaying. */
+    let nowPlaying = null;
+    let nowPlayingIndex = null;
+    /** Structured now-playing parts published alongside the line (jatui-153tz). */
+    let nowPlayingTitle = null;
+    let nowPlayingPosition = null;
+    let nowPlayingDuration = null;
+    const ambienceSubs = new Set();
+    const sharedSubs = new Set();
+    function sharedState() {
+        const st = local.state;
+        return {
+            currentId: role === 'leader' ? st.currentId : (remoteS?.currentId ?? st.currentId),
+            playing: role === 'leader' ? st.playing : (remoteS?.playing ?? false),
+            paused: role === 'leader' ? st.paused : (remoteS?.paused ?? false),
+            volume: userVolume,
+            muted,
+            role,
+            leaderTabId: role === 'leader' ? tabId : (remoteS?.leaderTabId ?? null),
+            leaderGone: role === 'leader' ? false : leaderGone,
+            nowPlaying: role === 'leader' ? nowPlaying : (remoteS?.nowPlaying ?? null),
+            trackIndex: role === 'leader' ? nowPlayingIndex : (remoteS?.trackIndex ?? null),
+            trackTitle: role === 'leader' ? nowPlayingTitle : (remoteS?.trackTitle ?? null),
+            trackPosition: role === 'leader' ? nowPlayingPosition : (remoteS?.trackPosition ?? null),
+            trackDuration: role === 'leader' ? nowPlayingDuration : (remoteS?.trackDuration ?? null)
+        };
+    }
+    function ambienceState() {
+        const s = sharedState();
+        return {
+            currentId: s.currentId,
+            playing: s.playing && !s.leaderGone,
+            paused: s.paused,
+            volume: s.volume
+        };
+    }
+    function emitShared() {
+        const s = sharedState();
+        for (const fn of sharedSubs)
+            fn(s);
+        const a = ambienceState();
+        for (const fn of ambienceSubs)
+            fn(a);
+    }
+    // --- transport -----------------------------------------------------------
+    function post(msg) {
+        try {
+            bc?.postMessage(msg);
+        }
+        catch {
+            /* a closed/detached channel must not take the engine down */
+        }
+    }
+    function publish() {
+        if (role !== 'leader')
+            return;
+        post({ t: 'state', from: tabId, s: sharedState() });
+    }
+    // --- leadership ----------------------------------------------------------
+    /** Rejects when the lock is stolen (Web Locks) or resolved on resign. */
+    let lostReject = null;
+    const lost = new Promise((_res, rej) => {
+        lostReject = rej;
+    });
+    lost.catch(() => { }); // never an unhandled rejection
+    let heartbeatTimer = null;
+    function becomeLeader(how) {
+        role = 'leader';
+        leaderGone = false;
+        remoteS = null;
+        // Apply the muted state the (fresh) engine can't know about yet.
+        if (muted)
+            local.setVolume(0);
+        else
+            local.setVolume(userVolume);
+        publish();
+        emitShared();
+        if (heartbeatTimer)
+            clearInterval(heartbeatTimer);
+        heartbeatTimer = setInterval(() => {
+            post({ t: 'heartbeat', from: tabId, s: sharedState() });
+        }, heartbeatMs);
+        post({ t: 'heartbeat', from: tabId, s: sharedState() });
+    }
+    function resign(reason) {
+        if (role !== 'leader')
+            return;
+        role = 'remote';
+        nowPlaying = null;
+        nowPlayingIndex = null;
+        nowPlayingTitle = null;
+        nowPlayingPosition = null;
+        nowPlayingDuration = null;
+        remoteS = null;
+        if (heartbeatTimer) {
+            clearInterval(heartbeatTimer);
+            heartbeatTimer = null;
+        }
+        // The audio must not outlive the leadership — fade out, close as usual.
+        local.stop();
+        lostReject?.(new Error(`lost leadership: ${reason}`));
+        emitShared();
+    }
+    /** Initial election: hold the lock if it's free, else be a remote. */
+    function elect() {
+        if (!locks) {
+            heartbeatElection();
+            return;
+        }
+        void locks
+            .request(lockName, { ifAvailable: true }, (lock) => {
+            if (!lock) {
+                role = 'remote';
+                emitShared();
+                return;
+            }
+            becomeLeader('lock');
+            return lost; // hold until stolen or destroyed
+        })
+            .then(() => {
+            // Settled = the lock was released (stolen) or never held.
+            if (role === 'leader')
+                resign('lock-lost');
+        })
+            .catch(() => {
+            if (role === 'leader')
+                resign('lock-lost');
+        });
+    }
+    // --- heartbeat fallback election (no Web Locks) ---------------------------
+    /** Deterministic tie-break: the lexicographically SMALLEST tabId wins.
+     *  On a `want` from a bigger tab we claim at once; from a smaller one we
+     *  defer and let it win. */
+    function smaller(other) {
+        return other < tabId;
+    }
+    function heartbeatElection() {
+        post({ t: 'want', from: tabId });
+        setTimeout(() => {
+            if (role !== 'unknown')
+                return; // a leader made itself known in time
+            becomeLeader('fallback');
+            post({ t: 'claim', from: tabId, s: sharedState() });
+        }, SHARED_TIMING.CLAIM_GUARD_MS);
+    }
+    /** A remote (or a leaderless stale tab) claims leadership — Web Locks path.
+     *  Steal is always granted; the previous leader's held promise rejects and
+     *  it fades out inside its own resign(). */
+    function claimWithLocks() {
+        return new Promise((resolve) => {
+            let decided = false;
+            const decide = (v) => {
+                if (!decided) {
+                    decided = true;
+                    resolve(v);
+                }
+            };
+            void locks
+                .request(lockName, { steal: true }, (lock) => {
+                if (lock) {
+                    becomeLeader('steal');
+                    decide(true);
+                    return lost; // hold until stolen again or destroyed
+                }
+                decide(false);
+            })
+                .then(() => {
+                if (role === 'leader')
+                    resign('lock-lost');
+            }, () => {
+                if (role === 'leader')
+                    resign('lock-lost');
+            });
+            // Web Locks grants steal promptly; a missed grant resolves false.
+            setTimeout(() => decide(false), 1000);
+        });
+    }
+    /** Claim via the heartbeat election: broadcast `claim`, back off if a live
+     *  leader reasserts within the guard window (or a SMALLER tab claims — the
+     *  tie-break), else take over. */
+    function claimWithHeartbeat() {
+        return new Promise((resolve) => {
+            let leaderSeen = false;
+            const guard = (e) => {
+                if ((e.t === 'heartbeat' || e.t === 'state' || (e.t === 'claim' && smaller(e.from))) &&
+                    e.from !== tabId)
+                    leaderSeen = true;
+            };
+            const prevOnMessage = bc?.onmessage ?? null;
+            if (bc)
+                bc.onmessage = (e) => guard(e.data);
+            post({ t: 'claim', from: tabId, s: sharedState() });
+            setTimeout(() => {
+                if (bc)
+                    bc.onmessage = prevOnMessage;
+                if (leaderSeen) {
+                    role = 'remote'; // a live leader asserted itself
+                    emitShared();
+                    resolve(false);
+                }
+                else {
+                    becomeLeader('fallback');
+                    post({ t: 'claim', from: tabId, s: sharedState() });
+                    resolve(true);
+                }
+            }, SHARED_TIMING.CLAIM_GUARD_MS);
+        });
+    }
+    async function claim() {
+        if (role === 'leader')
+            return true;
+        // A remote whose leader is ALIVE must not steal it (Web Locks steal is
+        // unconditional) — deferring is the fallback election's job. With locks,
+        // play() in a remote always takes over (task spec: tab B starting a
+        // scape becomes the leader).
+        if (locks)
+            return claimWithLocks();
+        if (role === 'remote' && !leaderGone && Date.now() - lastBeatAt < staleMs)
+            return false; // live leader — play via command instead
+        return claimWithHeartbeat();
+    }
+    // --- remote play waiter ----------------------------------------------------
+    const playWaiters = new Set();
+    function waitRemotePlay(id) {
+        return new Promise((resolve, reject) => {
+            const w = { id, resolve, reject };
+            playWaiters.add(w);
+            setTimeout(() => {
+                if (playWaiters.delete(w))
+                    reject(new Error(`The tab playing ambience did not start "${id}"`));
+            }, SHARED_TIMING.REMOTE_PLAY_TIMEOUT_MS);
+        });
+    }
+    // --- messages --------------------------------------------------------------
+    function onMsg(msg) {
+        if (!msg || typeof msg !== 'object' || msg.from === tabId)
+            return;
+        switch (msg.t) {
+            case 'state':
+            case 'heartbeat': {
+                lastBeatAt = Date.now();
+                const was = JSON.stringify(remoteS);
+                remoteS = msg.s;
+                leaderGone = false;
+                if (role === 'unknown')
+                    role = 'remote';
+                if (JSON.stringify(remoteS) !== was)
+                    emitShared();
+                break;
+            }
+            case 'claim': {
+                lastBeatAt = Date.now();
+                // A live leader reasserts immediately so a racing claim backs off.
+                if (role === 'leader') {
+                    post({ t: 'heartbeat', from: tabId, s: sharedState() });
+                }
+                else if (role === 'unknown') {
+                    // Tie-break: a claim from a bigger tab loses to ours; from a
+                    // smaller one it wins — we defer and mirror its state.
+                    if (smaller(msg.from)) {
+                        remoteS = msg.s;
+                        role = 'remote';
+                        emitShared();
+                    }
+                    else {
+                        becomeLeader('fallback');
+                        post({ t: 'claim', from: tabId, s: sharedState() });
+                    }
+                }
+                else {
+                    remoteS = msg.s;
+                    emitShared();
+                }
+                break;
+            }
+            case 'want': {
+                // A live leader answers at once; an unknown tab resolves the tie
+                // deterministically (smallest tabId claims, bigger one defers).
+                if (role === 'leader') {
+                    post({ t: 'heartbeat', from: tabId, s: sharedState() });
+                }
+                else if (role === 'unknown' && !smaller(msg.from)) {
+                    becomeLeader('fallback');
+                    post({ t: 'claim', from: tabId, s: sharedState() });
+                }
+                break;
+            }
+            case 'gone': {
+                // The leader tab is closing: mark it gone at once — no staleness
+                // wait, and never a surprise autoplay in a background tab.
+                if (remoteS && (remoteS.leaderTabId === msg.from || lastBeatTab === msg.from)) {
+                    remoteS = { ...remoteS, playing: false, paused: false, nowPlaying: null };
+                    leaderGone = true;
+                    emitShared();
+                }
+                break;
+            }
+            case 'cmd': {
+                if (role !== 'leader')
+                    return;
+                switch (msg.cmd) {
+                    case 'stop':
+                        local.stop();
+                        break;
+                    case 'pause':
+                        local.pause();
+                        break;
+                    case 'resume':
+                        remoteCommand = true;
+                        local
+                            .resume()
+                            .catch(() => {
+                            if (role === 'leader')
+                                publish();
+                        })
+                            .finally(() => {
+                            remoteCommand = false;
+                        });
+                        break;
+                    case 'skip':
+                    case 'prev': {
+                        // The now-playing row's transport (jatui-153tz): routed to the
+                        // leader's own playlist scape instance.
+                        if (!msg.id)
+                            return;
+                        const p = playlistFor(msg.id);
+                        if (msg.cmd === 'skip')
+                            p?.skip();
+                        else
+                            p?.prev();
+                        break;
+                    }
+                    case 'setVolume':
+                        applyVolume(msg.arg ?? userVolume);
+                        break;
+                    case 'toggleMute':
+                        muted = !muted;
+                        applyVolume(userVolume);
+                        savePersisted(storageKey, { volume: userVolume, muted, lastScape: local.state.currentId ?? undefined });
+                        publish();
+                        emitShared();
+                        break;
+                    case 'play': {
+                        if (!msg.id)
+                            return;
+                        remoteCommand = true;
+                        void local
+                            .play(msg.id)
+                            .catch(() => {
+                            // The leader could not start it (e.g. suspended context,
+                            // unknown scape) — publish the unchanged state so the
+                            // remote's waiter times out and shows the failure.
+                            publish();
+                        })
+                            .finally(() => {
+                            remoteCommand = false;
+                        });
+                        break;
+                    }
+                }
+                break;
+            }
+        }
+    }
+    /** Which tab last asserted itself (heartbeat/state/claim) — a `gone` from
+     *  it is acted on. */
+    let lastBeatTab = null;
+    // --- watchdog: heartbeat silence marks the leader gone ---------------------
+    const watchdog = setInterval(() => {
+        if (role === 'leader')
+            return;
+        if (remoteS?.playing &&
+            lastBeatAt > 0 &&
+            Date.now() - lastBeatAt > staleMs) {
+            remoteS = { ...remoteS, playing: false, paused: false, nowPlaying: null };
+            leaderGone = true;
+            emitShared();
+        }
+    }, 500);
+    // --- local engine wiring ---------------------------------------------------
+    local.subscribe(() => {
+        if (role === 'leader')
+            publish();
+        emitShared();
+    });
+    // Resolve remote play waiters whenever the shared state flips to playing:
+    // hook emitShared (the shared-state notify) to also drain them.
+    const notifyWaiters = (s) => {
+        if (!s.playing || !s.currentId)
+            return;
+        for (const w of [...playWaiters]) {
+            if (w.id === s.currentId) {
+                playWaiters.delete(w);
+                w.resolve();
+            }
+        }
+    };
+    const emitSharedBase = emitShared;
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    emitShared = () => {
+        emitSharedBase();
+        notifyWaiters(sharedState());
+    };
+    // --- pagehide: announce our own death ---------------------------------------
+    function onPageHide() {
+        if (role === 'leader')
+            post({ t: 'gone', from: tabId });
+    }
+    if (typeof window !== 'undefined' && typeof window.addEventListener === 'function') {
+        window.addEventListener('pagehide', onPageHide);
+    }
+    // --- engine operations -------------------------------------------------------
+    function applyVolume(v) {
+        userVolume = Math.min(1, Math.max(0, v));
+        local.setVolume(muted ? 0 : userVolume);
+    }
+    /** Find a registered playlist scape for position handover. */
+    function playlistFor(id) {
+        const item = local.items().find((i) => i.id === id);
+        return item && isPlaylistScape(item) ? item : null;
+    }
+    async function play(id) {
+        if (role === 'leader')
+            return local.play(id);
+        // Starting a scape in a remote takes the leadership over (task spec) —
+        // a Web Locks steal runs inside THIS user gesture, the old leader fades
+        // out, never two tabs audible.
+        const tookOver = await claim();
+        if (tookOver) {
+            // Playlist position handover: the same scape, previously playing in
+            // the old leader, resumes at that track — fresh, not from zero.
+            const s = remoteS;
+            const handover = !!s && s.currentId === id && s.playing === true && s.trackIndex != null && s.trackIndex >= 0;
+            remoteS = null;
+            const p = local.play(id);
+            if (handover) {
+                const scape = playlistFor(id);
+                try {
+                    scape?.startAt(s.trackIndex);
+                }
+                catch {
+                    /* position handover is best-effort */
+                }
+            }
+            return p;
+        }
+        // Live leader (heartbeat fallback): send the command and wait for the echo.
+        post({ t: 'cmd', cmd: 'play', id, from: tabId });
+        return waitRemotePlay(id);
+    }
+    function stop() {
+        if (role === 'leader') {
+            local.stop(); // publish happens via the engine subscription
+            return;
+        }
+        post({ t: 'cmd', cmd: 'stop', from: tabId });
+        // Optimistic: the leader echoes the authoritative state right after.
+        if (remoteS)
+            remoteS = { ...remoteS, playing: false, paused: false, nowPlaying: null };
+        emitShared();
+    }
+    /** Freeze in place (the scape is not torn down; a playlist keeps its track
+     *  position). Leader-side it pauses the local engine; a remote asks the
+     *  leader to — the echo of the authoritative state follows. */
+    function pause() {
+        if (role === 'leader') {
+            local.pause(); // publish happens via the engine subscription
+            return;
+        }
+        post({ t: 'cmd', cmd: 'pause', from: tabId });
+        if (remoteS)
+            remoteS = { ...remoteS, playing: false, paused: true };
+        emitShared();
+    }
+    /** Continue a paused scape. No-op when nothing is paused. */
+    async function resume() {
+        if (role === 'leader') {
+            await local.resume().catch(() => {
+                if (role === 'leader')
+                    publish();
+            });
+            return;
+        }
+        post({ t: 'cmd', cmd: 'resume', from: tabId });
+        if (remoteS)
+            remoteS = { ...remoteS, playing: true, paused: false };
+        emitShared();
+    }
+    /** Transport for the now-playing row (jatui-153tz): skip to the next track
+     *  (or go back one) on a playlist scape — routed to the leader's live
+     *  instance when this tab is a remote. */
+    function skipTrack(id) {
+        if (role === 'leader') {
+            playlistFor(id)?.skip();
+            return;
+        }
+        post({ t: 'cmd', cmd: 'skip', id, from: tabId });
+    }
+    function prevTrack(id) {
+        if (role === 'leader') {
+            playlistFor(id)?.prev();
+            return;
+        }
+        post({ t: 'cmd', cmd: 'prev', id, from: tabId });
+    }
+    function setVolume(v) {
+        applyVolume(v);
+        savePersisted(storageKey, {
+            volume: userVolume,
+            muted,
+            lastScape: local.state.currentId ?? undefined
+        });
+        if (role === 'leader')
+            publish();
+        else
+            post({ t: 'cmd', cmd: 'setVolume', arg: userVolume, from: tabId });
+        emitShared();
+    }
+    function setMuted(m) {
+        if (m === muted)
+            return;
+        muted = m;
+        local.setVolume(muted ? 0 : userVolume);
+        savePersisted(storageKey, {
+            volume: userVolume,
+            muted,
+            lastScape: local.state.currentId ?? undefined
+        });
+        if (role === 'leader')
+            publish();
+        else
+            post({ t: 'cmd', cmd: 'toggleMute', from: tabId });
+        emitShared();
+    }
+    function toggleMute() {
+        setMuted(!muted);
+    }
+    function destroy() {
+        onPageHide();
+        if (role === 'leader')
+            resign('destroy');
+        else
+            role = 'remote';
+        clearInterval(watchdog);
+        if (heartbeatTimer) {
+            clearInterval(heartbeatTimer);
+            heartbeatTimer = null;
+        }
+        if (role === 'leader')
+            local.kill();
+        local.stop();
+        if (bc) {
+            bc.onmessage = null;
+            try {
+                bc.close();
+            }
+            catch {
+                /* already closed */
+            }
+        }
+    }
+    // Elect on the next microtask so the constructor returns synchronously.
+    elect();
+    return {
+        register: (item) => local.register(item),
+        list: () => local.list(),
+        items: () => local.items(),
+        groups: () => local.groups(),
+        play,
+        stop,
+        pause,
+        resume,
+        skipTrack,
+        prevTrack,
+        kill: () => {
+            // A remote has nothing local to kill — tell the leader instead.
+            if (role === 'leader')
+                local.kill();
+            else
+                post({ t: 'cmd', cmd: 'stop', from: tabId });
+        },
+        setVolume,
+        setMuted,
+        toggleMute,
+        setNowPlaying(line, index, position, duration, title) {
+            nowPlaying = line;
+            nowPlayingIndex = line ? (index ?? null) : null;
+            nowPlayingPosition = line ? (position ?? null) : null;
+            nowPlayingDuration = line ? (duration ?? null) : null;
+            nowPlayingTitle = line ? (title ?? null) : null;
+            if (role === 'leader') {
+                publish();
+                emitShared();
+            }
+        },
+        get state() {
+            return ambienceState();
+        },
+        get sharedState() {
+            return sharedState();
+        },
+        subscribe(fn) {
+            ambienceSubs.add(fn);
+            fn(ambienceState());
+            return () => ambienceSubs.delete(fn);
+        },
+        subscribeShared(fn) {
+            sharedSubs.add(fn);
+            fn(sharedState());
+            return () => sharedSubs.delete(fn);
+        },
+        onBreath: (fn) => local.onBreath(fn),
+        destroy
+    };
+}
+/** createAmbience() with the `shared` opt-in (jatui-lm1mf): identical to the
+ *  plain engine until a host passes `{ shared: true }`, which makes playback
+ *  cross-tab — one leader, all other tabs remotes. Hosts keep the exact
+ *  Ambience interface (AmbienceToggle needs no changes beyond reading the
+ *  shared now-playing line). */
+export function createAmbience(options = {}) {
+    return options.shared ? createSharedAmbience(options) : createLocalEngine(options);
+}
+/** The always-local engine factory — the barrel's `createAmbienceLocal`.
+ *  The ambience barrel has re-exported this name since the shared player
+ *  landed (jatui-lm1mf), but shared.ts never defined it: real ESM (the built
+ *  dist, Node) failed to import the subpath at all (jatui-153tz rebuild). It
+ *  is the plain engine: `shared` is never honored, whatever the options. */
+export const createAmbienceLocal = createLocalEngine;