@joewinke/jatui 0.58.0 → 0.60.0

package/CLAUDE.md

@@ -333,7 +333,7 @@ const rec = createAudioRecorder({
 
 ### Ambience (subpath: `jatui/ambience`, components on the root)
 
-`createAmbience({ storageKey?, groups? })` / `createDefaultAmbience()` (headless generative Web Audio engine) + `AmbienceToggle` (app-shell speaker button). The toggle menu = volume + one row per section (Radio / Focus / Noise / Meditation … — host order via `groups: Array<ScapeGroup | {id, label}>`, default radio/focus/noise/meditation/nature/music, unlisted groups appended), each opening a submenu (→/Enter/Space open, ←/Esc close; ContextMenu submenu pattern). `radioStation({id, label, href})` registers an OUTBOUND LINK item (new tab, `rel="noopener noreferrer"`, external glyph, http(s) only) — streams are never relayed. `createPlaylistScape({ …, group? })` (default `'music'`); a playing playlist shows title — composer · license. `engine.list()` = playable scapes, `engine.items()` = scapes + links. Helpers: `groupAmbienceItems`, `isAmbienceLink`, `isPlaylistScape`, `trackAttribution`, `safeAmbienceHref`. Demo: `/components/ambience-toggle`.
+`createAmbience({ storageKey?, groups? })` / `createDefaultAmbience()` (headless generative Web Audio engine) + `AmbienceToggle` (app-shell speaker button). The toggle menu = a now-playing row above volume (playing/paused only; playlists: track title — composer · license, elapsed/total progress bar, prev / play-pause / next transport — `prev()` restarts the track when >3 s are in, else goes back one; play-pause uses engine `pause()`/`resume()` which freeze the scape in place — generative scapes get play/pause only) + one row per section (Radio / Focus / Noise / Meditation … — host order via `groups: Array<ScapeGroup | {id, label}>`, default radio/focus/noise/meditation/nature/music, unlisted groups appended), each opening a submenu (→/Enter/Space open, ←/Esc close; ContextMenu submenu pattern). `radioStation({id, label, href})` registers an OUTBOUND LINK item (new tab, `rel="noopener noreferrer"`, external glyph, http(s) only) — streams are never relayed. `createPlaylistScape({ …, group? })` (default `'music'`); a playing playlist shows title — composer · license and exposes `state().position/duration` + `skip()`/`prev()`. `engine.list()` = playable scapes, `engine.items()` = scapes + links. Shared mode: remotes render the leader's published now-playing parts (`trackTitle/trackPosition/trackDuration`) and route pause/resume/skip/prev via commands. Helpers: `groupAmbienceItems`, `isAmbienceLink`, `isPlaylistScape`, `trackAttribution`, `safeAmbienceHref`. Demo: `/components/ambience-toggle`.
 
 ### Sound (first-class sibling of motion)
 

package/dist/ambience/README.md

@@ -120,12 +120,19 @@ scape.subscribe((s) => {
   // s.status: 'idle' | 'loading' | 'playing' | 'error'
   // s.track: { title, composer, performer?, license, sourceUrl? } | null
   // s.index, s.count, s.error?
+  // s.position, s.duration — elapsed/total seconds of the current track
+  //   (0 while unknown; refreshed on the ~250 ms engine tick — jatui-153tz)
 });
-scape.skip(); // crossfade to the next track now
+scape.skip();  // crossfade to the next track now
+scape.prev();  // restart the track when >3 s are in, else the previous track
 scape.setShuffle(true);
 scape.tracks(); // resolved list, or null until the manifest resolved
 ```
 
 Cast a scape from `ambience.list()` to `PlaylistScape` in the toggle to reach
 it. The toggle renders the attribution line — `composer · performer · license`
-— linked to `sourceUrl` while a playlist scape is playing.
+— linked to `sourceUrl` while a playlist scape is playing, and (jatui-153tz) a
+now-playing row above the volume with the track, a progress bar fed by
+`position`/`duration`, and a prev / play-pause / next transport. The engine's
+`pause()`/`resume()` freeze the scape in place — the playlist pauses its media
+elements and keeps the track position.

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/engine.d.ts

@@ -12,6 +12,8 @@ export declare const TIMING: Readonly<{
     RESUME_FADE: 4;
     /** setVolume ramp (s). */
     VOLUME_RAMP: 0.3;
+    /** pause() fade-out before the scape freezes (s). */
+    PAUSE_FADE: 0.15;
     /** The fade handed to instance.stop() on kill — 0 = immediate. */
     KILL_FADE: 0;
     /** After a scape's stop fade, its un-released lookahead cbs are retired

package/dist/ambience/engine.js

@@ -27,6 +27,8 @@ export const TIMING = Object.freeze({
     RESUME_FADE: 4,
     /** setVolume ramp (s). */
     VOLUME_RAMP: 0.3,
+    /** pause() fade-out before the scape freezes (s). */
+    PAUSE_FADE: 0.15,
     /** The fade handed to instance.stop() on kill — 0 = immediate. */
     KILL_FADE: 0,
     /** After a scape's stop fade, its un-released lookahead cbs are retired
@@ -50,6 +52,12 @@ export function createAmbience(options = {}) {
     let volume = clamp(typeof persisted.volume === 'number' ? persisted.volume : (options.defaultVolume ?? 0.6));
     let currentId = persisted.lastScape ?? null;
     let playing = false;
+    /** True between pause() and resume()/play()/stop(): the instance stays
+     *  built and frozen (playlist position kept), the context suspended. */
+    let paused = false;
+    /** The deferred freeze at the end of pause()'s fade — a resume()/play()
+     *  inside the window aborts it. */
+    let pauseTimer = null;
     let ctx = null;
     let chain = null;
     let active = null;
@@ -62,7 +70,7 @@ export function createAmbience(options = {}) {
     const breathSubs = new Set();
     const lookaheadCbs = new Set();
     function state() {
-        return { currentId, playing, volume };
+        return { currentId, playing, paused, volume };
     }
     function emit() {
         const s = state();
@@ -145,8 +153,11 @@ export function createAmbience(options = {}) {
         // one is suspended at `await c.resume()` invalidates it — the loser
         // returns without building or starting anything.
         const gen = ++playGen;
-        // Inside the post-stop close window: cancel the close, fade back in.
-        const resuming = closeTimer !== null;
+        const wasPaused = paused;
+        paused = false; // a play() is a fresh start — never a continuation
+        // Inside the post-stop close window (or resuming from a paused scape):
+        // cancel the close / unfreeze, and fade the bus back in.
+        const resuming = closeTimer !== null || wasPaused;
         if (closeTimer !== null) {
             clearTimeout(closeTimer);
             closeTimer = null;
@@ -201,7 +212,15 @@ export function createAmbience(options = {}) {
     }
     function stop() {
         playGen++; // invalidate any in-flight play()
-        if (!ctx || !playing) {
+        if (pauseTimer) {
+            clearTimeout(pauseTimer);
+            pauseTimer = null;
+        }
+        const wasPaused = paused;
+        paused = false;
+        // A paused scape still owns a live (frozen) instance + context — its
+        // stop must tear them down like a playing stop would.
+        if (!ctx || (!playing && !wasPaused)) {
             playing = false;
             emit();
             return;
@@ -223,12 +242,88 @@ export function createAmbience(options = {}) {
         }, TIMING.CLOSE_DELAY_MS);
         emit();
     }
+    function pause() {
+        if (!playing)
+            return;
+        playing = false;
+        paused = true;
+        emit();
+        if (!ctx || !chain || !active)
+            return;
+        // A short fade so the freeze is click-free, then the scape freezes in
+        // place (media elements) and the context suspends — generative scapes
+        // stop evolving and the audio thread rests.
+        const now = ctx.currentTime;
+        const g = chain.bus.gain;
+        g.cancelScheduledValues(now);
+        g.setValueAtTime(g.value, now);
+        g.linearRampToValueAtTime(0, now + TIMING.PAUSE_FADE);
+        if (pauseTimer)
+            clearTimeout(pauseTimer);
+        pauseTimer = setTimeout(() => {
+            pauseTimer = null;
+            // A resume()/play()/stop() inside the fade window aborted the pause.
+            if (!paused || playing || !active || !ctx)
+                return;
+            try {
+                active.inst.pause?.();
+            }
+            catch {
+                /* a broken scape must not take the engine down */
+            }
+            try {
+                void ctx.suspend();
+            }
+            catch {
+                /* already closed */
+            }
+        }, TIMING.PAUSE_FADE * 1000 + 20);
+    }
+    async function resume() {
+        if (playing || !currentId || !paused)
+            return; // only a paused scape resumes
+        if (!isGesture())
+            throw new Error('resume() must be called from a user gesture');
+        const gen = ++playGen; // a stop()/kill() during the resume invalidates it
+        paused = false;
+        // Defensive: a paused engine always still owns its context + instance
+        // (kill/stop clear the paused flag) — bail rather than guess.
+        if (!ctx || !chain || !active) {
+            emit();
+            return;
+        }
+        if (ctx.state === 'suspended')
+            await ctx.resume();
+        if (gen !== playGen || !ctx || !chain || !active)
+            return; // superseded mid-resume
+        try {
+            active.inst.resume?.();
+        }
+        catch {
+            /* a broken scape must not take the engine down */
+        }
+        const g = chain.bus.gain;
+        g.cancelScheduledValues(ctx.currentTime);
+        g.setValueAtTime(g.value, ctx.currentTime);
+        g.linearRampToValueAtTime(1, ctx.currentTime + TIMING.VOLUME_RAMP);
+        // A pause did not stop the breath clock, but make sure it runs.
+        if (!breath.running)
+            breath.start(ctx.currentTime);
+        playing = true;
+        persist();
+        emit();
+    }
     function kill() {
         playGen++; // invalidate any in-flight play()
         if (closeTimer) {
             clearTimeout(closeTimer);
             closeTimer = null;
         }
+        if (pauseTimer) {
+            clearTimeout(pauseTimer);
+            pauseTimer = null;
+        }
+        paused = false;
         if (tick) {
             clearInterval(tick);
             tick = null;
@@ -298,6 +393,8 @@ export function createAmbience(options = {}) {
         },
         play,
         stop,
+        pause,
+        resume,
         kill,
         setVolume,
         get state() {

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

@@ -47,6 +47,9 @@ export declare const PLAYLIST: Readonly<{
     /** Start the next track when at most this much of the current track is
      *  left ON TOP of the crossfade (s). */
     END_MARGIN: 0.25;
+    /** prev() restarts the current track when more than this many seconds are
+     *  in; below it, it goes back one track (jatui-153tz). */
+    PREV_RESTART: 3;
     /** setParam('gain') ramp (s). */
     GAIN_RAMP: 0.15;
     /** Disconnect + pause this many ms after a stop fade ends — before the
@@ -84,6 +87,13 @@ export interface PlaylistState {
     index: number;
     /** Number of tracks in the resolved playlist (0 until resolved). */
     count: number;
+    /** Elapsed seconds of the current track (0 while none is sounding).
+     *  Updated on the engine's ~250 ms lookahead tick — the cadence the
+     *  toggle's progress bar renders at (jatui-153tz). */
+    position: number;
+    /** Total seconds of the current track (0 until metadata reports one —
+     *  a stream without a duration stays 0). */
+    duration: number;
     /** Present on error. */
     error?: string;
 }
@@ -124,8 +134,17 @@ export interface PlaylistScape extends Scape {
     subscribe(fn: (s: PlaylistState) => void): () => void;
     /** Crossfade to the next track now. No-op while loading/released. */
     skip(): void;
+    /** Back one step (jatui-153tz): restart the current track when more than
+     *  PLAYLIST.PREV_RESTART (3 s) are in, else crossfade to the previous
+     *  track in the play order (at the very first track, restart). No-op
+     *  while loading/released or mid-transition. */
+    prev(): 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

@@ -8,6 +8,9 @@ export const PLAYLIST = Object.freeze({
     /** Start the next track when at most this much of the current track is
      *  left ON TOP of the crossfade (s). */
     END_MARGIN: 0.25,
+    /** prev() restarts the current track when more than this many seconds are
+     *  in; below it, it goes back one track (jatui-153tz). */
+    PREV_RESTART: 3,
     /** setParam('gain') ramp (s). */
     GAIN_RAMP: 0.15,
     /** Disconnect + pause this many ms after a stop fade ends — before the
@@ -43,7 +46,7 @@ export function createPlaylistScape(options) {
         }
     }
     /** Shared UI snapshot + subscribers. Only the latest build writes it. */
-    let snap = { status: 'idle', track: null, index: 0, count: 0 };
+    let snap = { status: 'idle', track: null, index: 0, count: 0, position: 0, duration: 0 };
     const subs = new Set();
     /** Handle to the most recent build — skip()/setShuffle() route here. */
     let latest = null;
@@ -178,6 +181,12 @@ export function createPlaylistScape(options) {
                 if (slot.trackIndex < 0)
                     return;
                 const el = slot.el;
+                // Live progress for the toggle's now-playing row (jatui-153tz):
+                // elapsed/total on the ~250 ms tick cadence the bar renders at.
+                const position = Number.isFinite(el.currentTime) ? Math.max(0, el.currentTime) : 0;
+                const duration = Number.isFinite(el.duration) && el.duration > 0 ? el.duration : 0;
+                if (snap.position !== position || snap.duration !== duration)
+                    setSnap({ position, duration });
                 const d = el.duration;
                 // Stateless per-tick check (no while-loop to re-anchor): at most ONE
                 // transition per tick, always anchored at THIS tick's now, so a
@@ -274,7 +283,15 @@ export function createPlaylistScape(options) {
             catch {
                 onTrackFailed();
             }
-            setSnap({ status: 'playing', track, index: pos, count: resolved.length, error: undefined });
+            setSnap({
+                status: 'playing',
+                track,
+                index: pos,
+                count: resolved.length,
+                position: 0,
+                duration: 0,
+                error: undefined
+            });
             preloadNext();
         }
         function quietSlot(slot) {
@@ -357,6 +374,8 @@ export function createPlaylistScape(options) {
                 track: null,
                 index: 0,
                 count: resolved?.length ?? 0,
+                position: 0,
+                duration: 0,
                 error: undefined
             });
             const f = Math.max(0, fade);
@@ -432,7 +451,9 @@ export function createPlaylistScape(options) {
                 error: message,
                 track: null,
                 index: 0,
-                count: resolved?.length ?? 0
+                count: resolved?.length ?? 0,
+                position: 0,
+                duration: 0
             });
             const now = ctx.currentTime;
             const g = mix.gain;
@@ -461,6 +482,66 @@ export function createPlaylistScape(options) {
             if (ni !== -1)
                 startTrack(ni, 'cross');
         }
+        /** Back one step (jatui-153tz): > 3 s into the track restarts it, else
+         *  the previous track in the play order (the first track restarts). */
+        function prevInternal() {
+            if (released || !started || order.length === 0 || active < 0)
+                return;
+            const slot = slots[active];
+            const cur = order[pos];
+            if (slot.trackIndex !== cur)
+                return; // mid-transition — the skip owns it
+            if (slot.el.currentTime > PLAYLIST.PREV_RESTART || pos === 0) {
+                // Restart the current track: a quick fade into the idle slot
+                // loaded with the same track, play order pointer unchanged.
+                startTrack(cur, 'ended');
+            }
+            else {
+                pos -= 1;
+                startTrack(order[pos], 'cross');
+            }
+        }
+        /** Engine pause(): freeze in place — both elements stop, the track and
+         *  its position are kept for resume(). Gains/schedules stay as they are
+         *  (the context suspension freezes the audio clock mid-ramp). */
+        function pauseInternal() {
+            if (released || !started)
+                return;
+            for (const slot of slots) {
+                try {
+                    slot.el.pause();
+                }
+                catch {
+                    /* element already unusable */
+                }
+            }
+        }
+        /** Engine resume(): the active element continues from where it paused.
+         *  The idle (preloading) slot stays paused. */
+        function resumeInternal() {
+            if (released || !started || active < 0)
+                return;
+            const slot = slots[active];
+            if (slot.trackIndex < 0)
+                return;
+            try {
+                const p = slot.el.play();
+                if (p)
+                    p.catch(() => { }); // the engine's failed-track path owns errors
+            }
+            catch {
+                /* element already unusable */
+            }
+        }
+        /** 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() {
@@ -480,8 +561,10 @@ export function createPlaylistScape(options) {
         }
         wireLookahead();
         return {
-            api: { start, stop, setParam },
+            api: { start, stop, setParam, pause: pauseInternal, resume: resumeInternal },
             skip: skipInternal,
+            prev: prevInternal,
+            startAt: startAtInternal,
             reshuffle,
             isReleased: () => released
         };
@@ -509,11 +592,19 @@ export function createPlaylistScape(options) {
             if (latest && !latest.isReleased())
                 latest.skip();
         },
+        prev() {
+            if (latest && !latest.isReleased())
+                latest.prev();
+        },
         setShuffle(on) {
             shuffle = on;
             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,164 @@
+/**
+ * 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 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;
+    /** The published track's title, so a remote can show title and
+     *  attribution on their own lines (jatui-153tz). */
+    trackTitle: string | null;
+    /** Elapsed seconds within the published track (leader-published at the
+     *  playlist's ~250 ms state cadence); null when unknown. */
+    trackPosition: number | null;
+    /** Total seconds of the published track; null while unknown (no metadata
+     *  yet, or a stream without a duration). */
+    trackDuration: number | null;
+    /** True while the leader is PAUSED (engine.pause() — the scape is frozen
+     *  in place, not torn down; resume continues it). */
+    paused: boolean;
+}
+/** 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 + progress) so remote tabs show it too.
+     *  `position`/`duration`/`title` (jatui-153tz) feed the remote tabs'
+     *  now-playing row; nulls mean unknown. */
+    setNowPlaying(line: string | null, trackIndex?: number | null, position?: number | null, duration?: number | null, title?: string | null): void;
+    /** Now-playing-row transport (jatui-153tz): skip / go back one track on a
+     *  playlist scape. A remote routes the command to the leader's instance. */
+    skipTrack(id: string): void;
+    prevTrack(id: string): 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;
+/** 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 declare const createAmbienceLocal: typeof createLocalEngine;