@joewinke/jatui 0.62.0 → 0.63.0

package/CLAUDE.md

@@ -336,7 +336,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 = 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; plus a Download IconButton for tracks whose licence permits redistribution — allowlist CC0/public-domain/CC-BY/CC-BY-SA via `isTrackDownloadable` (NC/ND refused unless the manifest flags `downloadable: true`); the url must survive `safeAmbienceHref` (absolute http/https — before the fetch AND the new-tab CORS-failure fallback; remotes re-validate the leader's publication via `safeSharedTrackDownload`); fetch→Blob→`a[download="Composer - Title.ext"]` (`trackDownloadFilename`); licence + source in the tooltip and the `aria-describedby` line; busy spinner never blocks playback) + 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/trackDownload`) and route pause/resume/skip/prev via commands. Helpers: `groupAmbienceItems`, `isAmbienceLink`, `isPlaylistScape`, `trackAttribution`, `isTrackDownloadable`, `trackLicenseAllowsRedistribution`, `trackDownloadFilename`, `safeSharedTrackDownload`, `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, and a shuffle / prev / play-pause / next transport — the Shuffle toggle is an `aria-pressed` IconButton, persisted per station and defaulting to the scape's registered `shuffle` option; a session's order is FRESHLY shuffled — never the engine's scape-id-seeded rand, which made every session identical — with recently-heard tracks pushed to the end of the new order (no-repeat across sessions; per-station recents in localStorage `jatui:ambience:recents:<id>`, guarded, capped `RECENTS_CAP` 200 by track url; the window resets once the whole station has been heard) — `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; plus a Download IconButton for tracks whose licence permits redistribution — allowlist CC0/public-domain/CC-BY/CC-BY-SA via `isTrackDownloadable` (NC/ND refused unless the manifest flags `downloadable: true`); the url must survive `safeAmbienceHref` (absolute http/https — before the fetch AND the new-tab CORS-failure fallback; remotes re-validate the leader's publication via `safeSharedTrackDownload`); fetch→Blob→`a[download="Composer - Title.ext"]` (`trackDownloadFilename`); licence + source in the tooltip and the `aria-describedby` line; busy spinner never blocks playback) + 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, streamUrl?})` registers an OUTBOUND LINK item (new tab, `rel="noopener noreferrer"`, external glyph, http(s) only) — streams are never relayed. With a public `streamUrl` (absolute http(s) via `safeAmbienceHref`; a bad scheme is refused and degrades to the link) the station becomes a PLAYABLE scape (`scapes/radio.ts`, `isRadioScape`): the browser fetches the stream client-side through a plain `<audio>` element — deliberately outside the Web Audio graph (a MediaElementSourceNode without CORS headers is silenced by the tainted-graph rule, and station streams rarely send CORS) — with loudness mirroring the engine master via the optional `ScapeContext.volume` hook (`el.volume = gain × master`, refreshed each lookahead tick, so volume + cross-tab mute still apply); the now-playing row shows the station name, the `Open station site` attribution link and an error line when the stream stalls; play/pause only. `createPlaylistScape({ …, group? })` (default `'music'`); a playing playlist shows title — composer · license and exposes `state().position/duration/shuffle` + `skip()`/`prev()`/`setShuffle()`. `engine.list()` = playable scapes, `engine.items()` = scapes + links. Shared mode: remotes render the leader's published now-playing parts (`trackTitle/trackPosition/trackDuration/trackDownload/trackShuffle`) and route pause/resume/skip/prev/shuffle via commands. Helpers: `groupAmbienceItems`, `isAmbienceLink`, `isPlaylistScape`, `isRadioScape`, `trackAttribution`, `isTrackDownloadable`, `trackLicenseAllowsRedistribution`, `trackDownloadFilename`, `safeSharedTrackDownload`, `safeAmbienceHref`. Demo: `/components/ambience-toggle`.
 
 ### Sound (first-class sibling of motion)
 

package/dist/ambience/README.md

@@ -49,7 +49,8 @@ inline `tracks` or a `manifestUrl`:
 | `manifestUrl` | Fetched **once, lazily, on the first play** — never at import. A failed fetch is not cached; the next play retries it. |
 | `tracks` | Inline track list — no fetch at all (resolved eagerly, a pure local filter). |
 | `crossfade` | Track-to-track crossfade in seconds, 0–30 (default 3). |
-| `shuffle` | Fisher–Yates play order over the engine's per-scape PRNG (default off). `setShuffle()` toggles live: the current track stays, the rest reorder. |
+| `shuffle` | Fisher–Yates play order (default off). `setShuffle()` toggles live: the current track stays, the rest reorder. The order is FRESH per session — a crypto-seeded source (`freshShuffleRand()`), never the engine's scape-id-seeded rand, which produced the same "shuffled" order every session (jatui-plbzq). Recently-heard tracks close the new order (no-repeat across sessions, see below). The toggle state persists per station (`jatui:ambience:shuffle:<id>`) and the scape's registered `shuffle` stays the default until the listener toggles. |
+| `shuffleRand` | Injectable shuffle source for tests (default: a fresh `freshShuffleRand()` per play). |
 | `gain` | Initial gain of the scape mix into the master chain, 0–1 (default 1). `setParam('gain', v)` ramps it live. |
 | `fetchFn`, `createMediaElement` | Injectable for tests (default `fetch` / `new Audio(url)`). |
 
@@ -91,6 +92,17 @@ serving the audio must send CORS headers** (`Access-Control-Allow-Origin`);
 a non-CORS source then fails loudly per track (the scape skips to the next
 track) instead of playing silence into a tainted graph.
 
+### No-repeat across sessions (jatui-plbzq)
+
+Every track that starts sounding is remembered per station: localStorage
+`jatui:ambience:recents:<scapeId>` (guarded try/catch, capped at
+`RECENTS_CAP` = 200, ids are the tracks' urls — so the memory is shared
+across tabs of the same origin). A shuffled order leads with unheard
+tracks and closes with the recently-heard ones, so a returning listener
+does not hear the same first tracks; when the WHOLE station has been
+heard the window resets and a plain fresh shuffle plays. The rule applies
+at play start, on cycle wrap and on a mid-play `setShuffle(true)`.
+
 ### Behavior notes
 
 - Two ping-pong slots (element + source node + gain each) are **built once per
@@ -125,10 +137,42 @@ scape.subscribe((s) => {
 });
 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.setShuffle(true); // persisted per station; state().shuffle reports it
 scape.tracks(); // resolved list, or null until the manifest resolved
 ```
 
+## Radio stream scape — a station's public stream in the player (jatui-plbzq)
+
+`src/lib/ambience/scapes/radio.ts` — `radioStation({ id, label, href,
+streamUrl })` builds an outbound link as before when `streamUrl` is
+absent; with one, it builds a PLAYABLE scape: the station's public
+stream, fetched by the BROWSER from the station (never relayed, never
+proxied through the host).
+
+- The stream url must be an absolute http(s) one (`safeAmbienceHref`) —
+  a bad scheme is refused with a console warning and the station degrades
+  to its link behavior. The station-site `href` stays the attribution
+  target (validated again when the row renders).
+- The element is a plain `<audio>`, deliberately OUTSIDE the Web Audio
+  graph: a `MediaElementAudioSourceNode` without CORS headers is silenced
+  by the tainted-graph rule, and station streams rarely send
+  `Access-Control-Allow-Origin` (a `crossOrigin='anonymous'` load would
+  fail outright). Loudness mirrors the engine through the optional
+  `ScapeContext.volume` hook: `el.volume = scape gain × master volume`,
+  refreshed on the lookahead tick — so the volume slider and cross-tab
+  mute apply. A stop fades the element volume in steps, wall-clock.
+- The scape's `state()`/`subscribe()` surface (`radio: true`) reports
+  `status`, `station`, `href` and an `error` line for a stream that
+  stalls or dies. The toggle renders the station name, an
+  `Open station site` link and play/pause only.
+- `createRadioStreamScape()` is the low-level factory (throws on a bad
+  `streamUrl`); `radioStation()` is the public shape that picks link vs
+  scape.
+
+**The host is responsible for a station's terms**: only add a
+`streamUrl` for stations that publish their stream and allow third-party
+players — jatui never relays audio and never claims the right to play.
+
 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, and (jatui-153tz) a

package/dist/ambience/engine.js

@@ -182,7 +182,10 @@ export function createAmbience(options = {}) {
             lookahead: scheduleLookaheadFor(instCbs),
             // Fresh PRNG per build: a shared stream would interleave between the
             // outgoing and incoming scape during a crossfade.
-            rand: makeRand(id)
+            rand: makeRand(id),
+            // The live master volume — a scape that plays OUTSIDE the graph (a
+            // radio stream's plain element) mirrors it onto el.volume (jatui-plbzq).
+            volume: () => volume
         };
         let inst;
         try {

package/dist/ambience/groups.d.ts

@@ -29,17 +29,13 @@ export declare function ambienceGroupLabel(group: ScapeGroup, defs?: readonly Am
  * groups appended in first-seen order.
  */
 export declare function groupAmbienceItems<T extends AmbienceItem>(items: readonly T[], groups?: ReadonlyArray<ScapeGroup | AmbienceGroupDef>): AmbienceSection<T>[];
-/** Build a radio-station link item (group 'radio' unless the host says otherwise). */
-export declare function radioStation(options: {
-    id: string;
-    label: string;
-    href: string;
-    description?: string;
-    group?: ScapeGroup;
-}): AmbienceLink;
 /**
  * The href the toggle may open: absolute http(s) only. A `javascript:` or
  * `data:` href from a host's station list would run in the page, so it is
  * refused (null) and the item renders disabled.
+ *
+ * `radioStation()` (the station-item factory, optionally WITH a playable
+ * `streamUrl`) lives in `./scapes/radio` — it needs the stream scape, and
+ * this module must stay import-free of the scapes.
  */
 export declare function safeAmbienceHref(href: string | null | undefined): string | null;

package/dist/ambience/groups.js

@@ -69,21 +69,14 @@ export function groupAmbienceItems(items, groups) {
     }
     return out;
 }
-/** Build a radio-station link item (group 'radio' unless the host says otherwise). */
-export function radioStation(options) {
-    return {
-        kind: 'link',
-        id: options.id,
-        label: options.label,
-        group: options.group ?? 'radio',
-        href: options.href,
-        description: options.description
-    };
-}
 /**
  * The href the toggle may open: absolute http(s) only. A `javascript:` or
  * `data:` href from a host's station list would run in the page, so it is
  * refused (null) and the item renders disabled.
+ *
+ * `radioStation()` (the station-item factory, optionally WITH a playable
+ * `streamUrl`) lives in `./scapes/radio` — it needs the stream scape, and
+ * this module must stay import-free of the scapes.
  */
 export function safeAmbienceHref(href) {
     if (typeof href !== 'string')

package/dist/ambience/index.d.ts

@@ -22,6 +22,7 @@ export type { PlaylistScape, PlaylistScapeOptions, PlaylistManifest, PlaylistSta
 export { BreathClock, BREATHS_PER_MINUTE } from './breath';
 export { MASTER } from './master';
 export { ScapeRegistry } from './registry';
-export { AMBIENCE_DEFAULT_GROUP_ORDER, AMBIENCE_DEFAULT_GROUP_LABELS, groupAmbienceItems, ambienceGroupLabel, isAmbienceLink, normalizeAmbienceGroups, radioStation, safeAmbienceHref } from './groups';
+export { AMBIENCE_DEFAULT_GROUP_ORDER, AMBIENCE_DEFAULT_GROUP_LABELS, groupAmbienceItems, ambienceGroupLabel, isAmbienceLink, normalizeAmbienceGroups, safeAmbienceHref } from './groups';
 export type { AmbienceSection } from './groups';
+export { radioStation, createRadioStreamScape, isRadioScape, RADIO, type RadioStreamScape, type RadioStreamScapeOptions, type RadioStreamState, type RadioStreamStatus } from './scapes/radio';
 export type { Ambience, AmbienceGroupDef, AmbienceItem, AmbienceLink, AmbienceOptions, AmbienceState, BreathState, Scape, ScapeContext, ScapeGroup, ScapeInstance } from './types';

package/dist/ambience/index.js

@@ -29,5 +29,10 @@ export { createPlaylistScape, isPlaylistScape, trackAttribution, trackLicenseAll
 export { BreathClock, BREATHS_PER_MINUTE } from './breath';
 export { MASTER } from './master';
 export { ScapeRegistry } from './registry';
-// Menu sections + outbound radio links (jatui-mdq2p).
-export { AMBIENCE_DEFAULT_GROUP_ORDER, AMBIENCE_DEFAULT_GROUP_LABELS, groupAmbienceItems, ambienceGroupLabel, isAmbienceLink, normalizeAmbienceGroups, radioStation, safeAmbienceHref } from './groups';
+// Menu sections + the outbound-radio-link helpers (jatui-mdq2p).
+export { AMBIENCE_DEFAULT_GROUP_ORDER, AMBIENCE_DEFAULT_GROUP_LABELS, groupAmbienceItems, ambienceGroupLabel, isAmbienceLink, normalizeAmbienceGroups, safeAmbienceHref } from './groups';
+// Radio stream scape (jatui-plbzq) — a radioStation() with a public
+// streamUrl plays the station's stream right in the player (client-side
+// fetch from the station, never relayed); without one it is the outbound
+// link it always was.
+export { radioStation, createRadioStreamScape, isRadioScape, RADIO } from './scapes/radio';

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

@@ -37,6 +37,22 @@
  * registry (jatui-poq30).
  */
 import type { Scape, ScapeGroup } from '../types';
+/** Cap on the recently-played list per station — at ~200 entries a station
+ *  remembers the last 200 heard tracks; a longer station simply never hits
+ *  the cap (the no-repeat window is then always "the last 200"). */
+export declare const RECENTS_CAP = 200;
+/**
+ * A FRESH random source for one session's shuffle order (jatui-plbzq):
+ * seeded once from crypto.getRandomValues, then streamed as mulberry32 —
+ * the same PRNG quality the engine uses, but never the same twice.
+ *
+ * The engine's per-scape rand is seeded by the SCAPE ID, so shuffling with
+ * it produced the identical order every session — the bug that started
+ * this. The seeded rand stays available for tests through
+ * `PlaylistScapeOptions.shuffleRand` (and the pure helpers below still
+ * take any `rand` injection); the default here is the fresh source.
+ */
+export declare function freshShuffleRand(): () => number;
 export declare const PLAYLIST: Readonly<{
     /** Crossfade between consecutive tracks (s). */
     CROSSFADE: 3;
@@ -99,6 +115,11 @@ export interface PlaylistState {
     /** Total seconds of the current track (0 until metadata reports one —
      *  a stream without a duration stays 0). */
     duration: number;
+    /** Whether shuffled play is on right now (jatui-plbzq) — the transport's
+     *  Shuffle toggle reads it and `setShuffle()` writes it. Persisted per
+     *  station; the initial value is the stored preference, else the
+     *  scape's `shuffle` option (stations register with `shuffle: true`). */
+    shuffle: boolean;
     /** Present on error. */
     error?: string;
 }
@@ -116,9 +137,16 @@ export interface PlaylistScapeOptions {
     tracks?: PlaylistTrack[];
     /** Track crossfade (s), 0–30. Default 3. */
     crossfade?: number;
-    /** Randomized play order (Fisher–Yates over the engine's per-scape rand).
-     *  Default false. Takes effect for the running order immediately. */
+    /** Randomized play order (Fisher–Yates). Default false. Takes effect
+     *  for the running order immediately. Since jatui-plbzq the order is
+     *  FRESH per session — never the engine's seeded rand, which produced
+     *  the same "shuffled" order every session — and recently-heard tracks
+     *  are pushed to the end of the new order (no-repeat). */
     shuffle?: boolean;
+    /** Injectable shuffle source for tests (default: a fresh unseeded
+     *  `freshShuffleRand()` per play). Passed the same way the old seeded
+     *  engine rand was, so order assertions stay deterministic. */
+    shuffleRand?: () => number;
     /** Initial gain of the scape mix into the master chain, 0..1. Default 1. */
     gain?: number;
     /** Injectable for tests (default `fetch`). */

package/dist/ambience/scapes/playlist.js

@@ -1,3 +1,114 @@
+// ---- shuffle randomness + no-repeat memory (jatui-plbzq) --------------------
+/** Cap on the recently-played list per station — at ~200 entries a station
+ *  remembers the last 200 heard tracks; a longer station simply never hits
+ *  the cap (the no-repeat window is then always "the last 200"). */
+export const RECENTS_CAP = 200;
+function recentsKey(scapeId) {
+    return `jatui:ambience:recents:${scapeId}`;
+}
+function shufflePrefKey(scapeId) {
+    return `jatui:ambience:shuffle:${scapeId}`;
+}
+/** The recently-played track ids for a station, most recent first. Guarded
+ *  try/catch (private mode / disabled storage / SSR → empty — the shuffle
+ *  still works, it just repeats across sessions). */
+function loadRecents(scapeId) {
+    try {
+        if (typeof localStorage === 'undefined')
+            return new Set();
+        const raw = localStorage.getItem(recentsKey(scapeId));
+        if (!raw)
+            return new Set();
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return new Set();
+        return new Set(parsed.filter((s) => typeof s === 'string'));
+    }
+    catch {
+        return new Set();
+    }
+}
+function saveRecents(scapeId, ids) {
+    try {
+        if (typeof localStorage === 'undefined')
+            return;
+        localStorage.setItem(recentsKey(scapeId), JSON.stringify(ids.slice(0, RECENTS_CAP)));
+    }
+    catch {
+        /* private mode / quota — persistence is best-effort */
+    }
+}
+/** A track just started sounding: move its id to the front of the station's
+ *  recents (dedup, capped). The station ids the track by its url — stable
+ *  across sessions and, since recents live in localStorage, across tabs. */
+function recordPlayed(scapeId, trackId) {
+    const list = [...loadRecents(scapeId)];
+    const at = list.indexOf(trackId);
+    if (at !== -1)
+        list.splice(at, 1);
+    list.unshift(trackId);
+    saveRecents(scapeId, list);
+}
+/** The persisted shuffle preference for a station (null = none saved). */
+function loadShufflePref(scapeId) {
+    try {
+        if (typeof localStorage === 'undefined')
+            return null;
+        const raw = localStorage.getItem(shufflePrefKey(scapeId));
+        return raw === '1' ? true : raw === '0' ? false : null;
+    }
+    catch {
+        return null;
+    }
+}
+function saveShufflePref(scapeId, on) {
+    try {
+        if (typeof localStorage === 'undefined')
+            return;
+        localStorage.setItem(shufflePrefKey(scapeId), on ? '1' : '0');
+    }
+    catch {
+        /* private mode / quota — persistence is best-effort */
+    }
+}
+/**
+ * A FRESH random source for one session's shuffle order (jatui-plbzq):
+ * seeded once from crypto.getRandomValues, then streamed as mulberry32 —
+ * the same PRNG quality the engine uses, but never the same twice.
+ *
+ * The engine's per-scape rand is seeded by the SCAPE ID, so shuffling with
+ * it produced the identical order every session — the bug that started
+ * this. The seeded rand stays available for tests through
+ * `PlaylistScapeOptions.shuffleRand` (and the pure helpers below still
+ * take any `rand` injection); the default here is the fresh source.
+ */
+export function freshShuffleRand() {
+    let s;
+    try {
+        const seed = new Uint32Array(1);
+        if (typeof crypto !== 'undefined' && typeof crypto.getRandomValues === 'function') {
+            crypto.getRandomValues(seed);
+            s = seed[0];
+        }
+        else {
+            s = (Math.random() * 0x100000000) >>> 0;
+        }
+    }
+    catch {
+        s = (Math.random() * 0x100000000) >>> 0;
+    }
+    return mulberry32(s || 1);
+}
+function mulberry32(seed) {
+    let s = seed >>> 0;
+    return () => {
+        s = (s + 0x6d2b79f5) >>> 0;
+        let t = s;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
 export const PLAYLIST = Object.freeze({
     /** Crossfade between consecutive tracks (s). */
     CROSSFADE: 3,
@@ -29,7 +140,10 @@ export function createPlaylistScape(options) {
     const crossfade = Math.min(30, Math.max(0, options.crossfade ?? PLAYLIST.CROSSFADE));
     const mixGain0 = Math.min(1, Math.max(0, options.gain ?? 1));
     const fetchFn = options.fetchFn ?? ((url) => fetch(url));
-    let shuffle = options.shuffle ?? false;
+    // Shuffle preference: the stored per-station choice wins, then the
+    // scape's registered default (stations pass shuffle: true — the task's
+    // "default ON for stations" is the host's registration, jatui-plbzq).
+    let shuffle = loadShufflePref(options.id) ?? (options.shuffle ?? false);
     /** Resolved track list — cached across plays (the manifest is fetched once,
      *  on the first play). null = unresolved; a FAILED fetch stays null so the
      *  next play retries. Inline tracks resolve eagerly (a pure local filter —
@@ -46,7 +160,15 @@ export function createPlaylistScape(options) {
         }
     }
     /** Shared UI snapshot + subscribers. Only the latest build writes it. */
-    let snap = { status: 'idle', track: null, index: 0, count: 0, position: 0, duration: 0 };
+    let snap = {
+        status: 'idle',
+        track: null,
+        index: 0,
+        count: 0,
+        position: 0,
+        duration: 0,
+        shuffle
+    };
     const subs = new Set();
     /** Handle to the most recent build — skip()/setShuffle() route here. */
     let latest = null;
@@ -132,6 +254,33 @@ export function createPlaylistScape(options) {
         let order = [];
         let pos = 0;
         let failures = 0;
+        // This play's shuffle source: the injected one (tests) or a FRESH
+        // unseeded draw — never the engine's scape id-seeded rand, which made
+        // every session's "shuffled" order identical (jatui-plbzq root cause).
+        const shuffleRand = options.shuffleRand ?? freshShuffleRand();
+        /** Fresh shuffle order with the no-repeat rule (jatui-plbzq): tracks
+         *  the listener has heard recently close the order, unheard ones lead;
+         *  when the WHOLE station has been heard the recents reset and the
+         *  order is a plain fresh shuffle. */
+        function recentsAwareOrder() {
+            const n = resolved?.length ?? 0;
+            const fresh = shuffledOrder(n, shuffleRand);
+            const heard = loadRecents(options.id);
+            if (heard.size === 0)
+                return fresh;
+            const tracks = resolved;
+            const unheard = [];
+            const recent = [];
+            for (const i of fresh)
+                (heard.has(tracks[i].url) ? recent : unheard).push(i);
+            if (unheard.length === 0) {
+                // The whole station has been heard — the no-repeat window starts
+                // over: clear it and play a plain fresh shuffle.
+                saveRecents(options.id, []);
+                return fresh;
+            }
+            return [...unheard, ...recent];
+        }
         const isLive = () => instId === instanceSeq && !released;
         function atTimer(ms, fn) {
             if (released)
@@ -226,7 +375,7 @@ export function createPlaylistScape(options) {
                 fail(resolveError ?? 'Playlist has no playable tracks');
                 return;
             }
-            order = shuffle ? shuffledOrder(resolved.length, scapeCtx.rand) : plainOrder(resolved.length);
+            order = shuffle ? recentsAwareOrder() : plainOrder(resolved.length);
             pos = 0;
             startTrack(order[0], 'first');
         }
@@ -292,6 +441,9 @@ export function createPlaylistScape(options) {
                 duration: 0,
                 error: undefined
             });
+            // This track is now sounding: it goes on the station's no-repeat
+            // list (most recent first, capped — jatui-plbzq).
+            recordPlayed(options.id, track.url);
             preloadNext();
         }
         function quietSlot(slot) {
@@ -335,17 +487,16 @@ export function createPlaylistScape(options) {
                 return -1;
             return pos + 1 < order.length ? order[pos + 1] : order[0];
         }
-        /** Order for the next cycle; never opens with the track that just
-         *  ended when a swap can avoid it. */
+        /** Order for the next cycle: no-repeat-aware when shuffled (never
+         *  opens with the track that just ended when a swap can avoid it). */
         function wrapOrder(lastPlayed) {
-            const idx = plainOrder(resolved?.length ?? 0);
-            if (shuffle) {
-                shuffleInPlace(idx, scapeCtx.rand);
-                if (idx.length > 1 && idx[0] === lastPlayed) {
-                    const t = idx[0];
-                    idx[0] = idx[1];
-                    idx[1] = t;
-                }
+            if (!shuffle)
+                return plainOrder(resolved?.length ?? 0);
+            const idx = recentsAwareOrder();
+            if (idx.length > 1 && idx[0] === lastPlayed) {
+                const t = idx[0];
+                idx[0] = idx[1];
+                idx[1] = t;
             }
             return idx;
         }
@@ -549,8 +700,8 @@ export function createPlaylistScape(options) {
                 return;
             const current = order[pos] ?? 0;
             if (shuffle) {
-                const rest = plainOrder(resolved.length).filter((i) => i !== current);
-                shuffleInPlace(rest, scapeCtx.rand);
+                // No-repeat-aware rest: recently-heard tracks close the order.
+                const rest = recentsAwareOrder().filter((i) => i !== current);
                 order = [current, ...rest];
                 pos = 0;
             }
@@ -598,6 +749,10 @@ export function createPlaylistScape(options) {
         },
         setShuffle(on) {
             shuffle = on;
+            // The per-station preference (jatui-plbzq): survives sessions and is
+            // read back as the initial value on the next create.
+            saveShufflePref(options.id, on);
+            setSnap({ shuffle: on });
             if (latest && !latest.isReleased())
                 latest.reshuffle();
         },

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;