@joewinke/jatui 0.60.0 → 0.62.0

package/CLAUDE.md

@@ -84,6 +84,9 @@ Then import:
 | `ChartCard` | "Headline + period switch + chart" shell that draws NO chart (bring layerchart / d3 / SVG). The `chart` snippet gets `{ period, hover, hovered }`; call `hover({value, label, delta?})` as the pointer moves and the headline tweens to that point and the caption shows its label; `hover(null)` (or pointer leave) restores the total. Periods use SegmentedControl. | `label`, `value`, `format?`, `delta?`, `invertDelta?`, `caption?`, `periods?`, `period` (bindable), `onPeriodChange?`, `chartHeight?`, `loading?`, `chart` (snippet), `actions?`/`footer?` (snippets) |
 | `BarList` | Ranked horizontal bars ("top pages / top callers"): label + value as text, a decorative token-tinted bar sized against the max, optional `href` or `onSelect` per row, `hint`, per-row `tone`, `limit` + "Show N more". Pure HTML/CSS, no chart lib. | `items: BarListItem[]`, `sort?` (`desc`), `limit?`, `format?`, `formatValue?(item, total)`, `labelHeader?`/`valueHeader?`, `tone?`, `size?`, `onSelect?`, `label?` (snippet) |
 | `ActivityHeatmap` | GitHub-style activity-per-day calendar (calls/day, tasks closed/day): 7 weekday rows × week columns, default range = last 12 months, `weekStart`, 4-step `color-mix` ramp from one theme `tone` (no hex), one floating tooltip, legend + summary ("1,204 calls in the last year"). `role="grid"` with ONE tab stop: arrows move by day (↑↓) / week (←→), PgUp/PgDn 4 weeks, Home/End row ends, mod+Home/End range ends, Enter/Space select. `fill` (default `true`) sizes the cells to the container — pure CSS (`container-type: inline-size` + cqi), clamped 8–20px (`--hm-cell-min`/`--hm-cell-max`), scrolling only below the floor and the legend parked under the grid's right edge; `fill={false}` is the legacy fixed 12px grid (and the one to pass in a shrink-to-fit host, where an inline-size container collapses). Pure layout helpers exported (`buildHeatmap`, `moveHeatFocus`). | `data` (`{date, count}[]` or `getDate`/`getCount`), `start?`/`end?`, `weekStart?`, `unit?` ('call' or ['call','calls']), `formatLabel?`, `tone?`, `levels?`, `levelOf?`, `compact?`, `fill?` (true), `showLegend?`/`showWeekdays?`/`showMonths?`, `summary?`, `selected` (bindable), `onSelectDay?(date, count)`, `locale?` |
+| `UptimeBar` | One component's 90-day status strip (status-page style): one thin bar per day, coloured by status tone (operational green, degraded amber, partial orange, outage red, `no-data` hatched neutral — never coloured as up), a hover/touch/focus tooltip with date + minutes down + incident note, and the footer "90 days ago ——— 99.97% uptime ——— Today" (uptime % truncated to 2 decimals — never overclaims, e.g. 99.996% shows 99.99% never 100%). `role="grid"` with ONE tab stop and roving focus: arrows move by day, PgUp/PgDn by 7, Home/End to the window ends. Bars size to the container width (pure CSS cqi, clamped 3–14px, `--up-bar-min`/`--up-bar-max`); below the floor the strip scrolls horizontally inside the component, starting at the latest day. Token-only colours (`--jatui-status-*` + `color-mix`). Pure helpers exported (`buildUptime`, `moveUptimeFocus`, `uptimeWord`, `bannerStatus`, `aggregateStatus`, `defaultDownMinutes`, `formatUptimePct`). | `data` (`{date, status, downMinutes?, note?}[]`), `days?` (90), `end?`, `label?`, `formatLabel?`, `showUptime?`/`showRangeLabels?` (true), `locale?`, `class?` |
+| `StatusCard` | One measured component on a status page: name + info tooltip (what is measured), status icon at the right, the 90-day `UptimeBar` strip, and the status word (Normal / Degraded / Outage / No data — from the worst status in the window; `statusWord` overrides). | `name`, `description?`, `data`, `days?`, `end?`, `statusWord?`, `locale?`, `class?` |
+| `StatusBanner` | Status page headline banner: "All systems operational" / degraded / outage, token colours, check / warning / x icon. | `status` ('operational' \| 'degraded' \| 'outage'), `message?`, `info?`, `class?` |
 | `StatusBadge` | Status indicator with dot | `status: StatusValue`, `label` |
 | `Card` | Content card container | `title`, `children` (snippet) |
 | `Modal` | Dialog overlay. `zIndex` accepts `number` OR any CSS `z-index` string, including `"var(--z-lightbox)"`. **On open, focus goes to the first fillable field** (WAI-ARIA APG): a `[data-autofocus]`/`autofocus` element, else the first enabled **rendered** text-entry control (readOnly/disabled textareas excluded, unrendered candidates skipped), else the dialog itself — `initialFocus` overrides the order (`'dialog'` restores the old container focus); the focus landing is verified, else the container is focused. When the dialog is the fallback focus, **Escape is owned by the dialog element itself** (not the window handler), so `trapKeys`' stopPropagation can't swallow Esc; a Modal opened inside a host Drawer closes before the drawer. The component ships its own open-state `.modal-box` opacity rule, so it renders under DaisyUI 5 with no host global override. | `open` (bindable), `title`, `children` (snippet), `zIndex?: string \| number`, `trapKeys?`, `closeOnEscape?`, `initialFocus?` |
@@ -333,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/actions/tooltip.d.ts

@@ -15,12 +15,19 @@
  * Accessibility: sets aria-describedby on the host element.
  * Escape key hides the active tooltip.
  * Focus events (focusin/focusout) trigger alongside mouse hover.
+ * Touch/pen: a tap shows the tooltip immediately — only when the host sets
+ * `tapToShow` (default false, so plain buttons and badges don't pop on tap);
+ * the next tap elsewhere hides it.
  */
 export interface TooltipOptions {
     text: string;
     placement?: 'top' | 'bottom' | 'left' | 'right';
     /** ms to wait before showing (default 400). 0 = instant. */
     delayMs?: number;
+    /** Show the tooltip on a touch/pen TAP (default false — only components
+     * that ask for it, e.g. UptimeBar's day bars, pop a tooltip on tap; plain
+     * buttons and badges must not). */
+    tapToShow?: boolean;
 }
 export declare function tooltip(node: HTMLElement, options: TooltipOptions): {
     update(next: TooltipOptions): void;

package/dist/actions/tooltip.js

@@ -15,6 +15,9 @@
  * Accessibility: sets aria-describedby on the host element.
  * Escape key hides the active tooltip.
  * Focus events (focusin/focusout) trigger alongside mouse hover.
+ * Touch/pen: a tap shows the tooltip immediately — only when the host sets
+ * `tapToShow` (default false, so plain buttons and badges don't pop on tap);
+ * the next tap elsewhere hides it.
  */
 const COOL_WINDOW_MS = 500;
 const GAP = 8;
@@ -173,10 +176,29 @@ export function tooltip(node, options) {
         if (e.key === 'Escape')
             hide();
     }
+    let outTap = null;
+    function handlePointerdown(e) {
+        // Touch/pen: there is no hover — a TAP shows the tooltip. Only when the
+        // host asks for it (tapToShow): plain buttons and badges must not pop a
+        // tooltip on every tap. The next tap anywhere else hides it again (the
+        // tooltip itself has pointer-events: none, so the tap always reaches
+        // whatever is under it).
+        if (!opts.tapToShow)
+            return;
+        if (e.pointerType !== 'touch' && e.pointerType !== 'pen')
+            return;
+        scheduleShow();
+        outTap = (e2) => {
+            if (!node.contains(e2.target))
+                hide();
+        };
+        document.addEventListener('pointerdown', outTap, { capture: true, once: true });
+    }
     node.addEventListener('mouseenter', scheduleShow);
     node.addEventListener('mouseleave', hide);
     node.addEventListener('focusin', scheduleShow);
     node.addEventListener('focusout', hide);
+    node.addEventListener('pointerdown', handlePointerdown);
     document.addEventListener('keydown', handleKeydown);
     return {
         update(next) {
@@ -188,10 +210,16 @@ export function tooltip(node, options) {
         },
         destroy() {
             hide();
+            if (outTap) {
+                // The once-listener can outlive the node — remove it explicitly.
+                document.removeEventListener('pointerdown', outTap, { capture: true });
+                outTap = null;
+            }
             node.removeEventListener('mouseenter', scheduleShow);
             node.removeEventListener('mouseleave', hide);
             node.removeEventListener('focusin', scheduleShow);
             node.removeEventListener('focusout', hide);
+            node.removeEventListener('pointerdown', handlePointerdown);
             document.removeEventListener('keydown', handleKeydown);
         },
     };

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();