@joewinke/jatui 0.54.0 → 0.55.0

package/CLAUDE.md

@@ -59,7 +59,7 @@ Then import:
 | `TimeSlotPicker` | Slots grouped morning/afternoon/evening as one `role="radiogroup"` (`role="radio"` + `aria-checked`, full spoken date+time): roving arrows skip unavailable slots, Up/Down jump a visual row, Home/End, Space/Enter choose. Times and grouping follow `timeZone`'s wall clock. | `slots: TimeSlot[]`, `onSelect`, `selectedSlot`, `loading`, `accentColor`, `hourCycle?` ('h12' \| 'h23'), `timeZone?` (IANA), `locale?`, `selectOnFocus?`, `timezone?` (snippet row above the slots) |
 | `BookingScheduler` | Calendly-shaped composition over `CalendarPicker` + `TimeSlotPicker`: details pane (host, duration, location, zone), time-zone select + 12h/24h toggle, slot list, Confirm. Container-query layout (3 panes → 2 → 1). Host supplies data; nothing is booked here. | `getSlots(date, timeZone)` (sync/async, stale responses dropped), `getAvailability?`, `selectedDate`/`selectedSlot`/`timeZone`/`hourCycle` (bindable), `title`, `durationMinutes`, `hostName`, `location`, `description`, `details?` (snippet), `onConfirm(slot, {timeZone})`, `confirming` |
 | `EventCalendar` | Month / week / day / agenda event calendar, engine upstreamed from MOS `CalendarGrid`: one lane allocator per month row (`packWeek`/`computeVisibility`, measured lane capacity), "+N more" expands the week IN PLACE, week/day time grid with side-by-side overlap layout (`layoutDay`) + all-day bar row + now-line, agenda list, month-switcher pill (the shared month panel), details popover snippet, HTML5 drag-to-move, drag- or Shift+arrow range select. Event colours from `--jatui-event-N{,-bg,-fg}`. Generic over your event type. | `events: CalendarEventItem[]` (`{id,title,start,end?,allDay?,color?: 1-6 \| semantic,…}`), `view`/`date` (bindable), `views`, `weekStart`, `locale`, `hourCycle`, `dayStartHour`/`dayEndHour`, `hourHeight`, `height`, `eventDetails?`/`eventContent?`/`toolbarEnd?` (snippets), `moreAction`, `onEventClick`, `onDayClick`, `onCreate(date, hour?)`, `onEventMove(ev, {date, hour?, allDay})`, `onRangeSelect`, `onRangeChange(range, view)` |
-| `CalendarMonthGrid` | The shared month panel every picker uses — exported for custom surfaces. `<table role="grid">`, roving tabindex, range band that bridges cell gaps and rounds at week edges, disabled days stay focusable (`aria-disabled`), `day` snippet + `describeDay` for extra per-day content/name. Pair with `createCalendarGrid()`. | `month`, `focusedDate`, `onFocusDate`, `onSelect`, `selected?`, `range?`, `isDisabled?`, `min`/`max`, `weekStart`, `locale`, `showOutsideDays`, `fixedWeeks`, `size`, `onHover?`, `day?`, `describeDay?` |
+| `CalendarMonthGrid` | The shared month panel every picker uses — exported for custom surfaces. `<table role="grid">`, roving tabindex, range band that bridges cell gaps and rounds at week edges, disabled days stay focusable (`aria-disabled`), `day` snippet + `describeDay` for extra per-day content/name. Pair with `createCalendarGrid()`. | `month`, `focusedDate`, `onFocusDate`, `onSelect`, `selected?`, `range?`, `isDisabled?`, `min`/`max`, `weekStart`, `locale`, `showOutsideDays`, `fixedWeeks`, `size`, `fill?` (true; pass `false` in a `max-content` popover or other shrink-to-fit host — a filling table's max-content is unbounded in Chrome), `onHover?`, `day?`, `describeDay?` |
 | `AvailabilityModal` | Date override editor (modal) | `date`, `overrides`, `onSave`, `onClose` |
 | `BookingForm` | Guest info form for booking | `onSubmit`, `submitting`, `requirePhone`, `accentColor`, `showAttendeeOption` |
 | `CountdownTimer` | Countdown to target date | `targetDate: Date`, `label` |
@@ -330,6 +330,10 @@ const rec = createAudioRecorder({
 // Methods: start() stop() pause() resume() cancel() reset() destroy()
 ```
 
+### 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 = volume + 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. `engine.list()` = playable scapes, `engine.items()` = scapes + links. Helpers: `groupAmbienceItems`, `isAmbienceLink`, `isPlaylistScape`, `trackAttribution`, `safeAmbienceHref`. Demo: `/components/ambience-toggle`.
+
 ### Sound (first-class sibling of motion)
 
 One preferences store every app sound goes through. UI + notification sounds are **off by default** (opt-in); the `incoming-call` ringer is **opt-out** (plays out of the box, muted via `categories.calls`). Semantic names (`confirm`, `error`, `notify`, `message`, `send`, `toggle`, `tap`, `incoming-call`, plus the booking-delight set `tick` 0.03 / `select` 0.08 / `chime` 0.12 / `attention` 0.10) map to bundled CC0 clips or a host's own file (`SOUND_CLIP_VARIANTS['error-soft']` is a gentler `error`). Policy per category: background tab, quiet hours and the quiet/reduced-motion mode silence `ui`/`notifications`; calls always ring. **Throttle:** per-name `minIntervalMs` (tick 80 ms, select 120 ms) drops — never queues — a play inside the window (`blocked: 'throttled'`); per-call `minIntervalMs` overrides. **Pitch:** `playSound('tick', { pitch: pentatonicPitch(i) })` (semitones → `playbackRate`; `playbackRate` also accepted). `tick` is the one hover sound — call it only on pointer-fine devices. **Site level:** host stamps `<html data-sound="off|subtle">` (like `data-motion`; `setSoundLevel` / `resolveSoundLevel` / `soundLevelDefaults`); `subtle` only starts UI sound on for a visitor with no saved preference — a saved preference (the panel mute) always wins, and `decideSound` is unchanged. **iOS unlock:** the player creates its AudioContext lazily (inside clip-decode promise chains), which iOS Safari leaves suspended forever — call `unlockSound()` from inside a user gesture (or `armSoundUnlock()` once for a one-shot first-gesture listener); custom backends implement optional `unlock()` / `unlocked` and the player delegates. Discipline doc: `docs/sound.md`.

package/README.md

@@ -51,8 +51,10 @@ Key contract points:
 ```
 
 Track URLs must be served with CORS headers (they are fetched as `HTMLAudioElement` sources fed into the Web Audio graph), and the host owns the manifest and its licensing claims — an example of public-domain Musopen recordings can be listed with attribution in the scape's `description`.
+- **Menu sections** — `createAmbience({ groups: ['radio', 'focus', 'noise', { id: 'meditation', label: 'Calm' }] })` (also on `createDefaultAmbience`) orders and labels the toggle's sections; groups holding items but missing from the list still render after them. Without it the order is radio / focus / noise / meditation / nature / music. `ScapeGroup` accepts any string, so a host can add its own sections. A playlist goes in any section with `createPlaylistScape({ …, group: 'focus' })` (default `'music'`).
+- **Radio = outbound links** — `engine.register(radioStation({ id, label, href, description? }))` adds a link item (group `'radio'`). The toggle renders it as an `<a target="_blank" rel="noopener noreferrer">` menu item with an external-link glyph; it opens the station's own site or player. We never relay a third-party stream (licensing), and `engine.play()` refuses a link. Only `http(s)` hrefs render (`safeAmbienceHref`). `engine.list()` stays playable-only; `engine.items()` lists scapes and links.
 - **Persistence** — volume + last scape persist through the engine (custom `storageKey`); restoring preselects but never autoplays.
-- **AmbienceToggle** — click plays/stops the last scape; ArrowDown, press-and-hold or right-click opens the grouped scape menu with volume; `aria-pressed` / `menuitemradio` / `aria-live` status wired; a rejected `play()` announces a transient “couldn't start — tap again” in the sr-only status, cleared by the next successful play; the glyph breathes with the shared breath clock and is static under reduced motion / `data-motion="calm"`.
+- **AmbienceToggle** — click plays/stops the last scape; ArrowDown, press-and-hold or right-click opens the menu: volume, then one row per section, each opening a submenu (Right / Enter / Space open and focus its first item, Left / Escape close back to the row, hover opens without moving focus). The current scape is checked and its section row names it; a playing playlist shows the track's title, composer and license; `aria-pressed` / `menuitemradio` / `aria-live` status wired; a rejected `play()` announces a transient “couldn't start — tap again” in the sr-only status, cleared by the next successful play; the glyph breathes with the shared breath clock and is static under reduced motion / `data-motion="calm"`.
 
 Demo: `/components/ambience-toggle` on the docs site.
 

package/dist/ambience/default.d.ts

@@ -1,24 +1,10 @@
-/**
- * createDefaultAmbience() — the "just works" engine.
- *
- * Every scape the library ships is pre-registered, in the menu order the
- * AmbienceToggle groups them (meditation / focus / noise / nature). A host
- * that supplies extra scapes (e.g. a playlist scape from a manifest of
- * public-domain recordings) registers them on top — registry duplicate-id
- * protection still applies.
- *
- * @example
- *   import { createDefaultAmbience } from '../../../dist/ambience';
- *   const ambience = createDefaultAmbience();
- *   // inside a click handler:
- *   await ambience.play('rain');
- */
-import { type Ambience } from './engine';
-import type { Scape } from './types';
+import type { Ambience, AmbienceOptions, Scape } from './types';
 /** The scapes the library ships, in canonical menu order. */
 export declare const DEFAULT_SCAPES: readonly Scape[];
 export interface DefaultAmbienceOptions {
     /** Passed through to `createAmbience` (e.g. a custom `storageKey`). */
     storageKey?: string;
+    /** Menu section order/labels, passed through to `createAmbience`. */
+    groups?: AmbienceOptions['groups'];
 }
 export declare function createDefaultAmbience(options?: DefaultAmbienceOptions): Ambience;

package/dist/ambience/default.js

@@ -1,8 +1,9 @@
 /**
  * createDefaultAmbience() — the "just works" engine.
  *
- * Every scape the library ships is pre-registered, in the menu order the
- * AmbienceToggle groups them (meditation / focus / noise / nature). A host
+ * Every scape the library ships is pre-registered (meditation / focus /
+ * noise / nature); the AmbienceToggle orders the sections by the `groups`
+ * option, or radio / focus / noise / meditation / nature / music. A host
  * that supplies extra scapes (e.g. a playlist scape from a manifest of
  * public-domain recordings) registers them on top — registry duplicate-id
  * protection still applies.

package/dist/ambience/engine.js

@@ -10,6 +10,7 @@
  * NO UI here. The AmbienceToggle task (jatui-b7qvr) hosts this module.
  */
 import { BreathClock } from './breath';
+import { normalizeAmbienceGroups } from './groups';
 import { createMasterChain } from './master';
 import { loadPersisted, savePersisted } from './persist';
 import { ScapeRegistry } from './registry';
@@ -42,6 +43,7 @@ export function createAmbience(options = {}) {
             return nav?.userActivation ? nav.userActivation.isActive : true;
         });
     const registry = new ScapeRegistry();
+    const groupDefs = normalizeAmbienceGroups(options.groups);
     const breath = new BreathClock();
     // Resting state restored from storage (never autoplays — preselect only).
     const persisted = loadPersisted(storageKey);
@@ -132,8 +134,11 @@ export function createAmbience(options = {}) {
     }
     async function play(id) {
         const scape = registry.get(id);
-        if (!scape)
+        if (!scape) {
+            if (registry.item(id))
+                throw new Error(`Not playable (a link item): ${id}`);
             throw new Error(`Unknown scape: ${id}`);
+        }
         if (!isGesture())
             throw new Error('play() must be called from a user gesture');
         // Monotonic play token: a second play() (or a stop()/kill()) while this
@@ -279,12 +284,18 @@ export function createAmbience(options = {}) {
         };
     }
     return {
-        register(scape) {
-            registry.register(scape);
+        register(item) {
+            registry.register(item);
         },
         list() {
             return registry.list();
         },
+        items() {
+            return registry.items();
+        },
+        groups() {
+            return groupDefs.map((d) => ({ ...d }));
+        },
         play,
         stop,
         kill,

package/dist/ambience/groups.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Menu sections — the pure grouping the AmbienceToggle renders (jatui-mdq2p).
+ * The host orders and labels sections (`AmbienceOptions.groups`); without
+ * that, the default order is radio / focus / noise / meditation / nature /
+ * music. A group that holds items but is missing from the order still
+ * renders, after the ordered ones, in first-seen order: a menu never silently
+ * drops a registered item.
+ */
+import type { AmbienceGroupDef, AmbienceItem, AmbienceLink, ScapeGroup } from './types';
+/** Default section order when the host configures none. */
+export declare const AMBIENCE_DEFAULT_GROUP_ORDER: readonly ScapeGroup[];
+/** Human labels for the library's own groups. */
+export declare const AMBIENCE_DEFAULT_GROUP_LABELS: Readonly<Record<string, string>>;
+/** One section of the menu: its id, label and items in registration order. */
+export interface AmbienceSection<T extends AmbienceItem = AmbienceItem> {
+    group: ScapeGroup;
+    label: string;
+    scapes: T[];
+}
+/** Narrow an item to an outbound link. */
+export declare function isAmbienceLink(item: AmbienceItem | null | undefined): item is AmbienceLink;
+/** Normalize `groups` input (`'radio'` or `{ id, label }`), dropping blanks and duplicates. */
+export declare function normalizeAmbienceGroups(groups: ReadonlyArray<ScapeGroup | AmbienceGroupDef> | undefined): AmbienceGroupDef[];
+/** The label for a group: host label, then the library's, then the id capitalized. */
+export declare function ambienceGroupLabel(group: ScapeGroup, defs?: readonly AmbienceGroupDef[]): string;
+/**
+ * Group items into menu sections: host order (or the default order),
+ * registration order within a section, empty sections omitted, unlisted
+ * 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.
+ */
+export declare function safeAmbienceHref(href: string | null | undefined): string | null;

package/dist/ambience/groups.js

@@ -0,0 +1,98 @@
+/** Default section order when the host configures none. */
+export const AMBIENCE_DEFAULT_GROUP_ORDER = Object.freeze([
+    'radio',
+    'focus',
+    'noise',
+    'meditation',
+    'nature',
+    'music'
+]);
+/** Human labels for the library's own groups. */
+export const AMBIENCE_DEFAULT_GROUP_LABELS = Object.freeze({
+    radio: 'Radio',
+    focus: 'Focus',
+    noise: 'Noise',
+    meditation: 'Meditation',
+    nature: 'Nature',
+    music: 'Music'
+});
+/** Narrow an item to an outbound link. */
+export function isAmbienceLink(item) {
+    return !!item && item.kind === 'link';
+}
+/** Normalize `groups` input (`'radio'` or `{ id, label }`), dropping blanks and duplicates. */
+export function normalizeAmbienceGroups(groups) {
+    const out = [];
+    const seen = new Set();
+    for (const g of groups ?? []) {
+        const def = typeof g === 'string' ? { id: g } : g;
+        if (!def?.id || seen.has(def.id))
+            continue;
+        seen.add(def.id);
+        out.push(def.label ? { id: def.id, label: def.label } : { id: def.id });
+    }
+    return out;
+}
+/** The label for a group: host label, then the library's, then the id capitalized. */
+export function ambienceGroupLabel(group, defs = []) {
+    const host = defs.find((d) => d.id === group)?.label;
+    if (host)
+        return host;
+    if (AMBIENCE_DEFAULT_GROUP_LABELS[group])
+        return AMBIENCE_DEFAULT_GROUP_LABELS[group];
+    return group ? group.charAt(0).toUpperCase() + group.slice(1) : 'Other';
+}
+/**
+ * Group items into menu sections: host order (or the default order),
+ * registration order within a section, empty sections omitted, unlisted
+ * groups appended in first-seen order.
+ */
+export function groupAmbienceItems(items, groups) {
+    const defs = normalizeAmbienceGroups(groups);
+    const order = defs.length ? defs.map((d) => d.id) : AMBIENCE_DEFAULT_GROUP_ORDER;
+    const byGroup = new Map();
+    for (const item of items) {
+        const list = byGroup.get(item.group) ?? [];
+        list.push(item);
+        byGroup.set(item.group, list);
+    }
+    const out = [];
+    for (const g of order) {
+        const list = byGroup.get(g);
+        if (!list?.length)
+            continue;
+        out.push({ group: g, label: ambienceGroupLabel(g, defs), scapes: list });
+        byGroup.delete(g);
+    }
+    for (const [g, list] of byGroup) {
+        out.push({ group: g, label: ambienceGroupLabel(g, defs), scapes: list });
+    }
+    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.
+ */
+export function safeAmbienceHref(href) {
+    if (typeof href !== 'string')
+        return null;
+    try {
+        const u = new URL(href.trim());
+        return u.protocol === 'https:' || u.protocol === 'http:' ? u.href : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/ambience/index.d.ts

@@ -15,9 +15,11 @@ 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 } from './scapes/playlist';
+export { createPlaylistScape, isPlaylistScape, trackAttribution } 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 type { Ambience, AmbienceOptions, AmbienceState, BreathState, Scape, ScapeContext, ScapeGroup, ScapeInstance } from './types';
+export { AMBIENCE_DEFAULT_GROUP_ORDER, AMBIENCE_DEFAULT_GROUP_LABELS, groupAmbienceItems, ambienceGroupLabel, isAmbienceLink, normalizeAmbienceGroups, radioStation, safeAmbienceHref } from './groups';
+export type { AmbienceSection } from './groups';
+export type { Ambience, AmbienceGroupDef, AmbienceItem, AmbienceLink, AmbienceOptions, AmbienceState, BreathState, Scape, ScapeContext, ScapeGroup, ScapeInstance } from './types';

package/dist/ambience/index.js

@@ -21,7 +21,9 @@ 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 } from './scapes/playlist';
+export { createPlaylistScape, isPlaylistScape, trackAttribution } 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';

package/dist/ambience/registry.d.ts

@@ -1,11 +1,11 @@
-/**
- * The scape registry — a named map with duplicate-id protection. list()
- * returns registration order (stable for menus).
- */
-import type { Scape } from './types';
+import type { AmbienceItem, AmbienceLink, Scape } from './types';
 export declare class ScapeRegistry {
     #private;
-    register(scape: Scape): void;
+    register(item: Scape | AmbienceLink): void;
+    /** The playable scape with this id (undefined for a link or an unknown id). */
     get(id: string): Scape | undefined;
+    /** Any registered item with this id. */
+    item(id: string): AmbienceItem | undefined;
     list(): Scape[];
+    items(): AmbienceItem[];
 }

package/dist/ambience/registry.js

@@ -1,16 +1,39 @@
+/**
+ * The scape registry — a named map with duplicate-id protection. Holds
+ * playable scapes and outbound link items (radio stations) in ONE id space.
+ * list() returns the playable scapes and items() everything, both in
+ * registration order (stable for menus).
+ */
+import { isAmbienceLink } from './groups';
 export class ScapeRegistry {
-    #scapes = new Map();
-    register(scape) {
-        if (!scape?.id)
+    #items = new Map();
+    register(item) {
+        if (!item?.id)
             throw new Error('Scape must have an id');
-        if (this.#scapes.has(scape.id))
-            throw new Error(`Scape id already registered: ${scape.id}`);
-        this.#scapes.set(scape.id, scape);
+        if (this.#items.has(item.id))
+            throw new Error(`Scape id already registered: ${item.id}`);
+        if (isAmbienceLink(item)) {
+            if (typeof item.href !== 'string' || !item.href.trim())
+                throw new Error(`Link item needs an href: ${item.id}`);
+        }
+        else if (typeof item.build !== 'function') {
+            throw new Error(`Scape needs a build(): ${item.id}`);
+        }
+        this.#items.set(item.id, item);
     }
+    /** The playable scape with this id (undefined for a link or an unknown id). */
     get(id) {
-        return this.#scapes.get(id);
+        const item = this.#items.get(id);
+        return item && !isAmbienceLink(item) ? item : undefined;
+    }
+    /** Any registered item with this id. */
+    item(id) {
+        return this.#items.get(id);
     }
     list() {
-        return [...this.#scapes.values()];
+        return [...this.#items.values()].filter((i) => !isAmbienceLink(i));
+    }
+    items() {
+        return [...this.#items.values()];
     }
 }

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

@@ -36,7 +36,7 @@
  * Nothing is registered globally; the integration task wires the default
  * registry (jatui-poq30).
  */
-import type { Scape } from '../types';
+import type { Scape, ScapeGroup } from '../types';
 export declare const PLAYLIST: Readonly<{
     /** Crossfade between consecutive tracks (s). */
     CROSSFADE: 3;
@@ -91,6 +91,9 @@ export interface PlaylistScapeOptions {
     id: string;
     label: string;
     description?: string;
+    /** The menu section this playlist sits in (e.g. 'focus', 'meditation',
+     *  or a host group). Default 'music'. */
+    group?: ScapeGroup;
     /** Manifest URL — fetched lazily, ONCE, on the first play. A failed fetch
      *  is retried on the next play. */
     manifestUrl?: string;
@@ -108,10 +111,13 @@ export interface PlaylistScapeOptions {
     /** Injectable for tests (default `new Audio(url)`). */
     createMediaElement?: (url: string) => HTMLAudioElement;
 }
-/** A Scape plus the playlist UI surface. Cast a registered Scape to this in
+/** A Scape plus the playlist UI surface. Narrow a registered Scape with
+ *  isPlaylistScape() in
  *  the toggle to reach state()/subscribe()/skip()/setShuffle(). */
 export interface PlaylistScape extends Scape {
-    group: 'music';
+    /** Discriminates a playlist from other scapes (the toggle shows the
+     *  playing track's attribution for these). */
+    readonly playlist: true;
     /** Current snapshot (also the initial value subscribe() fires with). */
     state(): PlaylistState;
     /** Subscribe to playlist state changes; fires immediately. */
@@ -127,3 +133,10 @@ export declare function createPlaylistScape(options: PlaylistScapeOptions): Play
 /** Fisher–Yates over an injected rand (the engine's per-scape PRNG), so the
  *  play order is deterministic for tests. */
 export declare function shuffledOrder(n: number, rand: () => number): number[];
+/** Narrow a registered scape to a playlist (to reach its state/subscribe). */
+export declare function isPlaylistScape(scape: unknown): scape is PlaylistScape;
+/**
+ * The attribution line for a track: "Composer · Performer · License"
+ * (performer only when present and different from the composer).
+ */
+export declare function trackAttribution(track: PlaylistTrack | null | undefined): string;

package/dist/ambience/scapes/playlist.js

@@ -489,8 +489,9 @@ export function createPlaylistScape(options) {
     const scape = {
         id: options.id,
         label: options.label,
-        group: 'music',
+        group: options.group ?? 'music',
         description: options.description,
+        playlist: true,
         build(scapeCtx) {
             const inst = buildInstance(scapeCtx);
             latest = inst;
@@ -567,3 +568,23 @@ function isValidTrack(t) {
         (o.sourceUrl === undefined ||
             (typeof o.sourceUrl === 'string' && o.sourceUrl.trim() !== '')));
 }
+/** Narrow a registered scape to a playlist (to reach its state/subscribe). */
+export function isPlaylistScape(scape) {
+    return (typeof scape === 'object' &&
+        scape !== null &&
+        scape.playlist === true &&
+        typeof scape.subscribe === 'function');
+}
+/**
+ * The attribution line for a track: "Composer · Performer · License"
+ * (performer only when present and different from the composer).
+ */
+export function trackAttribution(track) {
+    if (!track)
+        return '';
+    const parts = [track.composer];
+    if (track.performer && track.performer !== track.composer)
+        parts.push(track.performer);
+    parts.push(track.license);
+    return parts.filter(Boolean).join(' · ');
+}

package/dist/ambience/types.d.ts

@@ -28,8 +28,38 @@ export interface ScapeInstance {
     /** Optional live parameter (scape-defined keys). */
     setParam?(key: string, value: number): void;
 }
-export type ScapeGroup = 'meditation' | 'focus' | 'noise' | 'nature' | 'music';
+/**
+ * A menu section. The named members are the library's own groups (radio holds
+ * outbound station links); any other string is a host-defined group — it
+ * renders after the configured ones, labelled from its id unless the host
+ * labels it via `AmbienceOptions.groups`.
+ */
+export type ScapeGroup = 'radio' | 'focus' | 'noise' | 'meditation' | 'nature' | 'music' | (string & {});
+/** A host's menu section: its id plus the label the toggle shows. */
+export interface AmbienceGroupDef {
+    id: ScapeGroup;
+    label?: string;
+}
+/**
+ * An outbound link item (radio stations). The engine never plays it: the
+ * toggle opens `href` — the station's own site or player — in a new tab. We
+ * do NOT relay third-party streams (licensing), so a station is a link, not a
+ * scape.
+ */
+export interface AmbienceLink {
+    kind: 'link';
+    id: string;
+    label: string;
+    group: ScapeGroup;
+    /** The station's own page or web player. Opened in a new tab. */
+    href: string;
+    description?: string;
+}
+/** Anything the menu lists: a playable scape or an outbound link. */
+export type AmbienceItem = Scape | AmbienceLink;
 export interface Scape {
+    /** Absent (or 'scape') on every playable scape; links carry 'link'. */
+    kind?: 'scape';
     id: string;
     label: string;
     group: ScapeGroup;
@@ -53,10 +83,16 @@ export interface BreathState {
     rising: boolean;
 }
 export interface Ambience {
-    register(scape: Scape): void;
+    /** Register a playable scape or an outbound link (ids are unique across both). */
+    register(item: Scape | AmbienceLink): void;
+    /** The playable scapes, registration order (links excluded). */
     list(): Scape[];
+    /** Every registered item — scapes AND links — in registration order. */
+    items(): AmbienceItem[];
+    /** The host's menu sections in order (`AmbienceOptions.groups`), or [] for the default order. */
+    groups(): AmbienceGroupDef[];
     /** MUST be called from a user gesture (a click/keydown handler). Rejects
-     *  otherwise. Resolves once the scape is scheduled and audibly started. */
+     *  otherwise, and for an unknown id or a link item. Resolves once the scape is scheduled and audibly started. */
     play(id: string): Promise<void>;
     /** Fade out ~0.55 s; the AudioContext closes ~3 s later. A play() inside
      *  that window cancels the close and fades back in over ~4 s. */
@@ -70,6 +106,14 @@ export interface Ambience {
 }
 export interface AmbienceOptions {
     storageKey?: string;
+    /**
+     * Menu sections in the order the toggle shows them, each optionally
+     * labelled (`'radio'` or `{ id: 'radio', label: 'Stations' }`). Groups
+     * holding items but missing here still render, after these — a menu never
+     * silently drops a registered item. Omitted: the default order
+     * radio / focus / noise / meditation / nature / music.
+     */
+    groups?: Array<ScapeGroup | AmbienceGroupDef>;
     defaultVolume?: number;
     /** Gesture probe, injectable for tests. Default: navigator.userActivation
      * when it exists (trusted-UI truth), otherwise permissive (SSR/node).