@joewinke/jatui 0.61.0 → 0.62.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, 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`.
 
 ### Sound (first-class sibling of motion)
 

package/dist/ambience/index.d.ts

@@ -11,13 +11,13 @@
  */
 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';

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,7 +25,7 @@ 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';

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

@@ -73,6 +73,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;
@@ -159,3 +164,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

@@ -657,7 +657,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 +680,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}`;
+}

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,10 @@ 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;
 }
 /** An Ambience whose playback is shared across tabs (see module doc). */
 export interface SharedAmbience extends Ambience {
@@ -105,8 +134,10 @@ 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. */
+    setNowPlaying(line: string | null, trackIndex?: number | null, position?: number | null, duration?: number | null, title?: string | null, download?: SharedTrackDownload | 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;

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,8 @@ export function createSharedAmbience(options = {}) {
     let nowPlayingTitle = null;
     let nowPlayingPosition = null;
     let nowPlayingDuration = null;
+    /** The published track's download info (jatui-0vxcu). */
+    let nowPlayingDownload = null;
     const ambienceSubs = new Set();
     const sharedSubs = new Set();
     function sharedState() {
@@ -137,7 +161,8 @@ 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)
         };
     }
     function ambienceState() {
@@ -206,6 +231,7 @@ export function createSharedAmbience(options = {}) {
         nowPlayingTitle = null;
         nowPlayingPosition = null;
         nowPlayingDuration = null;
+        nowPlayingDownload = null;
         remoteS = null;
         if (heartbeatTimer) {
             clearInterval(heartbeatTimer);
@@ -404,7 +430,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();
                 }
@@ -487,7 +513,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 +597,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
@@ -697,12 +723,13 @@ export function createSharedAmbience(options = {}) {
         setVolume,
         setMuted,
         toggleMute,
-        setNowPlaying(line, index, position, duration, title) {
+        setNowPlaying(line, index, position, duration, title, download) {
             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;
             if (role === 'leader') {
                 publish();
                 emitShared();

package/dist/components/AmbienceToggle.svelte

@@ -32,6 +32,16 @@
 	 *     focus) get the play/pause control only. The transport joins the
 	 *     menu's roving order; a paused row stays visible (its play button is
 	 *     the resume) and a stopped one hides.
+	 *   - Playlists whose licence permits redistribution (jatui-0vxcu: CC0,
+	 *     public domain, CC-BY, CC-BY-SA — never NC/ND unless the manifest
+	 *     marks the track `downloadable: true`) also get a Download button
+	 *     next to the transport: the track url is fetched to a Blob (a plain
+	 *     cross-origin `<a download>` is ignored), saved under
+	 *     "Composer - Title.ext" so attribution travels with the file, and a
+	 *     CORS failure falls back to opening the url in a new tab. The busy
+	 *     spinner never blocks playback. Shared mode: a remote tab downloads
+	 *     the leader's published track url (`SharedAmbienceState.trackDownload`)
+	 *     — or hides the button when the leader published none.
 	 *   - A playing playlist shows its current track's attribution (title,
 	 *     composer, license) under the playlist item and its section row.
 	 *   - With a menu or submenu open, the mouse wheel over that surface
@@ -233,8 +243,18 @@
 	import { getMotionContext } from '../motion/level';
 	import { isAmbienceLink, safeAmbienceHref } from '../ambience/groups';
 	import { isPlaylistScape, type PlaylistState } from '../ambience/scapes/playlist';
+	import {
+		isTrackDownloadable,
+		trackDownloadFilename
+	} from '../ambience/scapes/playlist';
+	import IconButton from './IconButton.svelte';
+	import { safeSharedTrackDownload } from '../ambience/shared';
+	import type {
+		SharedAmbience,
+		SharedAmbienceState,
+		SharedTrackDownload
+	} from '../ambience/shared';
 	import type { Ambience, AmbienceLink, Scape } from '../ambience/types';
-	import type { SharedAmbience, SharedAmbienceState } from '../ambience/shared';
 
 	let {
 		engine,
@@ -252,6 +272,8 @@
 	const menuId = $props.id();
 	const hintId = `${menuId}-hint`;
 	const subId = `${menuId}-sub`;
+	/** The download button's licence/source description line (jatui-0vxcu). */
+	const downloadHintId = `${menuId}-dl`;
 
 	/** Long-press duration for the pointer path to the menu. */
 	const LONG_PRESS_MS = 450;
@@ -309,6 +331,14 @@
 	let sharedTitle = $state<string | null>(null);
 	let sharedPosition = $state<number | null>(null);
 	let sharedDuration = $state<number | null>(null);
+	/** The leader's published download info (jatui-0vxcu) — a remote tab's
+	 *  download button reads this; null hides the button (not published, or
+	 *  the licence forbids redistribution). */
+	let sharedDownload = $state<SharedTrackDownload | null>(null);
+	/** True while a download fetch is in flight — the button shows its busy
+	 *  spinner and refuses re-entry. The fetch runs beside playback; nothing
+	 *  here touches the engine. */
+	let downloadBusy = $state(false);
 
 	// Wheel-volume accumulator over the open surfaces (jatui-xomny): carries
 	// the pending partial notch between wheel events so trackpad pixel deltas
@@ -360,6 +390,46 @@
 	);
 	const npPercent = $derived(progressPercent(npPosition, npDuration));
 
+	// --- download button (jatui-0vxcu) ---------------------------------------
+	/** What the download button offers right now: the playing (or paused)
+	 *  playlist track's url + ready-made filename + licence, gated by the
+	 *  licence AND by `safeAmbienceHref` — the url has to be an absolute
+	 *  http(s) one, because it is fetched and (on CORS failure) opened in a
+	 *  new tab; a `javascript:`/`data:`/scheme-relative entry means no button.
+	 *  On a remote tab the leader's publication is re-validated the same way
+	 *  (the leader is another tab, not a trusted source) — null → no button.
+	 *  Generative scapes never have one. */
+	const currentDownload = $derived.by(() => {
+		if (!showNowPlaying) return null;
+		if (isRemote) return safeSharedTrackDownload(sharedDownload);
+		const t = currentIsPlaylist ? (playlist?.track ?? null) : null;
+		if (!t || !isTrackDownloadable(t)) return null;
+		const url = safeAmbienceHref(t.url);
+		if (!url) return null;
+		return {
+			url,
+			filename: trackDownloadFilename(t),
+			license: t.license,
+			sourceUrl: t.sourceUrl
+		} satisfies SharedTrackDownload;
+	});
+	/** The button's tooltip: licence + source link — CC-BY needs attribution. */
+	const downloadTooltip = $derived(
+		currentDownload
+			? `Download ${currentDownload.filename} · ${currentDownload.license}${
+					currentDownload.sourceUrl ? ` · source: ${currentDownload.sourceUrl}` : ''
+				}`
+			: ''
+	);
+	/** The sr-only line the button's aria-describedby points at. */
+	const downloadHint = $derived(
+		currentDownload
+			? `Download as ${currentDownload.filename}. Licence: ${currentDownload.license}.${
+					currentDownload.sourceUrl ? ` Source: ${currentDownload.sourceUrl}.` : ''
+				}`
+			: ''
+	);
+
 	const BUTTON_SIZE = $derived(compact ? 'size-10' : 'size-11');
 	const ICON_SIZE = $derived(compact ? 18 : 20);
 
@@ -399,6 +469,7 @@
 			sharedTitle = s.trackTitle;
 			sharedPosition = s.trackPosition;
 			sharedDuration = s.trackDuration;
+			sharedDownload = s.trackDownload ?? null;
 		});
 	});
 
@@ -416,12 +487,25 @@
 		return item.subscribe((s) => {
 			playlist = s;
 			track = s.status === 'playing' ? s.track : null;
+			// The download rides the same publication (jatui-0vxcu): only a track
+			// whose licence permits redistribution AND whose url survives
+			// safeAmbienceHref (absolute http/https) is offered to the other tabs.
+			const t = s.status === 'playing' ? s.track : null;
+			const dlUrl = t && isTrackDownloadable(t) ? safeAmbienceHref(t.url) : null;
 			engine.setNowPlaying?.(
-				s.status === 'playing' && s.track ? nowPlayingLine(s.track) : null,
+				s.status === 'playing' && t ? nowPlayingLine(t) : null,
 				s.index,
 				s.status === 'playing' ? s.position : null,
 				s.status === 'playing' ? s.duration : null,
-				s.track?.title ?? null
+				s.track?.title ?? null,
+				t && dlUrl
+					? {
+							url: dlUrl,
+							filename: trackDownloadFilename(t),
+							license: t.license,
+							...(t.sourceUrl ? { sourceUrl: t.sourceUrl } : {})
+						}
+					: null
 			);
 		});
 	});
@@ -682,6 +766,47 @@
 		if (isPlaylistScape(currentItem)) currentItem.skip();
 	}
 
+	/**
+	 * The download button (jatui-0vxcu). A cross-origin `<a download>` is
+	 * ignored by browsers, so the file is fetched to a Blob and saved through
+	 * an object URL — the attribution filename was built by the pure helper.
+	 * A failed fetch (CORS) falls back to opening the url in a new tab. Both
+	 * the fetch and the fallback go through `safeAmbienceHref` — a url that
+	 * is not absolute http(s) (a hostile manifest, or a hostile shared-mode
+	 * leader) never reaches `window.open`. The fetch runs beside the engine —
+	 * playback is never blocked or touched.
+	 */
+	async function onDownloadClick() {
+		const info = currentDownload;
+		const href = safeAmbienceHref(info?.url);
+		if (!info || !href || downloadBusy) return;
+		downloadBusy = true;
+		try {
+			const res = await fetch(href);
+			if (!res.ok) throw new Error(`HTTP ${res.status}`);
+			const blob = await res.blob();
+			const objectUrl = URL.createObjectURL(blob);
+			const a = document.createElement('a');
+			a.href = objectUrl;
+			a.download = info.filename;
+			document.body.appendChild(a);
+			a.click();
+			a.remove();
+			// The browser has the blob reference the moment it accepts the
+			// download; the revoke is belt-and-braces housekeeping.
+			setTimeout(() => URL.revokeObjectURL(objectUrl), 10_000);
+		} catch {
+			// CORS refused or the network failed — the url still opens.
+			try {
+				window.open(href, '_blank', 'noopener,noreferrer');
+			} catch {
+				/* a blocked popup is not worth crashing over */
+			}
+		} finally {
+			downloadBusy = false;
+		}
+	}
+
 	// --- wheel volume over the open surfaces (jatui-xomny) -------------------
 	// While the menu (or one of its submenus) is open the wheel adjusts volume
 	// instead of scrolling the page — EXCEPT over a scrollable list that can
@@ -1064,7 +1189,67 @@
 								</svg>
 							</button>
 						{/if}
+						{#if currentDownload}
+							<!-- Download (jatui-0vxcu): only for tracks whose licence
+							     permits redistribution (or the leader's published url
+							     on a remote tab). aria-describedby points at the
+							     licence line below — the tooltip's own action also
+							     rewrites describedby while it shows, so the line stays
+							     in the row as readable content either way. -->
+							<IconButton
+								label="Download {npTitle}"
+								variant="ghost"
+								size="sm"
+								shape="circle"
+								tooltip={downloadTooltip}
+								tooltipPlacement="top"
+								aria-describedby={downloadHintId}
+								tabindex={-1}
+								data-ambience-nav
+								disabled={downloadBusy}
+								onclick={onDownloadClick}
+							>
+								{#if downloadBusy}
+									<!-- busy: the fetch is in flight (playback unaffected) -->
+									<svg
+										xmlns="http://www.w3.org/2000/svg"
+										viewBox="0 0 24 24"
+										fill="none"
+										stroke="currentColor"
+										stroke-width="2"
+										stroke-linecap="round"
+										class="jatui-dl-spin size-4"
+										aria-hidden="true"
+									>
+										<circle cx="12" cy="12" r="9" opacity="0.25" />
+										<path d="M21 12a9 9 0 0 0-9-9" />
+									</svg>
+								{:else}
+									<!-- download, lucide geometry -->
+									<svg
+										xmlns="http://www.w3.org/2000/svg"
+										viewBox="0 0 24 24"
+										fill="none"
+										stroke="currentColor"
+										stroke-width="2"
+										stroke-linecap="round"
+										stroke-linejoin="round"
+										class="size-4"
+										aria-hidden="true"
+									>
+										<path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" />
+										<polyline points="7 10 12 15 17 10" />
+										<line x1="12" y1="15" x2="12" y2="3" />
+									</svg>
+								{/if}
+							</IconButton>
+						{/if}
 					</div>
+					{#if currentDownload}
+						<!-- The licence + source the download carries — CC-BY needs
+						     attribution, so the filename alone is not enough. -->
+						<p id={downloadHintId} class="sr-only">{downloadHint}</p>
+					{/if}
 				</div>
 			{/if}
 
@@ -1315,5 +1500,20 @@
 		.now-progress-fill {
 			transition: none;
 		}
+		.jatui-dl-spin {
+			animation: none;
+		}
+	}
+
+	/* The download button's busy spinner — task feedback, not ambient motion,
+	 * but it still holds still under reduced motion. */
+	.jatui-dl-spin {
+		animation: jatui-dl-rotate 900ms linear infinite;
+	}
+
+	@keyframes jatui-dl-rotate {
+		to {
+			transform: rotate(360deg);
+		}
 	}
 </style>

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

@@ -31,6 +31,16 @@
  *     focus) get the play/pause control only. The transport joins the
  *     menu's roving order; a paused row stays visible (its play button is
  *     the resume) and a stopped one hides.
+ *   - Playlists whose licence permits redistribution (jatui-0vxcu: CC0,
+ *     public domain, CC-BY, CC-BY-SA — never NC/ND unless the manifest
+ *     marks the track `downloadable: true`) also get a Download button
+ *     next to the transport: the track url is fetched to a Blob (a plain
+ *     cross-origin `<a download>` is ignored), saved under
+ *     "Composer - Title.ext" so attribution travels with the file, and a
+ *     CORS failure falls back to opening the url in a new tab. The busy
+ *     spinner never blocks playback. Shared mode: a remote tab downloads
+ *     the leader's published track url (`SharedAmbienceState.trackDownload`)
+ *     — or hides the button when the leader published none.
  *   - A playing playlist shows its current track's attribution (title,
  *     composer, license) under the playlist item and its section row.
  *   - With a menu or submenu open, the mouse wheel over that surface
@@ -141,8 +151,8 @@ export declare function wheelVolumeSteps(acc: {
  * slider itself would produce for the same value.
  */
 export declare function volumeAfterSteps(volume: number, steps: number, stepPct?: number): number;
-import type { Ambience } from '../ambience/types';
 import type { SharedAmbience } from '../ambience/shared';
+import type { Ambience } from '../ambience/types';
 type $$ComponentProps = {
     /** The engine instance (from `createAmbience()`). The component never creates one, and never kills it — the host owns the engine's lifecycle. Section order/labels come from the engine's `groups` option. With the cross-tab shared player (jatui-lm1mf, `createAmbience({ shared: true })`) a plain `Ambience` is also accepted: the shared now-playing line is only read when the engine publishes one. */
     engine: Ambience | SharedAmbience;

package/dist/index.d.ts

@@ -423,4 +423,5 @@ export type { SharedAmbience, SharedAmbienceState, SharedAmbienceOptions } from
 export type { Ambience, AmbienceGroupDef, AmbienceItem, AmbienceLink, AmbienceOptions, AmbienceState, BreathState, Scape, ScapeContext, ScapeGroup, ScapeInstance } from './ambience';
 export { createPlaylistScape } from './ambience';
 export { isPlaylistScape, trackAttribution } from './ambience';
+export { trackLicenseAllowsRedistribution, isTrackDownloadable, trackDownloadFilename } from './ambience';
 export type { PlaylistScape, PlaylistScapeOptions, PlaylistManifest, PlaylistState, PlaylistStatus, PlaylistTrack } from './ambience';

package/dist/index.js

@@ -469,3 +469,7 @@ export { createAmbience, createAmbienceLocal, createSharedAmbience, AMBIENCE_CHA
 // createPlaylistScape() and register on the engine yourself.
 export { createPlaylistScape } from './ambience';
 export { isPlaylistScape, trackAttribution } from './ambience';
+// Download gate + filename builder (jatui-0vxcu) — the licence allowlist
+// (CC0 / public domain / CC-BY / CC-BY-SA), the per-track override and the
+// "Composer - Title.ext" name attribution travels under.
+export { trackLicenseAllowsRedistribution, isTrackDownloadable, trackDownloadFilename } from './ambience';

package/package.json

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