@joewinke/jatui 0.46.0 → 0.48.0

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

@@ -0,0 +1,74 @@
+/**
+ * AmbienceToggle — the audio twin of ThemeToggle (jatui-b7qvr): one small
+ * speaker button for the app shell over the headless ambience engine
+ * (`createAmbience()` from `src/lib/ambience/`).
+ *
+ * Interaction contract:
+ *   - Click (or Space/Enter) = play / stop the last scape. A gesture-gated
+ *     engine call, made synchronously inside the click handler.
+ *   - The scape menu (menu button pattern) opens with ArrowDown/ArrowUp,
+ *     a press-and-hold (~450 ms) or a right-click (Android/Chrome fire
+ *     contextmenu on touch holds; iOS may cancel the pointer instead —
+ *     the keyboard path always works). It lists every
+ *     registered scape grouped meditation / focus / noise / nature / music
+ *     (`menuitemradio` items, current scape checked), carries a volume
+ *     slider wired to `engine.setVolume`, and shows each scape's
+ *     `description` as its secondary line — playlist scapes put their
+ *     track attribution there.
+ *
+ * A11y: the trigger is `aria-pressed` while playing and carries the full
+ * menu-button wiring (`aria-expanded` / `aria-haspopup` / `aria-controls`).
+ * An sr-only description teaches the menu gestures, and an `aria-live`
+ * status line announces state changes ("Ambience: Hibiscus, playing").
+ * The speaker glyph morphs off↔on on the motion tokens and, while playing,
+ * breathes with `engine.onBreath` — ambient motion, so it is static under
+ * `prefers-reduced-motion` and `data-motion="calm"`.
+ *
+ * Token-only theming (DaisyUI + `--jatui-*` + `--motion-*`). SSR-safe: the
+ * engine is lazy and nothing here touches `window` at import.
+ */
+import type { Ambience, Scape, ScapeGroup } from '../ambience/types';
+/** Canonical menu group order (the Scape contract's groups). */
+export declare const AMBIENCE_GROUP_ORDER: readonly ScapeGroup[];
+/** Human labels for the canonical groups. */
+export declare const GROUP_LABELS: Readonly<Record<ScapeGroup, string>>;
+/** One grouped section of the scape menu. */
+export interface AmbienceScapeGroup {
+    group: ScapeGroup;
+    label: string;
+    scapes: Scape[];
+}
+/**
+ * Group scapes for the menu: canonical group order, registration order
+ * within a group, empty groups omitted. A group outside the union (a
+ * registry from a newer engine) still renders, after the known ones, in
+ * first-seen order — a menu never silently drops a registered scape.
+ */
+export declare function groupScapes(scapes: Scape[]): AmbienceScapeGroup[];
+/**
+ * The live label — "Ambience: Hibiscus, playing" while sounding,
+ * "Ambience: Hibiscus, stopped" once a scape has been selected but is not
+ * playing, "Ambience: off" before anything was selected.
+ */
+export declare function ambienceLiveLabel(currentLabel: string | null, playing: boolean): string;
+/** Transient failure label — a rejected engine.play() (gesture probe,
+ * context suspend, unknown scape) must never surface as an unhandled
+ * rejection OR as silence: the trigger visibly fails to respond, so the
+ * sr-only status explains it. Cleared by the next successful play. */
+export declare const PLAY_ERROR_LABEL = "Ambience: couldn't start \u2014 tap again";
+/**
+ * Glyph scale for a breath value (0..1): the speaker grows on the inhale
+ * and settles on the exhale — 6% total, clamped against out-of-range input.
+ */
+export declare function breathScale(value: number): number;
+type $$ComponentProps = {
+    /** The engine instance (from `createAmbience()`). The component never creates one, and never kills it — the host owns the engine's lifecycle. */
+    engine: Ambience;
+    /** Smaller app-shell footprint: 40px trigger with an 18px glyph (default 44px / 20px). Never below the 40px touch floor. */
+    compact?: boolean;
+    /** Which way the menu opens from the trigger. Auto-flips vertically when the viewport has no room on that side. */
+    placement?: 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end';
+};
+declare const AmbienceToggle: import("svelte").Component<$$ComponentProps, {}, "">;
+type AmbienceToggle = ReturnType<typeof AmbienceToggle>;
+export default AmbienceToggle;

package/dist/components/VideoPlayer.svelte

@@ -265,10 +265,12 @@
 		SETTINGS_WRITE_DELAY_MS,
 		VIDEO_SETTINGS,
 		REMEMBERED_MUTED,
+		REMEMBERED_TRANSCRIPT,
 		REMEMBERED_VOLUME,
 		type SettingAvailability,
 		type SettingsSession,
 		type SettingValue,
+		type TranscriptLayout,
 		type VideoSettingsStore
 	} from '../video/settings';
 	import SettingsPanel from '../video/settings/SettingsPanel.svelte';
@@ -458,6 +460,15 @@
 		talkTime?: VideoSpeakerTalkTime[];
 		/** Seek here once metadata lands (a queued seek never fires on a later source). */
 		startAt?: number | null;
+		/**
+		 * Where the transcript sits when the viewer has not chosen otherwise —
+		 * `'below'` the player, or beside it (`'side'`) on wide viewports. The
+		 * viewer's Shift+T cycles the layout: side / below / hidden (E24,
+		 * jatui-kgsxf) and the choice is remembered per viewer under the
+		 * `player.transcript` setting — through `settingsStore` when one is
+		 * given, else this browser's localStorage (every access guarded). A
+		 * remembered choice wins over this prop.
+		 */
 		transcriptPosition?: 'below' | 'side';
 		/**
 		 * CSS length bounding the transcript pane's height — it scrolls inside
@@ -924,7 +935,14 @@
 	let baseRate = $state(1);
 
 	// ── Transcript + help overlays ──────────────────────────────────────────
-	let transcriptVisible = $state(true);
+	/**
+	 * The viewer's transcript layout (E24, jatui-kgsxf): the host's
+	 * `transcriptPosition` prop is the default; a remembered choice wins over
+	 * it. The side layout is the beside-the-video grid, below the pane under
+	 * the player, hidden — no pane at all.
+	 */
+	let transcriptChoice = $state<TranscriptLayout | null>(null);
+	const transcriptLayout = $derived(transcriptChoice ?? transcriptPosition);
 	let keysOpen = $state(false);
 
 	// ── Transcript search (jatui-xmtnv) ────────────────────────────────
@@ -2386,6 +2404,54 @@
 		flashOsd(next ? 'Theater mode' : 'Default view');
 	}
 
+	// ── Transcript layout cycle (E24, jatui-kgsxf) ─────────────────────────
+	// The extension's T cycles three layouts: beside the video, below, hidden
+	// (library.js:6137, 9346). The host's `transcriptPosition` prop is the
+	// default; a remembered choice wins over it, and survives a reload — the
+	// same store split as the media state (the host's `settingsStore`, else
+	// this browser's localStorage), `settings/remembered.ts` holds the id and
+	// the never-throws coercion.
+	const TRANSCRIPT_CYCLE = ['side', 'below', 'hidden'] as const;
+	const localTranscriptStore = localSettingsStore();
+	let transcriptTouched = false;
+
+	function cycleTranscript() {
+		if (sortedSegments.length === 0) return;
+		const idx = TRANSCRIPT_CYCLE.indexOf(transcriptLayout);
+		const next = TRANSCRIPT_CYCLE[(idx + 1) % TRANSCRIPT_CYCLE.length];
+		transcriptChoice = next;
+		rememberTranscriptLayout(next);
+		flashOsd(
+			next === 'side' ? 'Transcript beside' : next === 'below' ? 'Transcript below' : 'Transcript hidden'
+		);
+	}
+
+	/** A viewer choice from outside the panel (Shift+T) — saved like one. */
+	function rememberTranscriptLayout(v: TranscriptLayout) {
+		transcriptTouched = true;
+		writeRemembered(settingsStore ?? localTranscriptStore, REMEMBERED_TRANSCRIPT.id, v);
+	}
+
+	// The load-time read, once per store identity: a junk or throwing store
+	// reads as nothing stored, and a choice made before the read resolves wins
+	// (the settings session's rule, mirrored here).
+	$effect(() => {
+		const store = settingsStore ?? localTranscriptStore;
+		let cancelled = false;
+		untrack(() => {
+			void Promise.resolve(store.get(REMEMBERED_TRANSCRIPT.id))
+				.then((raw) => {
+					if (cancelled || transcriptTouched) return;
+					const v = REMEMBERED_TRANSCRIPT.coerce(raw);
+					if (v !== undefined) transcriptChoice = v;
+				})
+				.catch(() => {});
+		});
+		return () => {
+			cancelled = true;
+		};
+	});
+
 	// ── Remembered volume & mute (E12, jatui-xz6so) ──────────────────────
 	// Extension library.js:5768 — the volume level and the mute choice survive
 	// a reload, persisted through the same store the settings registry writes
@@ -3160,8 +3226,7 @@
 			case 'T':
 				if (sortedSegments.length > 0) {
 					e.preventDefault();
-					transcriptVisible = !transcriptVisible;
-					flashOsd(transcriptVisible ? 'Transcript shown' : 'Transcript hidden');
+					cycleTranscript();
 				}
 				return;
 			case '/':
@@ -3317,7 +3382,9 @@
 	 *  it focus once it mounts — the effect below lands it. */
 	function openSearch() {
 		if (sortedSegments.length === 0) return;
-		transcriptVisible = true;
+		// Showing the pane for the search is transient — the viewer's own
+		// layout choice (possibly hidden) is not overwritten.
+		if (transcriptLayout === 'hidden') transcriptChoice = transcriptPosition;
 		searchOpen = true;
 		searchMatchIdx = -1;
 	}
@@ -3447,7 +3514,7 @@
 <div
 	class="vp-root {className}"
 	bind:this={rootEl}
-	class:vp-side={transcriptPosition === 'side' && !theaterOn && sortedSegments.length > 0 && transcriptVisible}
+	class:vp-side={transcriptLayout === 'side' && !theaterOn && sortedSegments.length > 0}
 	class:vp-theater={theaterOn}
 	data-theater={theaterAvailable ? String(theaterOn) : undefined}
 	class:vp-rail-side={railOn}
@@ -4097,7 +4164,7 @@
 		<div class="vp-below-stage">{@render belowStage()}</div>
 	{/if}
 
-	{#if sortedSegments.length > 0 && transcriptVisible}
+	{#if sortedSegments.length > 0 && transcriptLayout !== 'hidden'}
 		<!-- Height-bounded (jatui-ap4oz): the pane scrolls itself and never
 		     the page, so the video stays in frame. Below the player the bound
 		     is `transcriptMaxHeight` (default min(40vh, 28rem)); beside it, the

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

@@ -167,6 +167,15 @@ type $$ComponentProps = {
     talkTime?: VideoSpeakerTalkTime[];
     /** Seek here once metadata lands (a queued seek never fires on a later source). */
     startAt?: number | null;
+    /**
+     * Where the transcript sits when the viewer has not chosen otherwise —
+     * `'below'` the player, or beside it (`'side'`) on wide viewports. The
+     * viewer's Shift+T cycles the layout: side / below / hidden (E24,
+     * jatui-kgsxf) and the choice is remembered per viewer under the
+     * `player.transcript` setting — through `settingsStore` when one is
+     * given, else this browser's localStorage (every access guarded). A
+     * remembered choice wins over this prop.
+     */
     transcriptPosition?: 'below' | 'side';
     /**
      * CSS length bounding the transcript pane's height — it scrolls inside

package/dist/index.d.ts

@@ -405,3 +405,9 @@ export * from './data/grid/index';
 export { default as ImageReveal } from './components/ImageReveal.svelte';
 export { imageRevealPhase, imageRevealBusy, imageRevealInitials, imageRevealSize, imageRevealTone, IMAGE_REVEAL_SIZES, IMAGE_REVEAL_RADIUS } from './components/imageReveal';
 export type { ImageRevealPhase, ImageRevealShape, ImageRevealSizeName, ImageRevealToneName, ImageRevealState } from './components/imageReveal';
+export { default as AmbienceToggle, AMBIENCE_GROUP_ORDER } from './components/AmbienceToggle.svelte';
+export { createAmbience, createDefaultAmbience, DEFAULT_SCAPES, BreathClock, BREATHS_PER_MINUTE, MASTER, ScapeRegistry, hibiscusScape, focusScape, noiseScapes, brownNoiseScape, pinkNoiseScape, whiteNoiseScape, rain, waves } from './ambience';
+export type { DefaultAmbienceOptions } from './ambience';
+export type { Ambience, AmbienceOptions, AmbienceState, BreathState, Scape, ScapeContext, ScapeGroup, ScapeInstance } from './ambience';
+export { createPlaylistScape } from './ambience';
+export type { PlaylistScape, PlaylistScapeOptions, PlaylistManifest, PlaylistState, PlaylistStatus, PlaylistTrack } from './ambience';

package/dist/index.js

@@ -451,3 +451,12 @@ export { default as SettingsRow } from './components/settings/SettingsRow.svelte
 export * from './data/grid/index';
 export { default as ImageReveal } from './components/ImageReveal.svelte';
 export { imageRevealPhase, imageRevealBusy, imageRevealInitials, imageRevealSize, imageRevealTone, IMAGE_REVEAL_SIZES, IMAGE_REVEAL_RADIUS } from './components/imageReveal';
+// Ambience — generative background-sound engine (headless) + the app-shell
+// AmbienceToggle. Mount the engine once at the root layout so sound survives
+// navigation; createDefaultAmbience() pre-registers every shipped scape
+// (hibiscus, focus, brown/pink/white noise, rain, waves).
+export { default as AmbienceToggle, AMBIENCE_GROUP_ORDER } from './components/AmbienceToggle.svelte';
+export { createAmbience, createDefaultAmbience, DEFAULT_SCAPES, BreathClock, BREATHS_PER_MINUTE, MASTER, ScapeRegistry, hibiscusScape, focusScape, noiseScapes, brownNoiseScape, pinkNoiseScape, whiteNoiseScape, rain, waves } from './ambience';
+// Playlist scape (phase 2) — per-host, never in DEFAULT_SCAPES: build with
+// createPlaylistScape() and register on the engine yourself.
+export { createPlaylistScape } from './ambience';

package/dist/video/keys.d.ts

@@ -5,9 +5,10 @@
  *
  * Map parity is with extension-library's theater handler (FEATURES.md):
  * Space play/pause, ←/→ seek, ↑/↓ volume, M mute, −/= speed, Backspace reset
- * speed, </> frame step, [/] chapter jumps, B bookmark, Shift+T transcript
- * (t is theater mode, YouTube's key — jatui-ee2ty), ?
- * shortcuts, Home/End, and `/` transcript search (the pane has none yet).
+ * speed, </> frame step, [/] chapter jumps, B bookmark, Shift+T transcript layout
+ * cycle (side / below / hidden — jatui-kgsxf), t is theater mode (YouTube's key
+ * — jatui-ee2ty), ? shortcuts, Home/End, and `/` transcript search (the pane has
+ * none yet).
  * Deliberately NOT ported: F/M (favourite/file-under — library-app verbs,
  * not player verbs). N (night cycle) landed with the night module
  * (mos-5lzns.33) and `,` (settings) with the settings panel

package/dist/video/keys.js

@@ -5,9 +5,10 @@
  *
  * Map parity is with extension-library's theater handler (FEATURES.md):
  * Space play/pause, ←/→ seek, ↑/↓ volume, M mute, −/= speed, Backspace reset
- * speed, </> frame step, [/] chapter jumps, B bookmark, Shift+T transcript
- * (t is theater mode, YouTube's key — jatui-ee2ty), ?
- * shortcuts, Home/End, and `/` transcript search (the pane has none yet).
+ * speed, </> frame step, [/] chapter jumps, B bookmark, Shift+T transcript layout
+ * cycle (side / below / hidden — jatui-kgsxf), t is theater mode (YouTube's key
+ * — jatui-ee2ty), ? shortcuts, Home/End, and `/` transcript search (the pane has
+ * none yet).
  * Deliberately NOT ported: F/M (favourite/file-under — library-app verbs,
  * not player verbs). N (night cycle) landed with the night module
  * (mos-5lzns.33) and `,` (settings) with the settings panel
@@ -33,7 +34,7 @@ export const PLAYER_KEYS = [
     { keys: 'B', description: 'Bookmark at the current time', when: 'bookmarks' },
     // t = theater, YouTube's key; the transcript moved to Shift+T (jatui-ee2ty).
     { keys: 't', description: 'Theater mode on / off', when: 'theater' },
-    { keys: 'Shift+T', description: 'Show / hide the transcript', when: 'transcript' },
+    { keys: 'Shift+T', description: 'Cycle transcript layout: side / below / hidden', when: 'transcript' },
     { keys: '/', description: 'Search transcript', when: 'transcript' },
     // Shift+wheel over the transcript pane steps PLAYBACK line by line —
     // a plain wheel there scrolls the pane natively and is never claimed.

package/dist/video/settings/remembered.d.ts

@@ -26,5 +26,14 @@ export interface RememberedSpec<T> {
 }
 /** The playback level, 0–1 on the player's 0.05 gesture grid. */
 export declare const REMEMBERED_VOLUME: RememberedSpec<number>;
+/**
+ * The transcript layout (E24, jatui-kgsxf) — the extension's T cycles three
+ * layouts: beside the video, below it, hidden (library.js:6137, 9346). The
+ * host's `transcriptPosition` prop is the default; a remembered choice wins
+ * over it, and survives a reload. `default` here is only the fallback when a
+ * store holds nothing usable — the host's prop is the real default.
+ */
+export type TranscriptLayout = 'side' | 'below' | 'hidden';
+export declare const REMEMBERED_TRANSCRIPT: RememberedSpec<TranscriptLayout>;
 /** Whether playback starts muted. */
 export declare const REMEMBERED_MUTED: RememberedSpec<boolean>;

package/dist/video/settings/remembered.js

@@ -30,6 +30,15 @@ export const REMEMBERED_VOLUME = {
         }
     }
 };
+export const REMEMBERED_TRANSCRIPT = {
+    id: 'player.transcript',
+    default: 'below',
+    coerce(raw) {
+        if (raw === 'side' || raw === 'below' || raw === 'hidden')
+            return raw;
+        return undefined;
+    }
+};
 /** Whether playback starts muted. */
 export const REMEMBERED_MUTED = {
     id: 'player.muted',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joewinke/jatui",
-  "version": "0.46.0",
+  "version": "0.48.0",
   "private": false,
   "description": "Shared Svelte 5 component library for JAT projects",
   "type": "module",
@@ -87,6 +87,11 @@
       "types": "./dist/artifact-blocks/index.d.ts",
       "svelte": "./dist/artifact-blocks/index.js",
       "default": "./dist/artifact-blocks/index.js"
+    },
+    "./ambience": {
+      "types": "./dist/ambience/index.d.ts",
+      "svelte": "./dist/ambience/index.js",
+      "default": "./dist/ambience/index.js"
     }
   },
   "files": [