@joewinke/jatui 0.61.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) + 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`.
+`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

@@ -11,17 +11,18 @@
  */
 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 { createSharedAmbience, AMBIENCE_CHANNEL, AMBIENCE_LOCK, SHARED_TIMING, safeSharedTrackDownload, type SharedAmbience, type SharedAmbienceState, type SharedAmbienceOptions, type SharedChannel, type SharedLockManager, type SharedTrackDownload } from './shared';
 export { createDefaultAmbience, DEFAULT_SCAPES, type DefaultAmbienceOptions } from './default';
 export { hibiscusScape } from './scapes/hibiscus';
 export { focusScape } from './scapes/focus';
 export { noiseScapes, brownNoiseScape, pinkNoiseScape, whiteNoiseScape } from './scapes/noise';
 export { rain, waves } from './scapes/nature';
-export { createPlaylistScape, isPlaylistScape, trackAttribution } from './scapes/playlist';
+export { createPlaylistScape, isPlaylistScape, trackAttribution, trackLicenseAllowsRedistribution, isTrackDownloadable, trackDownloadFilename } from './scapes/playlist';
 export type { PlaylistScape, PlaylistScapeOptions, PlaylistManifest, PlaylistState, PlaylistStatus, PlaylistTrack } from './scapes/playlist';
 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

@@ -13,7 +13,7 @@
 // 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 { createSharedAmbience, AMBIENCE_CHANNEL, AMBIENCE_LOCK, SHARED_TIMING, safeSharedTrackDownload } 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().
@@ -25,9 +25,14 @@ export { rain, waves } from './scapes/nature';
 // recordings. NOTE: never auto-registered in DEFAULT_SCAPES — a playlist is
 // per-host (its manifest URL and licensing claims are the host's); build one
 // with createPlaylistScape() and engine.register() it yourself.
-export { createPlaylistScape, isPlaylistScape, trackAttribution } from './scapes/playlist';
+export { createPlaylistScape, isPlaylistScape, trackAttribution, trackLicenseAllowsRedistribution, isTrackDownloadable, trackDownloadFilename } from './scapes/playlist';
 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;
@@ -73,6 +89,11 @@ export interface PlaylistTrack {
     license: string;
     /** Page where the recording lives — the attribution link target. */
     sourceUrl?: string;
+    /** Explicit download override (jatui-0vxcu): `true` offers the file even
+     *  when the licence string carries NC/ND terms; `false` hides the download
+     *  button even for a redistributable licence. Absent: the licence gate
+     *  (`isTrackDownloadable`) decides from the `license` string. */
+    downloadable?: boolean;
 }
 export interface PlaylistManifest {
     title?: string;
@@ -94,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;
 }
@@ -111,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`). */
@@ -159,3 +192,29 @@ export declare function isPlaylistScape(scape: unknown): scape is PlaylistScape;
  * (performer only when present and different from the composer).
  */
 export declare function trackAttribution(track: PlaylistTrack | null | undefined): string;
+/**
+ * Does this LICENCE STRING permit redistributing the file? The download
+ * allowlist: CC0, the public domain (incl. the Public Domain Mark, and "PD")
+ * and CC-BY / CC-BY-SA. Anything carrying NC (no commercial) or ND (no
+ * derivatives) terms is refused — the host's only way past that is an
+ * explicit `downloadable: true` on the track (`isTrackDownloadable`).
+ * Matching is on tokens, so "CC BY-SA 4.0", "cc-by-sa", "Public Domain" and
+ * "CC0 1.0" all pass while "CC BY-NC", "BY-NC-ND" and unknown strings
+ * (default-deny) do not.
+ */
+export declare function trackLicenseAllowsRedistribution(license: string | null | undefined): boolean;
+/**
+ * May this track be downloaded? The licence gate behind the toggle's
+ * download button (jatui-0vxcu): an explicit boolean `downloadable` on the
+ * track overrides either way; otherwise the `license` string must permit
+ * redistribution (`trackLicenseAllowsRedistribution`). A track without a
+ * usable url is never downloadable.
+ */
+export declare function isTrackDownloadable(track: PlaylistTrack | null | undefined): boolean;
+/**
+ * The download filename — attribution travels with the file:
+ * "<Composer> - <Title>.<ext>". The extension comes from the track url
+ * (`DEFAULT_AUDIO_EXT` when the url carries none). Both parts are
+ * sanitized for real filesystems and the result stays deterministic.
+ */
+export declare function trackDownloadFilename(track: PlaylistTrack | null | undefined): string;

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();
         },
@@ -657,7 +812,8 @@ function isValidTrack(t) {
         o.license.trim() !== '' &&
         (o.performer === undefined || typeof o.performer === 'string') &&
         (o.sourceUrl === undefined ||
-            (typeof o.sourceUrl === 'string' && o.sourceUrl.trim() !== '')));
+            (typeof o.sourceUrl === 'string' && o.sourceUrl.trim() !== '')) &&
+        (o.downloadable === undefined || typeof o.downloadable === 'boolean'));
 }
 /** Narrow a registered scape to a playlist (to reach its state/subscribe). */
 export function isPlaylistScape(scape) {
@@ -679,3 +835,83 @@ export function trackAttribution(track) {
     parts.push(track.license);
     return parts.filter(Boolean).join(' · ');
 }
+// ---- download gate + filename (jatui-0vxcu) ---------------------------------
+/**
+ * Does this LICENCE STRING permit redistributing the file? The download
+ * allowlist: CC0, the public domain (incl. the Public Domain Mark, and "PD")
+ * and CC-BY / CC-BY-SA. Anything carrying NC (no commercial) or ND (no
+ * derivatives) terms is refused — the host's only way past that is an
+ * explicit `downloadable: true` on the track (`isTrackDownloadable`).
+ * Matching is on tokens, so "CC BY-SA 4.0", "cc-by-sa", "Public Domain" and
+ * "CC0 1.0" all pass while "CC BY-NC", "BY-NC-ND" and unknown strings
+ * (default-deny) do not.
+ */
+export function trackLicenseAllowsRedistribution(license) {
+    if (typeof license !== 'string' || license.trim() === '')
+        return false;
+    const l = license.toLowerCase().replace(/[-_.]+/g, ' ').replace(/\s+/g, ' ').trim();
+    // NC / ND terms — as their own tokens ("by nc", "by-nc" → "by nc") or as
+    // the spelled-out words.
+    if (/(^|\s)(nc|nd|noncommercial|non commercial|noderivs|no derivs|no derivatives)(\s|$)/.test(l))
+        return false;
+    return /(^|\s)(cc0|cc by|cc by sa|public domain|pd|pdm)(\s|$)/.test(l);
+}
+/**
+ * May this track be downloaded? The licence gate behind the toggle's
+ * download button (jatui-0vxcu): an explicit boolean `downloadable` on the
+ * track overrides either way; otherwise the `license` string must permit
+ * redistribution (`trackLicenseAllowsRedistribution`). A track without a
+ * usable url is never downloadable.
+ */
+export function isTrackDownloadable(track) {
+    if (!track || typeof track.url !== 'string' || track.url.trim() === '')
+        return false;
+    if (typeof track.downloadable === 'boolean')
+        return track.downloadable;
+    return trackLicenseAllowsRedistribution(track.license);
+}
+/** Cap on one filename part — a "Composer - Title.ext" name stays well under
+ *  the 255-byte filename floor even with long attribution strings. */
+const FILENAME_PART_MAX = 96;
+/** Extension for a url with no readable one — the Musopen-style manifests
+ *  this feature targets serve mp3. */
+const DEFAULT_AUDIO_EXT = 'mp3';
+/** One filename part: filesystem-hostile characters and control chars →
+ *  spaces, runs collapsed, no leading/trailing dots or spaces (Windows
+ *  rejects both), clamped to {@link FILENAME_PART_MAX}. */
+function sanitizeFilenamePart(part) {
+    return part
+        .replace(/[\u0000-\u001f\u007f]/g, ' ')
+        .replace(/[\\/:*?"<>|]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .replace(/^[. ]+|[. ]+$/g, '')
+        .slice(0, FILENAME_PART_MAX)
+        .replace(/[. ]+$/g, ''); // the clamp can re-expose a trailing dot
+}
+/** The audio extension of `url`'s last path segment ('' when there is none
+ *  or it is not 1–5 alphanumeric chars — query strings excluded). */
+function urlAudioExt(url) {
+    if (typeof url !== 'string')
+        return '';
+    const path = url.split(/[?#]/)[0];
+    const file = path.slice(Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\')) + 1);
+    const dot = file.lastIndexOf('.');
+    if (dot <= 0)
+        return '';
+    const ext = file.slice(dot + 1).toLowerCase();
+    return /^[a-z0-9]{1,5}$/.test(ext) ? ext : '';
+}
+/**
+ * The download filename — attribution travels with the file:
+ * "<Composer> - <Title>.<ext>". The extension comes from the track url
+ * (`DEFAULT_AUDIO_EXT` when the url carries none). Both parts are
+ * sanitized for real filesystems and the result stays deterministic.
+ */
+export function trackDownloadFilename(track) {
+    if (!track)
+        return '';
+    const composer = sanitizeFilenamePart(track.composer) || 'Unknown composer';
+    const title = sanitizeFilenamePart(track.title) || 'Untitled';
+    return `${composer} - ${title}.${urlAudioExt(track.url) || DEFAULT_AUDIO_EXT}`;
+}