@joewinke/jatui 0.59.0 → 0.61.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 = 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`.
+`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`.
 
 ### 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/README.md

@@ -120,12 +120,19 @@ scape.subscribe((s) => {
   // s.status: 'idle' | 'loading' | 'playing' | 'error'
   // s.track: { title, composer, performer?, license, sourceUrl? } | null
   // s.index, s.count, s.error?
+  // s.position, s.duration — elapsed/total seconds of the current track
+  //   (0 while unknown; refreshed on the ~250 ms engine tick — jatui-153tz)
 });
-scape.skip(); // crossfade to the next track now
+scape.skip();  // crossfade to the next track now
+scape.prev();  // restart the track when >3 s are in, else the previous track
 scape.setShuffle(true);
 scape.tracks(); // resolved list, or null until the manifest resolved
 ```
 
 Cast a scape from `ambience.list()` to `PlaylistScape` in the toggle to reach
 it. The toggle renders the attribution line — `composer · performer · license`
-— linked to `sourceUrl` while a playlist scape is playing.
+— linked to `sourceUrl` while a playlist scape is playing, and (jatui-153tz) a
+now-playing row above the volume with the track, a progress bar fed by
+`position`/`duration`, and a prev / play-pause / next transport. The engine's
+`pause()`/`resume()` freeze the scape in place — the playlist pauses its media
+elements and keeps the track position.

package/dist/ambience/engine.d.ts

@@ -12,6 +12,8 @@ export declare const TIMING: Readonly<{
     RESUME_FADE: 4;
     /** setVolume ramp (s). */
     VOLUME_RAMP: 0.3;
+    /** pause() fade-out before the scape freezes (s). */
+    PAUSE_FADE: 0.15;
     /** The fade handed to instance.stop() on kill — 0 = immediate. */
     KILL_FADE: 0;
     /** After a scape's stop fade, its un-released lookahead cbs are retired

package/dist/ambience/engine.js

@@ -27,6 +27,8 @@ export const TIMING = Object.freeze({
     RESUME_FADE: 4,
     /** setVolume ramp (s). */
     VOLUME_RAMP: 0.3,
+    /** pause() fade-out before the scape freezes (s). */
+    PAUSE_FADE: 0.15,
     /** The fade handed to instance.stop() on kill — 0 = immediate. */
     KILL_FADE: 0,
     /** After a scape's stop fade, its un-released lookahead cbs are retired
@@ -50,6 +52,12 @@ export function createAmbience(options = {}) {
     let volume = clamp(typeof persisted.volume === 'number' ? persisted.volume : (options.defaultVolume ?? 0.6));
     let currentId = persisted.lastScape ?? null;
     let playing = false;
+    /** True between pause() and resume()/play()/stop(): the instance stays
+     *  built and frozen (playlist position kept), the context suspended. */
+    let paused = false;
+    /** The deferred freeze at the end of pause()'s fade — a resume()/play()
+     *  inside the window aborts it. */
+    let pauseTimer = null;
     let ctx = null;
     let chain = null;
     let active = null;
@@ -62,7 +70,7 @@ export function createAmbience(options = {}) {
     const breathSubs = new Set();
     const lookaheadCbs = new Set();
     function state() {
-        return { currentId, playing, volume };
+        return { currentId, playing, paused, volume };
     }
     function emit() {
         const s = state();
@@ -145,8 +153,11 @@ export function createAmbience(options = {}) {
         // one is suspended at `await c.resume()` invalidates it — the loser
         // returns without building or starting anything.
         const gen = ++playGen;
-        // Inside the post-stop close window: cancel the close, fade back in.
-        const resuming = closeTimer !== null;
+        const wasPaused = paused;
+        paused = false; // a play() is a fresh start — never a continuation
+        // Inside the post-stop close window (or resuming from a paused scape):
+        // cancel the close / unfreeze, and fade the bus back in.
+        const resuming = closeTimer !== null || wasPaused;
         if (closeTimer !== null) {
             clearTimeout(closeTimer);
             closeTimer = null;
@@ -201,7 +212,15 @@ export function createAmbience(options = {}) {
     }
     function stop() {
         playGen++; // invalidate any in-flight play()
-        if (!ctx || !playing) {
+        if (pauseTimer) {
+            clearTimeout(pauseTimer);
+            pauseTimer = null;
+        }
+        const wasPaused = paused;
+        paused = false;
+        // A paused scape still owns a live (frozen) instance + context — its
+        // stop must tear them down like a playing stop would.
+        if (!ctx || (!playing && !wasPaused)) {
             playing = false;
             emit();
             return;
@@ -223,12 +242,88 @@ export function createAmbience(options = {}) {
         }, TIMING.CLOSE_DELAY_MS);
         emit();
     }
+    function pause() {
+        if (!playing)
+            return;
+        playing = false;
+        paused = true;
+        emit();
+        if (!ctx || !chain || !active)
+            return;
+        // A short fade so the freeze is click-free, then the scape freezes in
+        // place (media elements) and the context suspends — generative scapes
+        // stop evolving and the audio thread rests.
+        const now = ctx.currentTime;
+        const g = chain.bus.gain;
+        g.cancelScheduledValues(now);
+        g.setValueAtTime(g.value, now);
+        g.linearRampToValueAtTime(0, now + TIMING.PAUSE_FADE);
+        if (pauseTimer)
+            clearTimeout(pauseTimer);
+        pauseTimer = setTimeout(() => {
+            pauseTimer = null;
+            // A resume()/play()/stop() inside the fade window aborted the pause.
+            if (!paused || playing || !active || !ctx)
+                return;
+            try {
+                active.inst.pause?.();
+            }
+            catch {
+                /* a broken scape must not take the engine down */
+            }
+            try {
+                void ctx.suspend();
+            }
+            catch {
+                /* already closed */
+            }
+        }, TIMING.PAUSE_FADE * 1000 + 20);
+    }
+    async function resume() {
+        if (playing || !currentId || !paused)
+            return; // only a paused scape resumes
+        if (!isGesture())
+            throw new Error('resume() must be called from a user gesture');
+        const gen = ++playGen; // a stop()/kill() during the resume invalidates it
+        paused = false;
+        // Defensive: a paused engine always still owns its context + instance
+        // (kill/stop clear the paused flag) — bail rather than guess.
+        if (!ctx || !chain || !active) {
+            emit();
+            return;
+        }
+        if (ctx.state === 'suspended')
+            await ctx.resume();
+        if (gen !== playGen || !ctx || !chain || !active)
+            return; // superseded mid-resume
+        try {
+            active.inst.resume?.();
+        }
+        catch {
+            /* a broken scape must not take the engine down */
+        }
+        const g = chain.bus.gain;
+        g.cancelScheduledValues(ctx.currentTime);
+        g.setValueAtTime(g.value, ctx.currentTime);
+        g.linearRampToValueAtTime(1, ctx.currentTime + TIMING.VOLUME_RAMP);
+        // A pause did not stop the breath clock, but make sure it runs.
+        if (!breath.running)
+            breath.start(ctx.currentTime);
+        playing = true;
+        persist();
+        emit();
+    }
     function kill() {
         playGen++; // invalidate any in-flight play()
         if (closeTimer) {
             clearTimeout(closeTimer);
             closeTimer = null;
         }
+        if (pauseTimer) {
+            clearTimeout(pauseTimer);
+            pauseTimer = null;
+        }
+        paused = false;
         if (tick) {
             clearInterval(tick);
             tick = null;
@@ -298,6 +393,8 @@ export function createAmbience(options = {}) {
         },
         play,
         stop,
+        pause,
+        resume,
         kill,
         setVolume,
         get state() {

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

@@ -47,6 +47,9 @@ export declare const PLAYLIST: Readonly<{
     /** Start the next track when at most this much of the current track is
      *  left ON TOP of the crossfade (s). */
     END_MARGIN: 0.25;
+    /** prev() restarts the current track when more than this many seconds are
+     *  in; below it, it goes back one track (jatui-153tz). */
+    PREV_RESTART: 3;
     /** setParam('gain') ramp (s). */
     GAIN_RAMP: 0.15;
     /** Disconnect + pause this many ms after a stop fade ends — before the
@@ -84,6 +87,13 @@ export interface PlaylistState {
     index: number;
     /** Number of tracks in the resolved playlist (0 until resolved). */
     count: number;
+    /** Elapsed seconds of the current track (0 while none is sounding).
+     *  Updated on the engine's ~250 ms lookahead tick — the cadence the
+     *  toggle's progress bar renders at (jatui-153tz). */
+    position: number;
+    /** Total seconds of the current track (0 until metadata reports one —
+     *  a stream without a duration stays 0). */
+    duration: number;
     /** Present on error. */
     error?: string;
 }
@@ -124,6 +134,11 @@ export interface PlaylistScape extends Scape {
     subscribe(fn: (s: PlaylistState) => void): () => void;
     /** Crossfade to the next track now. No-op while loading/released. */
     skip(): void;
+    /** Back one step (jatui-153tz): restart the current track when more than
+     *  PLAYLIST.PREV_RESTART (3 s) are in, else crossfade to the previous
+     *  track in the play order (at the very first track, restart). No-op
+     *  while loading/released or mid-transition. */
+    prev(): void;
     /** Toggle shuffle; the current track stays, the rest reorder at once. */
     setShuffle(on: boolean): void;
     /** Crossfade to an absolute track index — used on leadership handover

package/dist/ambience/scapes/playlist.js

@@ -8,6 +8,9 @@ export const PLAYLIST = Object.freeze({
     /** Start the next track when at most this much of the current track is
      *  left ON TOP of the crossfade (s). */
     END_MARGIN: 0.25,
+    /** prev() restarts the current track when more than this many seconds are
+     *  in; below it, it goes back one track (jatui-153tz). */
+    PREV_RESTART: 3,
     /** setParam('gain') ramp (s). */
     GAIN_RAMP: 0.15,
     /** Disconnect + pause this many ms after a stop fade ends — before the
@@ -43,7 +46,7 @@ export function createPlaylistScape(options) {
         }
     }
     /** Shared UI snapshot + subscribers. Only the latest build writes it. */
-    let snap = { status: 'idle', track: null, index: 0, count: 0 };
+    let snap = { status: 'idle', track: null, index: 0, count: 0, position: 0, duration: 0 };
     const subs = new Set();
     /** Handle to the most recent build — skip()/setShuffle() route here. */
     let latest = null;
@@ -178,6 +181,12 @@ export function createPlaylistScape(options) {
                 if (slot.trackIndex < 0)
                     return;
                 const el = slot.el;
+                // Live progress for the toggle's now-playing row (jatui-153tz):
+                // elapsed/total on the ~250 ms tick cadence the bar renders at.
+                const position = Number.isFinite(el.currentTime) ? Math.max(0, el.currentTime) : 0;
+                const duration = Number.isFinite(el.duration) && el.duration > 0 ? el.duration : 0;
+                if (snap.position !== position || snap.duration !== duration)
+                    setSnap({ position, duration });
                 const d = el.duration;
                 // Stateless per-tick check (no while-loop to re-anchor): at most ONE
                 // transition per tick, always anchored at THIS tick's now, so a
@@ -274,7 +283,15 @@ export function createPlaylistScape(options) {
             catch {
                 onTrackFailed();
             }
-            setSnap({ status: 'playing', track, index: pos, count: resolved.length, error: undefined });
+            setSnap({
+                status: 'playing',
+                track,
+                index: pos,
+                count: resolved.length,
+                position: 0,
+                duration: 0,
+                error: undefined
+            });
             preloadNext();
         }
         function quietSlot(slot) {
@@ -357,6 +374,8 @@ export function createPlaylistScape(options) {
                 track: null,
                 index: 0,
                 count: resolved?.length ?? 0,
+                position: 0,
+                duration: 0,
                 error: undefined
             });
             const f = Math.max(0, fade);
@@ -432,7 +451,9 @@ export function createPlaylistScape(options) {
                 error: message,
                 track: null,
                 index: 0,
-                count: resolved?.length ?? 0
+                count: resolved?.length ?? 0,
+                position: 0,
+                duration: 0
             });
             const now = ctx.currentTime;
             const g = mix.gain;
@@ -461,6 +482,57 @@ export function createPlaylistScape(options) {
             if (ni !== -1)
                 startTrack(ni, 'cross');
         }
+        /** Back one step (jatui-153tz): > 3 s into the track restarts it, else
+         *  the previous track in the play order (the first track restarts). */
+        function prevInternal() {
+            if (released || !started || order.length === 0 || active < 0)
+                return;
+            const slot = slots[active];
+            const cur = order[pos];
+            if (slot.trackIndex !== cur)
+                return; // mid-transition — the skip owns it
+            if (slot.el.currentTime > PLAYLIST.PREV_RESTART || pos === 0) {
+                // Restart the current track: a quick fade into the idle slot
+                // loaded with the same track, play order pointer unchanged.
+                startTrack(cur, 'ended');
+            }
+            else {
+                pos -= 1;
+                startTrack(order[pos], 'cross');
+            }
+        }
+        /** Engine pause(): freeze in place — both elements stop, the track and
+         *  its position are kept for resume(). Gains/schedules stay as they are
+         *  (the context suspension freezes the audio clock mid-ramp). */
+        function pauseInternal() {
+            if (released || !started)
+                return;
+            for (const slot of slots) {
+                try {
+                    slot.el.pause();
+                }
+                catch {
+                    /* element already unusable */
+                }
+            }
+        }
+        /** Engine resume(): the active element continues from where it paused.
+         *  The idle (preloading) slot stays paused. */
+        function resumeInternal() {
+            if (released || !started || active < 0)
+                return;
+            const slot = slots[active];
+            if (slot.trackIndex < 0)
+                return;
+            try {
+                const p = slot.el.play();
+                if (p)
+                    p.catch(() => { }); // the engine's failed-track path owns errors
+            }
+            catch {
+                /* element already unusable */
+            }
+        }
         /** Leadership handover (jatui-lm1mf): crossfade to an absolute track
          *  index so the new leader tab picks up the position the old one left. */
         function startAtInternal(index) {
@@ -489,8 +561,9 @@ export function createPlaylistScape(options) {
         }
         wireLookahead();
         return {
-            api: { start, stop, setParam },
+            api: { start, stop, setParam, pause: pauseInternal, resume: resumeInternal },
             skip: skipInternal,
+            prev: prevInternal,
             startAt: startAtInternal,
             reshuffle,
             isReleased: () => released
@@ -519,6 +592,10 @@ export function createPlaylistScape(options) {
             if (latest && !latest.isReleased())
                 latest.skip();
         },
+        prev() {
+            if (latest && !latest.isReleased())
+                latest.prev();
+        },
         setShuffle(on) {
             shuffle = on;
             if (latest && !latest.isReleased())

package/dist/ambience/shared.d.ts

@@ -1,3 +1,46 @@
+/**
+ * The cross-tab shared player (jatui-lm1mf): exactly ONE tab owns the
+ * AudioContext and plays; every other tab is a REMOTE that renders the same
+ * live state and sends commands. Open MOS in ten tabs and the tab playing
+ * ambience is no longer unfindable — any tab's rail toggle shows and controls
+ * the one that's sounding.
+ *
+ * Leader election:
+ *   - Web Locks API (`navigator.locks.request(lockName)`) when available —
+ *     the lock IS the leadership, so the browser guarantees mutual exclusion.
+ *   - Fallback (no Web Locks): a BroadcastChannel heartbeat. The leader
+ *     heartbeats every HEARTBEAT_MS; a tab that hears no beat for STALE_MS
+ *     may claim, guarded by a short window in which a live leader reasserts.
+ *
+ * Transport (always BroadcastChannel 'jatui:ambience'):
+ *   - `state` / `heartbeat` — the leader publishes the live shared state
+ *     (playing scape, volume, muted, track attribution, its tab id).
+ *   - `cmd` — a remote tells the leader to stop / pause / resume / skip / go
+ *     back / setVolume / toggleMute / play (play only when the fallback
+ *     election defers to a live leader).
+ *   - `want` / `claim` — the heartbeat election.
+ *   - `gone` — the leader's pagehide: remotes immediately mark the leader
+ *     gone (playback stops — never a surprise autoplay in a background tab).
+ *
+ * Starting a scape in tab B while tab A plays makes B the leader: with
+ * Web Locks, B's user-gesture play STEALS the lock, A's held request promise
+ * rejects (AbortError) and A fades out — never two tabs audible. Playlist
+ * scapes hand over their track position (published by the leader, applied
+ * by the new leader via PlaylistScape.startAt).
+ *
+ * Resuming after the leader tab closes/reloads: playback is stopped and no
+ * remote autoplays; pressing play (the toggle's existing button — a user
+ * gesture, satisfying the autoplay policy) claims leadership and plays.
+ *
+ * Volume and mute persist in localStorage (shared by all tabs of the
+ * origin). The `storage` event is deliberately NOT the transport — it skips
+ * the writer tab; BroadcastChannel delivers to every OTHER tab.
+ *
+ * NO UI here. Hosts get everything through createAmbience({ shared: true }) —
+ * the Ambience interface is unchanged, so AmbienceToggle needs no structural
+ * changes beyond reading the shared now-playing line.
+ */
+import { createAmbience as createLocalEngine } from './engine';
 import type { Ambience, AmbienceOptions } from './types';
 /** BroadcastChannel name — the ambience control channel for the origin. */
 export declare const AMBIENCE_CHANNEL = "jatui:ambience";
@@ -37,6 +80,18 @@ export interface SharedAmbienceState {
     /** Position of the published now-playing track in its playlist (0-based),
      *  for leadership handover of playlist scapes. */
     trackIndex: number | null;
+    /** The published track's title, so a remote can show title and
+     *  attribution on their own lines (jatui-153tz). */
+    trackTitle: string | null;
+    /** Elapsed seconds within the published track (leader-published at the
+     *  playlist's ~250 ms state cadence); null when unknown. */
+    trackPosition: number | null;
+    /** Total seconds of the published track; null while unknown (no metadata
+     *  yet, or a stream without a duration). */
+    trackDuration: number | null;
+    /** True while the leader is PAUSED (engine.pause() — the scape is frozen
+     *  in place, not torn down; resume continues it). */
+    paused: boolean;
 }
 /** An Ambience whose playback is shared across tabs (see module doc). */
 export interface SharedAmbience extends Ambience {
@@ -48,8 +103,14 @@ export interface SharedAmbience extends Ambience {
     setMuted(muted: boolean): void;
     toggleMute(): void;
     /** Leader-side hook: the host publishes the playing track's attribution
-     *  (and playlist position) so remote tabs show it too. */
-    setNowPlaying(line: string | null, trackIndex?: number | null): void;
+     *  (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 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;
+    prevTrack(id: string): void;
     /** Release the lock, stop the heartbeat and close the channel. The local
      *  engine is killed if this tab was the leader. */
     destroy(): void;
@@ -95,3 +156,9 @@ export declare function createSharedAmbience(options?: SharedAmbienceOptions): S
  *  Ambience interface (AmbienceToggle needs no changes beyond reading the
  *  shared now-playing line). */
 export declare function createAmbience(options?: AmbienceOptions): Ambience;
+/** The always-local engine factory — the barrel's `createAmbienceLocal`.
+ *  The ambience barrel has re-exported this name since the shared player
+ *  landed (jatui-lm1mf), but shared.ts never defined it: real ESM (the built
+ *  dist, Node) failed to import the subpath at all (jatui-153tz rebuild). It
+ *  is the plain engine: `shared` is never honored, whatever the options. */
+export declare const createAmbienceLocal: typeof createLocalEngine;