@joewinke/jatui 0.58.0 → 0.59.0

package/dist/ambience/default.d.ts

@@ -6,5 +6,8 @@ export interface DefaultAmbienceOptions {
     storageKey?: string;
     /** Menu section order/labels, passed through to `createAmbience`. */
     groups?: AmbienceOptions['groups'];
+    /** Cross-tab shared player (jatui-lm1mf): one tab plays, every other tab
+     *  is a remote showing the same live state. */
+    shared?: boolean;
 }
 export declare function createDefaultAmbience(options?: DefaultAmbienceOptions): Ambience;

package/dist/ambience/default.js

@@ -28,7 +28,11 @@ export const DEFAULT_SCAPES = Object.freeze([
     waves
 ]);
 export function createDefaultAmbience(options = {}) {
-    const ambience = createAmbience(options);
+    const ambience = createAmbience({
+        storageKey: options.storageKey,
+        groups: options.groups,
+        shared: options.shared
+    });
     for (const scape of DEFAULT_SCAPES)
         ambience.register(scape);
     return ambience;

package/dist/ambience/index.d.ts

@@ -9,7 +9,9 @@
  *   // inside a click handler:
  *   await ambience.play('rain');
  */
-export { createAmbience, TIMING } from './engine';
+export { createAmbience, createAmbienceLocal } from './shared';
+export { TIMING } from './engine';
+export { createSharedAmbience, AMBIENCE_CHANNEL, AMBIENCE_LOCK, SHARED_TIMING, type SharedAmbience, type SharedAmbienceState, type SharedAmbienceOptions, type SharedChannel, type SharedLockManager } from './shared';
 export { createDefaultAmbience, DEFAULT_SCAPES, type DefaultAmbienceOptions } from './default';
 export { hibiscusScape } from './scapes/hibiscus';
 export { focusScape } from './scapes/focus';

package/dist/ambience/index.js

@@ -9,7 +9,11 @@
  *   // inside a click handler:
  *   await ambience.play('rain');
  */
-export { createAmbience, TIMING } from './engine';
+// createAmbience() is the shared-aware factory (jatui-lm1mf): identical to
+// the plain engine until a host passes { shared: true }.
+export { createAmbience, createAmbienceLocal } from './shared';
+export { TIMING } from './engine';
+export { createSharedAmbience, AMBIENCE_CHANNEL, AMBIENCE_LOCK, SHARED_TIMING } from './shared';
 export { createDefaultAmbience, DEFAULT_SCAPES } from './default';
 // The shipped scapes — hosts that want a hand-picked registry import them
 // individually instead of using createDefaultAmbience().

package/dist/ambience/persist.d.ts

@@ -6,6 +6,8 @@
 export interface PersistedAmbience {
     volume?: number;
     lastScape?: string;
+    /** Cross-tab mute (jatui-lm1mf) — shared by every tab of the origin. */
+    muted?: boolean;
 }
 export declare function loadPersisted(key: string): PersistedAmbience;
 export declare function savePersisted(key: string, value: PersistedAmbience): void;

package/dist/ambience/scapes/playlist.d.ts

@@ -126,6 +126,10 @@ export interface PlaylistScape extends Scape {
     skip(): void;
     /** Toggle shuffle; the current track stays, the rest reorder at once. */
     setShuffle(on: boolean): void;
+    /** Crossfade to an absolute track index — used on leadership handover
+     *  (jatui-lm1mf) so the new leader tab resumes the position the old one
+     *  left. No-op while not playing. */
+    startAt(index: number): void;
     /** The resolved track list, or null until the manifest resolved. */
     tracks(): PlaylistTrack[] | null;
 }

package/dist/ambience/scapes/playlist.js

@@ -461,6 +461,15 @@ export function createPlaylistScape(options) {
             if (ni !== -1)
                 startTrack(ni, 'cross');
         }
+        /** Leadership handover (jatui-lm1mf): crossfade to an absolute track
+         *  index so the new leader tab picks up the position the old one left. */
+        function startAtInternal(index) {
+            if (released || !started || !resolved || order.length === 0)
+                return;
+            const ni = plainOrder(resolved.length).indexOf(Math.trunc(index));
+            if (ni !== -1 && ni !== pos)
+                startTrack(ni, 'cross');
+        }
         /** setShuffle mid-play: with shuffle the rest reorder (current first);
          *  without, the natural order resumes from the current track. */
         function reshuffle() {
@@ -482,6 +491,7 @@ export function createPlaylistScape(options) {
         return {
             api: { start, stop, setParam },
             skip: skipInternal,
+            startAt: startAtInternal,
             reshuffle,
             isReleased: () => released
         };
@@ -514,6 +524,10 @@ export function createPlaylistScape(options) {
             if (latest && !latest.isReleased())
                 latest.reshuffle();
         },
+        startAt(index) {
+            if (latest && !latest.isReleased())
+                latest.startAt(index);
+        },
         tracks: () => (resolved ? [...resolved] : null)
     };
     return scape;

package/dist/ambience/shared.d.ts

@@ -0,0 +1,97 @@
+import type { Ambience, AmbienceOptions } from './types';
+/** BroadcastChannel name — the ambience control channel for the origin. */
+export declare const AMBIENCE_CHANNEL = "jatui:ambience";
+/** Web Locks lock name — holding it IS being the leader. */
+export declare const AMBIENCE_LOCK = "jatui:ambience:leader";
+export declare const SHARED_TIMING: Readonly<{
+    /** 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;
+}>;
+/** The live cross-tab state every tab renders. */
+export interface SharedAmbienceState {
+    /** Currently playing (or preselected) scape id, or null. */
+    currentId: string | null;
+    /** True while the leader is sounding. */
+    playing: boolean;
+    /** The user's volume (0..1) — independent of mute. */
+    volume: number;
+    /** True while muted (engine runs at 0 volume; the slider keeps its value). */
+    muted: boolean;
+    /** Who owns the AudioContext right now, if known. */
+    role: 'leader' | 'remote' | 'unknown';
+    /** The leader tab's id (channel-internal, for `gone` bookkeeping). */
+    leaderTabId: string | null;
+    /** True once the leader tab is gone (pagehide or heartbeat silence):
+     *  playback has stopped; play in THIS tab claims leadership. */
+    leaderGone: boolean;
+    /** The playing track's attribution line ("Title — Composer · License"),
+     *  published by the leader; null when unknown or nothing is playing. */
+    nowPlaying: string | null;
+    /** Position of the published now-playing track in its playlist (0-based),
+     *  for leadership handover of playlist scapes. */
+    trackIndex: number | null;
+}
+/** An Ambience whose playback is shared across tabs (see module doc). */
+export interface SharedAmbience extends Ambience {
+    /** The full cross-tab state (the plain `state` getter is its Ambience subset). */
+    get sharedState(): SharedAmbienceState;
+    /** Subscribe to the full cross-tab state; fires immediately. */
+    subscribeShared(fn: (s: SharedAmbienceState) => void): () => void;
+    /** Mute without losing the volume value (persisted with it). */
+    setMuted(muted: boolean): void;
+    toggleMute(): void;
+    /** Leader-side hook: the host publishes the playing track's attribution
+     *  (and playlist position) so remote tabs show it too. */
+    setNowPlaying(line: string | null, trackIndex?: number | null): void;
+    /** Release the lock, stop the heartbeat and close the channel. The local
+     *  engine is killed if this tab was the leader. */
+    destroy(): void;
+}
+export interface SharedAmbienceOptions extends AmbienceOptions {
+    /** Override the channel name (tests, multi-host pages). */
+    channelName?: string;
+    /** Override the lock name (tests). */
+    lockName?: string;
+    /** Injectable channel constructor for tests (default: BroadcastChannel). */
+    createChannel?: (name: string) => SharedChannel | null;
+    /** Injectable Web Locks surface for tests (default: navigator.locks). */
+    locks?: SharedLockManager | null;
+    /** Injectable tab id for tests (default: random). */
+    tabId?: string;
+    heartbeatMs?: number;
+    staleMs?: number;
+}
+/** The slice of BroadcastChannel the engine needs. */
+export interface SharedChannel {
+    postMessage(message: unknown): void;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    close(): void;
+}
+/** The slice of the Web Locks API the engine needs. */
+export interface SharedLockManager {
+    request(name: string, options: {
+        mode?: 'shared' | 'exclusive';
+        ifAvailable?: boolean;
+        steal?: boolean;
+    }, callback: (lock: unknown) => unknown | Promise<unknown>): Promise<unknown>;
+}
+/**
+ * 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 declare function createSharedAmbience(options?: SharedAmbienceOptions): SharedAmbience;
+/** 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 declare function createAmbience(options?: AmbienceOptions): Ambience;

package/dist/ambience/shared.js

@@ -0,0 +1,642 @@
+/**
+ * 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 / 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;
+    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),
+            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)
+        };
+    }
+    function ambienceState() {
+        const s = sharedState();
+        return { currentId: s.currentId, playing: s.playing && !s.leaderGone, 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;
+        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, nowPlaying: null };
+                    leaderGone = true;
+                    emitShared();
+                }
+                break;
+            }
+            case 'cmd': {
+                if (role !== 'leader')
+                    return;
+                switch (msg.cmd) {
+                    case 'stop':
+                        local.stop();
+                        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, 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, nowPlaying: null };
+        emitShared();
+    }
+    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,
+        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) {
+            nowPlaying = line;
+            nowPlayingIndex = line ? (index ?? 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);
+}

package/dist/ambience/types.d.ts

@@ -121,4 +121,8 @@ export interface AmbienceOptions {
     isGesture?: () => boolean;
     /** Context factory, injectable for tests (default: `new AudioContext()`). */
     createContext?: () => AudioContextLike;
+    /** Cross-tab shared player (jatui-lm1mf): one tab (the leader) owns the
+     *  AudioContext and plays; every other tab renders the same live state and
+     *  sends commands. See `shared.ts`. */
+    shared?: boolean;
 }

package/dist/components/AmbienceToggle.svelte

@@ -201,14 +201,15 @@
 	import { isAmbienceLink, safeAmbienceHref } from '../ambience/groups';
 	import { isPlaylistScape, type PlaylistState } from '../ambience/scapes/playlist';
 	import type { Ambience, AmbienceLink, Scape } from '../ambience/types';
+	import type { SharedAmbience } from '../ambience/shared';
 
 	let {
 		engine,
 		compact = false,
 		placement = 'bottom-end'
 	}: {
-		/** The engine instance (from `createAmbience()`). The component never creates one, and never kills it — the host owns the engine's lifecycle. Section order/labels come from the engine's `groups` option. */
-		engine: Ambience;
+		/** The engine instance (from `createAmbience()`). The component never creates one, and never kills it — the host owns the engine's lifecycle. Section order/labels come from the engine's `groups` option. With the cross-tab shared player (jatui-lm1mf, `createAmbience({ shared: true })`) a plain `Ambience` is also accepted: the shared now-playing line is only read when the engine publishes one. */
+		engine: Ambience | SharedAmbience;
 		/** Smaller app-shell footprint: 40px trigger with an 18px glyph (default 44px / 20px). Never below the 40px touch floor. */
 		compact?: boolean;
 		/** Which way the menu opens from the trigger. Auto-flips vertically when the viewport has no room on that side. */
@@ -259,6 +260,10 @@
 
 	let playError = $state(false);
 	let track = $state<PlaylistState['track']>(null);
+	/** The shared player's now-playing line (jatui-lm1mf): published by the
+	 *  leader tab, so a remote tab shows the same track attribution without
+	 *  owning the playlist instance. Null on a plain engine. */
+	let sharedNow = $state<string | null>(null);
 
 	// Wheel-volume accumulator over the open surfaces (jatui-xomny): carries
 	// the pending partial notch between wheel events so trackpad pixel deltas
@@ -271,7 +276,7 @@
 	const currentLabel = $derived(currentItem?.label ?? currentId);
 	const groups = $derived(groupScapes(items, engine.groups?.()));
 	const openSection = $derived(groups.find((g) => g.group === subGroup) ?? null);
-	const trackLine = $derived(playing ? nowPlayingLine(track) : '');
+	const trackLine = $derived(playing ? (sharedNow ?? nowPlayingLine(track)) : '');
 	const liveLabel = $derived(
 		playError ? PLAY_ERROR_LABEL : ambienceLiveLabel(currentLabel, playing)
 	);
@@ -298,15 +303,33 @@
 		});
 	});
 
-	// The current scape is a playlist → follow its track for the attribution line.
+	// The shared player's published now-playing line (leader → remotes).
+	$effect(() => {
+		const e = engine as SharedAmbience;
+		if (typeof e.subscribeShared !== 'function') {
+			sharedNow = null;
+			return;
+		}
+		return e.subscribeShared((s) => {
+			sharedNow = s.nowPlaying;
+		});
+	});
+
+	// The current scape is a playlist → follow its track for the attribution line,
+	// and (leader side) publish it to the other tabs via the shared engine.
 	$effect(() => {
 		const item = currentItem;
 		if (!isPlaylistScape(item)) {
 			track = null;
+			engine.setNowPlaying?.(null);
 			return;
 		}
 		return item.subscribe((s) => {
 			track = s.status === 'playing' ? s.track : null;
+			engine.setNowPlaying?.(
+				s.status === 'playing' && s.track ? nowPlayingLine(s.track) : null,
+				s.index
+			);
 		});
 	});
 

package/dist/components/AmbienceToggle.svelte.d.ts

@@ -128,9 +128,10 @@ export declare function wheelVolumeSteps(acc: {
  */
 export declare function volumeAfterSteps(volume: number, steps: number, stepPct?: number): number;
 import type { Ambience } from '../ambience/types';
+import type { SharedAmbience } from '../ambience/shared';
 type $$ComponentProps = {
-    /** The engine instance (from `createAmbience()`). The component never creates one, and never kills it — the host owns the engine's lifecycle. Section order/labels come from the engine's `groups` option. */
-    engine: Ambience;
+    /** The engine instance (from `createAmbience()`). The component never creates one, and never kills it — the host owns the engine's lifecycle. Section order/labels come from the engine's `groups` option. With the cross-tab shared player (jatui-lm1mf, `createAmbience({ shared: true })`) a plain `Ambience` is also accepted: the shared now-playing line is only read when the engine publishes one. */
+    engine: Ambience | SharedAmbience;
     /** Smaller app-shell footprint: 40px trigger with an 18px glyph (default 44px / 20px). Never below the 40px touch floor. */
     compact?: boolean;
     /** Which way the menu opens from the trigger. Auto-flips vertically when the viewport has no room on that side. */

package/dist/index.d.ts

@@ -411,8 +411,9 @@ export { default as ImageReveal } from './components/ImageReveal.svelte';
 export { imageRevealPhase, imageRevealBusy, imageRevealInitials, imageRevealSize, imageRevealTone, IMAGE_REVEAL_SIZES, IMAGE_REVEAL_RADIUS } from './components/imageReveal';
 export type { ImageRevealPhase, ImageRevealShape, ImageRevealSizeName, ImageRevealToneName, ImageRevealState } from './components/imageReveal';
 export { default as AmbienceToggle, AMBIENCE_GROUP_ORDER } from './components/AmbienceToggle.svelte';
-export { createAmbience, createDefaultAmbience, DEFAULT_SCAPES, BreathClock, BREATHS_PER_MINUTE, MASTER, ScapeRegistry, hibiscusScape, focusScape, noiseScapes, brownNoiseScape, pinkNoiseScape, whiteNoiseScape, rain, waves, AMBIENCE_DEFAULT_GROUP_ORDER, AMBIENCE_DEFAULT_GROUP_LABELS, groupAmbienceItems, ambienceGroupLabel, isAmbienceLink, normalizeAmbienceGroups, radioStation, safeAmbienceHref } from './ambience';
+export { createAmbience, createAmbienceLocal, createSharedAmbience, AMBIENCE_CHANNEL, AMBIENCE_LOCK, createDefaultAmbience, DEFAULT_SCAPES, BreathClock, BREATHS_PER_MINUTE, MASTER, ScapeRegistry, hibiscusScape, focusScape, noiseScapes, brownNoiseScape, pinkNoiseScape, whiteNoiseScape, rain, waves, AMBIENCE_DEFAULT_GROUP_ORDER, AMBIENCE_DEFAULT_GROUP_LABELS, groupAmbienceItems, ambienceGroupLabel, isAmbienceLink, normalizeAmbienceGroups, radioStation, safeAmbienceHref } from './ambience';
 export type { DefaultAmbienceOptions, AmbienceSection } from './ambience';
+export type { SharedAmbience, SharedAmbienceState, SharedAmbienceOptions } from './ambience';
 export type { Ambience, AmbienceGroupDef, AmbienceItem, AmbienceLink, AmbienceOptions, AmbienceState, BreathState, Scape, ScapeContext, ScapeGroup, ScapeInstance } from './ambience';
 export { createPlaylistScape } from './ambience';
 export { isPlaylistScape, trackAttribution } from './ambience';

package/dist/index.js

@@ -460,7 +460,7 @@ export { imageRevealPhase, imageRevealBusy, imageRevealInitials, imageRevealSize
 // navigation; createDefaultAmbience() pre-registers every shipped scape
 // (hibiscus, focus, brown/pink/white noise, rain, waves).
 export { default as AmbienceToggle, AMBIENCE_GROUP_ORDER } from './components/AmbienceToggle.svelte';
-export { createAmbience, createDefaultAmbience, DEFAULT_SCAPES, BreathClock, BREATHS_PER_MINUTE, MASTER, ScapeRegistry, hibiscusScape, focusScape, noiseScapes, brownNoiseScape, pinkNoiseScape, whiteNoiseScape, rain, waves, AMBIENCE_DEFAULT_GROUP_ORDER, AMBIENCE_DEFAULT_GROUP_LABELS, groupAmbienceItems, ambienceGroupLabel, isAmbienceLink, normalizeAmbienceGroups, radioStation, safeAmbienceHref } from './ambience';
+export { createAmbience, createAmbienceLocal, createSharedAmbience, AMBIENCE_CHANNEL, AMBIENCE_LOCK, createDefaultAmbience, DEFAULT_SCAPES, BreathClock, BREATHS_PER_MINUTE, MASTER, ScapeRegistry, hibiscusScape, focusScape, noiseScapes, brownNoiseScape, pinkNoiseScape, whiteNoiseScape, rain, waves, AMBIENCE_DEFAULT_GROUP_ORDER, AMBIENCE_DEFAULT_GROUP_LABELS, groupAmbienceItems, ambienceGroupLabel, isAmbienceLink, normalizeAmbienceGroups, radioStation, safeAmbienceHref } from './ambience';
 // Playlist scape (phase 2) — per-host, never in DEFAULT_SCAPES: build with
 // createPlaylistScape() and register on the engine yourself.
 export { createPlaylistScape } from './ambience';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joewinke/jatui",
-  "version": "0.58.0",
+  "version": "0.59.0",
   "private": false,
   "description": "Shared Svelte 5 component library for JAT projects",
   "type": "module",