@joewinke/jatui 0.61.0 → 0.63.0

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

@@ -0,0 +1,113 @@
+/**
+ * Ambience scape — radio stream (jatui-plbzq): play a station's public
+ * stream DIRECTLY in the player.
+ *
+ * By design (jatui-mdq2p) a `radioStation()` is an outbound LINK: the
+ * station's own site opens in a new tab and no stream is ever relayed
+ * through the host's servers. `streamUrl` opts a station into a second
+ * behavior: the browser fetches the station's public stream CLIENT-side
+ * (the same constraint — nothing is relayed — just moved from "not played"
+ * to "not proxied") and it sounds through this scape.
+ *
+ * The element is a plain `<audio src>` — deliberately NOT routed through
+ * the Web Audio graph:
+ *
+ * - Routing a cross-origin element through a MediaElementAudioSourceNode
+ *   without CORS headers yields SILENCE (the tainted-graph rule), and most
+ *   station streams do not send `Access-Control-Allow-Origin`. Setting
+ *   `crossOrigin = 'anonymous'` first (the playlist's contract — its host
+ *   owns the manifest and can serve CORS) would refuse to load those
+ *   streams outright.
+ * - A plain element plays any http(s) stream. Its loudness follows the
+ *   engine by mirroring the engine's volume onto `el.volume` (the scape's
+ *   own gain × the context's `volume()` — refreshed on the lookahead tick,
+ *   so the volume slider and cross-tab mute apply to radio too).
+ *
+ * What radio gives up versus the playlist: no crossfades (a live stream
+ * has no tracks to fade between — a stop is a stepped element-volume fade),
+ * no progress bar (a stream reports no duration) and no per-track
+ * attribution. Attribution stays: the scape keeps the station's site url
+ * (`safeAmbienceHref`-validated) and the now-playing row shows
+ * "Open station site".
+ *
+ * The returned object is a plain Scape for the engine plus a small UI
+ * surface (`state()` / `subscribe()`, discriminated by `radio: true`) that
+ * the toggle narrows with `isRadioScape()`. Nothing is registered globally.
+ */
+import type { AmbienceLink, Scape, ScapeGroup } from '../types';
+/** Ramp + teardown timing for the radio scape. */
+export declare const RADIO: Readonly<{
+    /** Stepped element-volume fade on stop() — steps per second of fade. */
+    FADE_STEPS_PER_S: 8;
+    /** Pause + de-src this many ms after a stop fade ends — before the
+     *  engine's lookahead retirement (fade*1000 + 250) can drop anything. */
+    TEARDOWN_DELAY_MS: 50;
+}>;
+export type RadioStreamStatus = 'idle' | 'loading' | 'playing' | 'error';
+export interface RadioStreamState {
+    status: RadioStreamStatus;
+    /** The station's name — the now-playing row's title. */
+    station: string;
+    /** The validated station-site url (the "Open station site" attribution
+     *  link), or null when the site href was not a safe absolute http(s)
+     *  one — the stream still plays, the link just hides. */
+    href: string | null;
+    /** Present on error. */
+    error?: string;
+}
+export interface RadioStreamScapeOptions {
+    id: string;
+    label: string;
+    description?: string;
+    /** The menu section (default 'radio'). */
+    group?: ScapeGroup;
+    /** The station's own page — the attribution link target. Validated with
+     *  `safeAmbienceHref`; an unsafe href keeps the stream playable and
+     *  just hides the link. */
+    href?: string;
+    /** The station's public stream url. MUST be an absolute http(s) one —
+     *  anything else is refused at creation. */
+    streamUrl: string;
+    /** Initial loudness multiplier, 0..1 (default 1) — the element's own
+     *  volume is this × the engine's master volume. `setParam('gain', v)`
+     *  changes it live. */
+    gain?: number;
+    /** Injectable for tests (default `new Audio(url)`). */
+    createMediaElement?: (url: string) => HTMLAudioElement;
+}
+/** A Scape plus the radio UI surface. Narrow a registered Scape with
+ *  `isRadioScape()` in the toggle to reach state()/subscribe(). */
+export interface RadioStreamScape extends Scape {
+    /** Discriminates a radio stream from other scapes. */
+    readonly radio: true;
+    /** The validated station-site url, or null (no attribution link). */
+    readonly href: string | null;
+    /** Current snapshot (also the initial value subscribe() fires with). */
+    state(): RadioStreamState;
+    /** Subscribe to radio state changes; fires immediately. */
+    subscribe(fn: (s: RadioStreamState) => void): () => void;
+}
+export declare function createRadioStreamScape(options: RadioStreamScapeOptions): RadioStreamScape;
+/** Narrow a registered scape to a radio stream (to reach its state surface). */
+export declare function isRadioScape(scape: unknown): scape is RadioStreamScape;
+/**
+ * Build a radio-station item: WITHOUT `streamUrl` an outbound link (the
+ * station's site opens in a new tab — the original, always-available
+ * behavior); WITH `streamUrl` the station's public stream plays right in
+ * the player (client-side fetch from the station — never relayed) and the
+ * site link survives as the attribution target in the now-playing row.
+ *
+ * A `streamUrl` that fails `safeAmbienceHref` (anything but an absolute
+ * http(s) url) is REFUSED: the station falls back to the outbound link and
+ * the bad url is never stored or loaded.
+ */
+export declare function radioStation(options: {
+    id: string;
+    label: string;
+    href: string;
+    description?: string;
+    group?: ScapeGroup;
+    /** The station's public stream url (absolute http(s) only) — when
+     *  present, the station plays in the player. */
+    streamUrl?: string;
+}): AmbienceLink | RadioStreamScape;

package/dist/ambience/scapes/radio.js

@@ -0,0 +1,297 @@
+import { safeAmbienceHref } from '../groups';
+/** Ramp + teardown timing for the radio scape. */
+export const RADIO = Object.freeze({
+    /** Stepped element-volume fade on stop() — steps per second of fade. */
+    FADE_STEPS_PER_S: 8,
+    /** Pause + de-src this many ms after a stop fade ends — before the
+     *  engine's lookahead retirement (fade*1000 + 250) can drop anything. */
+    TEARDOWN_DELAY_MS: 50
+});
+export function createRadioStreamScape(options) {
+    if (!options?.id)
+        throw new Error('createRadioStreamScape: id is required');
+    if (!options.label)
+        throw new Error('createRadioStreamScape: label is required');
+    if (!options.streamUrl || typeof options.streamUrl !== 'string')
+        throw new Error('createRadioStreamScape: streamUrl is required');
+    // Refuse at create time: a `javascript:`/`data:`/relative stream url
+    // would end up in an <audio> src — http(s) absolute only, the same gate
+    // as every other ambience href.
+    const validated = safeAmbienceHref(options.streamUrl);
+    if (!validated)
+        throw new Error('createRadioStreamScape: streamUrl must be an absolute http(s) url');
+    // Explicitly typed alias: buildInstance is a hoisted declaration, and TS
+    // resets truthiness narrowing at its capture — the guard above is the
+    // build-time refusal this module promises.
+    const streamUrl = validated;
+    const href = safeAmbienceHref(options.href);
+    let mixGain0 = Math.min(1, Math.max(0, options.gain ?? 1));
+    const makeElement = options.createMediaElement ?? ((url) => new Audio(url));
+    /** Shared UI snapshot + subscribers. Only the latest build writes it. */
+    let snap = {
+        status: 'idle',
+        station: options.label,
+        href: href ?? null
+    };
+    const subs = new Set();
+    let instanceSeq = 0;
+    function setSnap(patch) {
+        snap = { ...snap, ...patch };
+        for (const fn of subs)
+            fn(snap);
+    }
+    function buildInstance(scapeCtx) {
+        const instId = ++instanceSeq;
+        let released = false;
+        let started = false;
+        let fading = false;
+        const timers = new Set();
+        let unsub = null;
+        // A plain <audio> element — no crossOrigin (a station stream without
+        // CORS headers must still load), no source node (the tainted-graph
+        // rule would silence it). Loudness is el.volume, below.
+        const el = makeElement(streamUrl);
+        try {
+            // The src is set here, not only via the constructor: an injectable
+            // factory may build a bare element (the real `new Audio(url)` already
+            // carries it), and the tests read the assignment back.
+            el.src = streamUrl;
+            el.preload = 'auto';
+        }
+        catch {
+            /* exotic environments */
+        }
+        const isLive = () => instId === instanceSeq && !released;
+        function atTimer(ms, fn) {
+            if (released)
+                return;
+            const t = setTimeout(() => {
+                timers.delete(t);
+                if (!released)
+                    fn();
+            }, Math.max(0, ms));
+            timers.add(t);
+        }
+        /** The element's loudness right now: the scape gain × the engine's
+         *  master volume (a hand-made test context may omit the hook — it
+         *  then reads full volume). */
+        function elementVolume() {
+            const master = scapeCtx.volume ? scapeCtx.volume() : 1;
+            return Math.min(1, Math.max(0, master)) * Math.min(1, Math.max(0, mixGain0));
+        }
+        function applyVolume() {
+            try {
+                el.volume = Math.min(1, Math.max(0, elementVolume()));
+            }
+            catch {
+                /* element already unusable */
+            }
+        }
+        // The element's own events, so a stream that stalls or dies is
+        // visible in the state surface instead of playing silence.
+        el.addEventListener('playing', () => {
+            if (!isLive() || fading)
+                return;
+            setSnap({ status: 'playing', error: undefined });
+        });
+        el.addEventListener('ended', () => {
+            // A live stream should not end; when it does, say so rather than
+            // showing a playing row over silence.
+            if (!isLive() || fading)
+                return;
+            fail('The stream ended');
+        });
+        el.addEventListener('error', () => {
+            if (!isLive() || fading)
+                return;
+            fail('The stream could not be loaded');
+        });
+        // Mirror the engine's volume on every lookahead tick (~250 ms) so the
+        // volume slider and cross-tab mute reach an element outside the graph.
+        unsub = scapeCtx.lookahead(() => {
+            if (released || !started || fading)
+                return;
+            applyVolume();
+        });
+        function start(_at) {
+            // A superseded (stale) build is inert: only the newest instance may
+            // sound or report — the shared snapshot belongs to the live one.
+            if (started || released || !isLive())
+                return;
+            started = true;
+            setSnap({ status: 'loading', error: undefined });
+            applyVolume();
+            try {
+                const p = el.play();
+                if (p)
+                    p.then(() => {
+                        if (!isLive() || fading)
+                            return;
+                        setSnap({ status: 'playing', error: undefined });
+                    }, () => fail('The stream could not be started'));
+            }
+            catch {
+                fail('The stream could not be started');
+            }
+        }
+        function fail(message) {
+            if (released || !isLive())
+                return;
+            setSnap({ status: 'error', error: message });
+            release();
+        }
+        function release() {
+            if (released)
+                return;
+            released = true;
+            unsub?.();
+            unsub = null;
+            for (const t of timers)
+                clearTimeout(t);
+            timers.clear();
+            try {
+                el.pause();
+            }
+            catch {
+                /* element already unusable */
+            }
+            try {
+                el.removeAttribute('src');
+                el.load();
+            }
+            catch {
+                /* older engines */
+            }
+        }
+        function stop(_at, fade) {
+            if (released)
+                return;
+            setSnap({ status: 'idle', error: undefined });
+            const f = Math.max(0, fade);
+            if (f <= 0) {
+                release();
+                return;
+            }
+            // Stepped element-volume fade (there is no audio-clock gain here):
+            // FADE_STEPS_PER_S steps per fade second, then the wall-clock release.
+            fading = true;
+            const steps = Math.max(1, Math.round(f * RADIO.FADE_STEPS_PER_S));
+            const stepMs = (f * 1000) / steps;
+            for (let i = 1; i <= steps; i++) {
+                atTimer(stepMs * i, () => {
+                    const k = 1 - i / steps;
+                    try {
+                        el.volume = Math.min(1, Math.max(0, elementVolume())) * k;
+                    }
+                    catch {
+                        /* element already unusable */
+                    }
+                });
+            }
+            atTimer(f * 1000 + RADIO.TEARDOWN_DELAY_MS, release);
+        }
+        function setParam(key, value) {
+            if (key !== 'gain' || released)
+                return;
+            mixGain0 = Math.min(1, Math.max(0, value));
+            if (started && !fading)
+                applyVolume();
+        }
+        function pauseInternal() {
+            if (released || !started)
+                return;
+            try {
+                el.pause();
+            }
+            catch {
+                /* element already unusable */
+            }
+        }
+        function resumeInternal() {
+            if (released || !started)
+                return;
+            try {
+                const p = el.play();
+                if (p)
+                    p.catch(() => { }); // the error surface owns failures
+            }
+            catch {
+                /* element already unusable */
+            }
+        }
+        return { start, stop, setParam, pause: pauseInternal, resume: resumeInternal };
+    }
+    const scape = {
+        id: options.id,
+        label: options.label,
+        group: options.group ?? 'radio',
+        description: options.description,
+        radio: true,
+        href: href ?? null,
+        build(scapeCtx) {
+            return buildInstance(scapeCtx);
+        },
+        state: () => snap,
+        subscribe(fn) {
+            subs.add(fn);
+            fn(snap);
+            return () => {
+                subs.delete(fn);
+            };
+        }
+    };
+    return scape;
+}
+/** Narrow a registered scape to a radio stream (to reach its state surface). */
+export function isRadioScape(scape) {
+    return (typeof scape === 'object' &&
+        scape !== null &&
+        scape.radio === true &&
+        typeof scape.subscribe === 'function');
+}
+/**
+ * Build a radio-station item: WITHOUT `streamUrl` an outbound link (the
+ * station's site opens in a new tab — the original, always-available
+ * behavior); WITH `streamUrl` the station's public stream plays right in
+ * the player (client-side fetch from the station — never relayed) and the
+ * site link survives as the attribution target in the now-playing row.
+ *
+ * A `streamUrl` that fails `safeAmbienceHref` (anything but an absolute
+ * http(s) url) is REFUSED: the station falls back to the outbound link and
+ * the bad url is never stored or loaded.
+ */
+export function radioStation(options) {
+    if (options.streamUrl === undefined || options.streamUrl === null) {
+        return {
+            kind: 'link',
+            id: options.id,
+            label: options.label,
+            group: options.group ?? 'radio',
+            href: options.href,
+            description: options.description
+        };
+    }
+    if (!safeAmbienceHref(options.streamUrl)) {
+        // Refused: a typo'd scheme silently dropping the stream would be very
+        // hard to spot from the outside — say so once, then degrade to the
+        // always-available link behavior.
+        if (typeof console !== 'undefined' && typeof console.warn === 'function')
+            console.warn(`radioStation(${options.id}): streamUrl must be an absolute http(s) url — falling back to the outbound link`);
+        return {
+            kind: 'link',
+            id: options.id,
+            label: options.label,
+            group: options.group ?? 'radio',
+            href: options.href,
+            description: options.description
+        };
+    }
+    return createRadioStreamScape({
+        id: options.id,
+        label: options.label,
+        description: options.description,
+        group: options.group,
+        href: options.href,
+        streamUrl: options.streamUrl
+    });
+}

package/dist/ambience/shared.d.ts

@@ -57,6 +57,31 @@ export declare const SHARED_TIMING: Readonly<{
     /** A remote play command waits this long (ms) for the leader's echo. */
     REMOTE_PLAY_TIMEOUT_MS: 2500;
 }>;
+/** The current track's download info (jatui-0vxcu), published by the leader
+ *  alongside the now-playing parts — present ONLY when the licence permits
+ *  redistribution (`isTrackDownloadable`), so a remote tab can offer the
+ *  same download button without re-deriving the gate or the filename. */
+export interface SharedTrackDownload {
+    /** The track's audio url (the leader's manifest entry). */
+    url: string;
+    /** Ready-made filename — "Composer - Title.ext", built leader-side by
+     *  `trackDownloadFilename` so attribution travels with the file. */
+    filename: string;
+    /** The licence string, for the button's tooltip and describedby line. */
+    license: string;
+    /** Page the recording came from (attribution link target). */
+    sourceUrl?: string;
+}
+/**
+ * A published download re-validated on the CONSUMING side (jatui-0vxcu):
+ * the leader is another tab, not a trusted source — its `url` must survive
+ * `safeAmbienceHref` (absolute http/https only: a `javascript:`/`data:` or
+ * scheme-relative url from a compromised manifest or a hostile tab would
+ * otherwise reach this tab's `window.open` fallback) and the filename and
+ * licence must be usable strings. Anything else returns null — the remote
+ * tab's download button hides. The validated url replaces the original.
+ */
+export declare function safeSharedTrackDownload(download: SharedTrackDownload | null | undefined): SharedTrackDownload | null;
 /** The live cross-tab state every tab renders. */
 export interface SharedAmbienceState {
     /** Currently playing (or preselected) scape id, or null. */
@@ -92,6 +117,14 @@ export interface SharedAmbienceState {
     /** True while the leader is PAUSED (engine.pause() — the scape is frozen
      *  in place, not torn down; resume continues it). */
     paused: boolean;
+    /** The published track's download info (url + filename + licence), or
+     *  null when nothing is playing or the licence forbids redistribution
+     *  (jatui-0vxcu). A remote tab's download button reads this. */
+    trackDownload: SharedTrackDownload | null;
+    /** The playing playlist's shuffle state (jatui-plbzq), published so a
+     *  remote tab's Shuffle toggle shows the leader's truth. Null when
+     *  unknown (nothing playing, or the scape is not a playlist). */
+    trackShuffle: boolean | null;
 }
 /** An Ambience whose playback is shared across tabs (see module doc). */
 export interface SharedAmbience extends Ambience {
@@ -105,12 +138,18 @@ export interface SharedAmbience extends Ambience {
     /** 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; nulls mean unknown. `download` (jatui-0vxcu) carries
+     *  the track's download info when its licence permits redistribution —
+     *  null clears it. `shuffle` (jatui-plbzq) publishes the playing
+     *  playlist's shuffle state for the remotes' Shuffle toggle. */
+    setNowPlaying(line: string | null, trackIndex?: number | null, position?: number | null, duration?: number | null, title?: string | null, download?: SharedTrackDownload | null, shuffle?: boolean | 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;
+    /** Shuffle transport (jatui-plbzq): set the playing playlist's shuffle
+     *  state. A remote routes the command to the leader's instance. */
+    shuffleTrack(id: string, on: boolean): void;
     /** Release the lock, stop the heartbeat and close the channel. The local
      *  engine is killed if this tab was the leader. */
     destroy(): void;

package/dist/ambience/shared.js

@@ -42,6 +42,7 @@
  */
 import { createAmbience as createLocalEngine } from './engine';
 import { isPlaylistScape } from './scapes/playlist';
+import { safeAmbienceHref } from './groups';
 import { loadPersisted, savePersisted } from './persist';
 /** BroadcastChannel name — the ambience control channel for the origin. */
 export const AMBIENCE_CHANNEL = 'jatui:ambience';
@@ -58,6 +59,27 @@ export const SHARED_TIMING = Object.freeze({
     /** A remote play command waits this long (ms) for the leader's echo. */
     REMOTE_PLAY_TIMEOUT_MS: 2500
 });
+/**
+ * A published download re-validated on the CONSUMING side (jatui-0vxcu):
+ * the leader is another tab, not a trusted source — its `url` must survive
+ * `safeAmbienceHref` (absolute http/https only: a `javascript:`/`data:` or
+ * scheme-relative url from a compromised manifest or a hostile tab would
+ * otherwise reach this tab's `window.open` fallback) and the filename and
+ * licence must be usable strings. Anything else returns null — the remote
+ * tab's download button hides. The validated url replaces the original.
+ */
+export function safeSharedTrackDownload(download) {
+    if (!download || typeof download !== 'object')
+        return null;
+    const url = safeAmbienceHref(download.url);
+    if (!url)
+        return null;
+    if (typeof download.filename !== 'string' || download.filename.trim() === '')
+        return null;
+    if (typeof download.license !== 'string' || download.license.trim() === '')
+        return null;
+    return { ...download, url };
+}
 function randomTabId() {
     try {
         return `tab-${crypto.randomUUID?.() ?? Math.random().toString(36).slice(2)}`;
@@ -120,6 +142,10 @@ export function createSharedAmbience(options = {}) {
     let nowPlayingTitle = null;
     let nowPlayingPosition = null;
     let nowPlayingDuration = null;
+    /** The published track's download info (jatui-0vxcu). */
+    let nowPlayingDownload = null;
+    /** The published playlist's shuffle state (jatui-plbzq). */
+    let nowPlayingShuffle = null;
     const ambienceSubs = new Set();
     const sharedSubs = new Set();
     function sharedState() {
@@ -137,7 +163,9 @@ export function createSharedAmbience(options = {}) {
             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)
+            trackDuration: role === 'leader' ? nowPlayingDuration : (remoteS?.trackDuration ?? null),
+            trackDownload: role === 'leader' ? nowPlayingDownload : (remoteS?.trackDownload ?? null),
+            trackShuffle: role === 'leader' ? nowPlayingShuffle : (remoteS?.trackShuffle ?? null)
         };
     }
     function ambienceState() {
@@ -206,6 +234,8 @@ export function createSharedAmbience(options = {}) {
         nowPlayingTitle = null;
         nowPlayingPosition = null;
         nowPlayingDuration = null;
+        nowPlayingDownload = null;
+        nowPlayingShuffle = null;
         remoteS = null;
         if (heartbeatTimer) {
             clearInterval(heartbeatTimer);
@@ -404,7 +434,7 @@ export function createSharedAmbience(options = {}) {
                 // 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 };
+                    remoteS = { ...remoteS, playing: false, paused: false, nowPlaying: null, trackDownload: null };
                     leaderGone = true;
                     emitShared();
                 }
@@ -445,6 +475,14 @@ export function createSharedAmbience(options = {}) {
                             p?.prev();
                         break;
                     }
+                    case 'shuffle': {
+                        // The Shuffle toggle (jatui-plbzq): routed to the leader's own
+                        // playlist scape instance (its preference persists there).
+                        if (!msg.id)
+                            return;
+                        playlistFor(msg.id)?.setShuffle((msg.arg ?? 0) === 1);
+                        break;
+                    }
                     case 'setVolume':
                         applyVolume(msg.arg ?? userVolume);
                         break;
@@ -487,7 +525,7 @@ export function createSharedAmbience(options = {}) {
         if (remoteS?.playing &&
             lastBeatAt > 0 &&
             Date.now() - lastBeatAt > staleMs) {
-            remoteS = { ...remoteS, playing: false, paused: false, nowPlaying: null };
+            remoteS = { ...remoteS, playing: false, paused: false, nowPlaying: null, trackDownload: null };
             leaderGone = true;
             emitShared();
         }
@@ -571,7 +609,7 @@ export function createSharedAmbience(options = {}) {
         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 };
+            remoteS = { ...remoteS, playing: false, paused: false, nowPlaying: null, trackDownload: null };
         emitShared();
     }
     /** Freeze in place (the scape is not torn down; a playlist keeps its track
@@ -618,6 +656,16 @@ export function createSharedAmbience(options = {}) {
         }
         post({ t: 'cmd', cmd: 'prev', id, from: tabId });
     }
+    /** Shuffle transport (jatui-plbzq): set the playing playlist's shuffle
+     *  state — routed to the leader's live instance when this tab is a
+     *  remote (its preference persists there). */
+    function shuffleTrack(id, on) {
+        if (role === 'leader') {
+            playlistFor(id)?.setShuffle(on);
+            return;
+        }
+        post({ t: 'cmd', cmd: 'shuffle', id, arg: on ? 1 : 0, from: tabId });
+    }
     function setVolume(v) {
         applyVolume(v);
         savePersisted(storageKey, {
@@ -687,6 +735,7 @@ export function createSharedAmbience(options = {}) {
         resume,
         skipTrack,
         prevTrack,
+        shuffleTrack,
         kill: () => {
             // A remote has nothing local to kill — tell the leader instead.
             if (role === 'leader')
@@ -697,12 +746,14 @@ export function createSharedAmbience(options = {}) {
         setVolume,
         setMuted,
         toggleMute,
-        setNowPlaying(line, index, position, duration, title) {
+        setNowPlaying(line, index, position, duration, title, download, shuffle) {
             nowPlaying = line;
             nowPlayingIndex = line ? (index ?? null) : null;
             nowPlayingPosition = line ? (position ?? null) : null;
             nowPlayingDuration = line ? (duration ?? null) : null;
             nowPlayingTitle = line ? (title ?? null) : null;
+            nowPlayingDownload = line ? (download ?? null) : null;
+            nowPlayingShuffle = line ? (shuffle ?? null) : null;
             if (role === 'leader') {
                 publish();
                 emitShared();

package/dist/ambience/types.d.ts

@@ -19,6 +19,13 @@ export interface ScapeContext {
     lookahead: (cb: (now: number) => void) => () => void;
     /** Deterministic-ish random source scoped to the scape instance. */
     rand: () => number;
+    /** The engine's CURRENT master volume, 0..1 (jatui-plbzq). Optional —
+     *  only scapes that play OUTSIDE the audio graph need it: a radio
+     *  stream's plain `<audio>` element mirrors `volume() × `its own gain
+     *  onto `el.volume`, refreshed on the lookahead tick, so the volume
+     *  slider and cross-tab mute reach it too. Hand-made test contexts may
+     *  omit it (the scape then reads full volume). */
+    volume?: () => number;
 }
 export interface ScapeInstance {
     /** Begin sounding at audio time `at` (usually ctx.currentTime). */