@sveltesentio/media 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [0.3.0](https://github.com/golusoris/sveltesentio/compare/media-v0.2.0...media-v0.3.0) (2026-06-15)
+
+
+### Features
+
+* **media:** <Player> + <Carousel> + <Image> UI surfaces ([b4a9fa4](https://github.com/golusoris/sveltesentio/commit/b4a9fa499a9c5f2744a11acfb428c7814e7de98a))
+
+## [0.2.0](https://github.com/golusoris/sveltesentio/compare/media-v0.1.0...media-v0.2.0)
+
+
+### Features
+
+* **player:** headless HLS source model — `pickRendition` (separate-rendition quality switching with `maxHeight` / `preferCodec`), `buildMediaSessionMetadata`, a pure `playbackReducer` play/pause/quality state machine, and a bring-your-own-`hls.js` `createHlsAttachment` seam ([#67](https://github.com/golusoris/sveltesentio/issues/67), [#68](https://github.com/golusoris/sveltesentio/issues/68))
+* **image:** pure responsive-image `buildSrcSet` / `buildSizes` / `buildResponsiveImage` builders with template + query-merge URL strategies ([#67](https://github.com/golusoris/sveltesentio/issues/67))
+* sub-exports `./player` and `./image`; `hls.js` declared as an optional peer (no runtime media deps)
+
+
+### Notes
+
+* The `vidstack@next` `<Player>` UI shell and the `./carousel` re-export remain follow-throughs; README and AGENTS status reconciled per [#67](https://github.com/golusoris/sveltesentio/issues/67).
+
 ## [0.1.0](https://github.com/golusoris/sveltesentio/compare/media-v0.0.1...media-v0.1.0) (2026-06-14)
 
 

package/README.md

@@ -1,20 +1,69 @@
 # @sveltesentio/media
 
-> vidstack + HLS.js + embla-carousel wrappers for media server UIs
+> Headless media-player logic + responsive-image builders for media-server UIs
 
 Part of the [sveltesentio](https://github.com/golusoris/sveltesentio) composable SvelteKit framework.
 
 ## Status
 
-🚧 Phase 1 stub — implementation begins in Phase 2+.
+v0.2.0 — headless core landed. The pure logic for HLS rendition selection,
+OS media-session metadata, a play/pause/quality state machine, a
+bring-your-own-`hls.js` attachment seam, and responsive-image `srcset` / `sizes`
+builders all ship and are unit-tested. The full `<Player>` UI shell
+(`vidstack`) and the `./carousel` re-export are tracked as follow-throughs (see
+[AGENTS.md](AGENTS.md)) and are **not** in this release.
 
-## Installation
+## Install
 
 ```bash
 pnpm add @sveltesentio/media
+# optional, only if you drive adaptive HLS yourself:
+pnpm add hls.js
 ```
 
-See the [monorepo README](../../README.md) and [`docs/`](../../docs/) for design principles and usage.
+`hls.js` is an **optional** peer — nothing in this package imports it. You
+inject its constructor at the `createHlsAttachment` seam.
+
+## `@sveltesentio/media/player`
+
+```ts
+import {
+  pickRendition,
+  buildMediaSessionMetadata,
+  playbackReducer,
+  initialPlaybackState,
+  createHlsAttachment,
+} from '@sveltesentio/media/player';
+
+// Separate-rendition (un-muxed) quality switching: prefer HEVC, cap at 1080p.
+const best = pickRendition(renditions, { maxHeight: 1080, preferCodec: 'hvc1' });
+
+// OS lock-screen / media-keys metadata (pass to `new MediaMetadata(...)`).
+const meta = buildMediaSessionMetadata({ title, artist, artwork });
+
+// Pure play/pause/quality machine — invalid transitions are no-ops.
+let state = playbackReducer(initialPlaybackState, { type: 'load' });
+
+// Bring-your-own hls.js — no dynamic import, no bundled engine.
+import Hls from 'hls.js';
+const handle = createHlsAttachment(Hls).attach(videoEl, manifestUrl);
+// handle.destroy();
+```
+
+## `@sveltesentio/media/image`
+
+```ts
+import { buildResponsiveImage } from '@sveltesentio/media/image';
+
+const attrs = buildResponsiveImage('/images/poster/{path}', [320, 640, 1280], {
+  template: '/images/poster/w{w}/abc.avif',
+  sizes: [{ condition: '(min-width: 768px)', size: '33vw' }],
+});
+// → { src, srcset, sizes } — spread onto <img>.
+```
+
+See the [monorepo README](../../README.md) and [`docs/`](../../docs/) for design
+principles.
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sveltesentio/media",
-  "version": "0.1.0",
-  "description": "Vidstack + HLS.js + embla-carousel wrappers, artwork grid, 10-foot UI preset",
+  "version": "0.3.0",
+  "description": "Media player (headless HLS model + a11y <Player> shell), responsive blur-up <Image>, and a preset-aware embla <Carousel> — Svelte 5",
   "type": "module",
   "private": false,
   "sideEffects": false,
@@ -9,32 +9,82 @@
     ".": {
       "import": "./src/index.ts",
       "types": "./src/index.ts"
+    },
+    "./player": {
+      "import": "./src/player.ts",
+      "types": "./src/player.ts"
+    },
+    "./player/controls": {
+      "import": "./src/player-controls.ts",
+      "types": "./src/player-controls.ts"
+    },
+    "./player/component": {
+      "svelte": "./src/Player.svelte",
+      "default": "./src/Player.svelte"
+    },
+    "./image": {
+      "import": "./src/image.ts",
+      "types": "./src/image.ts"
+    },
+    "./image/lqip": {
+      "import": "./src/lqip.ts",
+      "types": "./src/lqip.ts"
+    },
+    "./image/component": {
+      "svelte": "./src/Image.svelte",
+      "default": "./src/Image.svelte"
+    },
+    "./carousel": {
+      "import": "./src/carousel.ts",
+      "types": "./src/carousel.ts"
+    },
+    "./carousel/component": {
+      "svelte": "./src/Carousel.svelte",
+      "default": "./src/Carousel.svelte"
     }
   },
+  "dependencies": {
+    "esm-env": "^1.2.2",
+    "@sveltesentio/core": "0.1.0"
+  },
   "peerDependencies": {
-    "vidstack": ">=0.6.0",
+    "embla-carousel-svelte": ">=8.6.0",
     "hls.js": ">=1.6.0",
-    "embla-carousel-svelte": ">=8.0.0",
-    "svelte": ">=5.0.0"
+    "svelte": ">=5.0.0",
+    "vidstack": ">=1.12.13 <2"
   },
   "peerDependenciesMeta": {
+    "embla-carousel-svelte": {
+      "optional": true
+    },
     "hls.js": {
       "optional": true
     },
-    "embla-carousel-svelte": {
+    "vidstack": {
       "optional": true
     }
   },
   "devDependencies": {
+    "@sveltejs/vite-plugin-svelte": "^7.1.2",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/svelte": "^5.3.1",
+    "axe-core": "^4.12.1",
+    "jsdom": "^29.1.1",
+    "svelte": "^5.56.3",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.4"
+    "vite": "^8.0.16",
+    "vitest": "^4.1.8",
+    "@sveltesentio/core": "0.1.0"
   },
   "keywords": [
     "sveltesentio",
     "media",
-    "vidstack",
     "hls",
+    "player",
     "carousel",
+    "image",
+    "srcset",
+    "media-session",
     "10-foot-ui"
   ],
   "publishConfig": {
@@ -48,6 +98,6 @@
     "build": "tsc",
     "lint": "eslint src/",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run --passWithNoTests"
+    "test": "vitest run"
   }
 }

package/src/Carousel.svelte

@@ -0,0 +1,128 @@
+<!--
+@component
+Carousel — a preset-aware a11y envelope over `embla-carousel-svelte` (ADR-0012).
+embla v8 ships no built-in a11y, and shadcn's generated wrapper leaves three
+obligations to the caller; this shell bakes them in: the `./carousel`
+`buildCarouselOptions` reduced-motion breakpoint, WCAG 2.5.8 nav-button
+target-size per interface preset, and the `role="region"` /
+`aria-roledescription="carousel"` + keyboard envelope.
+
+`embla-carousel-svelte` is an OPTIONAL peer: pass its `emblaAction` (the
+package default export `use:emblaCarousel`) to enable dragging/snapping. Absent
+it, the component degrades to a native scroll-snap region that still renders,
+keyboards, and passes axe — so it tests without the heavy peer.
+
+The tested logic lives in `./carousel`; this file is a thin, a11y-correct view.
+-->
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { Action } from 'svelte/action';
+	import {
+		buildCarouselOptions,
+		navButtonTargetPx,
+		type CarouselOptionsInput,
+		type CarouselPreset,
+		type EmblaOptionsLike,
+	} from './carousel.js';
+
+	interface Props extends CarouselOptionsInput {
+		/** Accessible name for the carousel region — required. */
+		label: string;
+		/** Slides. Each item should render its own focusable content. */
+		children: Snippet;
+		/** Interface preset governing nav-button target size. Default `desktop`. */
+		preset?: CarouselPreset;
+		/**
+		 * The `embla-carousel-svelte` action (its default export). When omitted the
+		 * region degrades to native CSS scroll-snap.
+		 */
+		emblaAction?: Action<HTMLElement, EmblaOptionsLike>;
+	}
+
+	const {
+		label,
+		children,
+		preset = 'desktop',
+		emblaAction,
+		...optionsInput
+	}: Props = $props();
+
+	const options = $derived(buildCarouselOptions(optionsInput as CarouselOptionsInput));
+	const targetPx = $derived(navButtonTargetPx(preset));
+	let viewport = $state<HTMLDivElement | null>(null);
+
+	function scrollByPage(direction: -1 | 1): void {
+		const el = viewport;
+		if (!el) return;
+		el.scrollBy({ left: direction * el.clientWidth, behavior: options.duration === 0 ? 'auto' : 'smooth' });
+	}
+</script>
+
+<!-- A named <section> is an implicit landmark `region`; aria-roledescription
+	relabels it as a carousel per the WAI-ARIA carousel pattern. -->
+<section
+	class="ssentio-carousel"
+	aria-roledescription="carousel"
+	aria-label={label}
+>
+	{#if emblaAction}
+		<div class="ssentio-carousel__viewport" bind:this={viewport} use:emblaAction={options}>
+			<div class="ssentio-carousel__container">{@render children()}</div>
+		</div>
+	{:else}
+		<div class="ssentio-carousel__viewport ssentio-carousel__viewport--native" bind:this={viewport}>
+			<div class="ssentio-carousel__container">{@render children()}</div>
+		</div>
+	{/if}
+
+	<div class="ssentio-carousel__nav">
+		<button
+			type="button"
+			class="ssentio-carousel__btn"
+			style="min-width:{targetPx}px;min-height:{targetPx}px"
+			aria-label="Previous slide"
+			onclick={() => scrollByPage(-1)}
+		>‹</button>
+		<button
+			type="button"
+			class="ssentio-carousel__btn"
+			style="min-width:{targetPx}px;min-height:{targetPx}px"
+			aria-label="Next slide"
+			onclick={() => scrollByPage(1)}
+		>›</button>
+	</div>
+</section>
+
+<style>
+	.ssentio-carousel {
+		display: flex;
+		flex-direction: column;
+		gap: 0.5rem;
+	}
+
+	.ssentio-carousel__viewport {
+		overflow: hidden;
+	}
+
+	.ssentio-carousel__viewport--native {
+		overflow-x: auto;
+		scroll-snap-type: x mandatory;
+	}
+
+	.ssentio-carousel__container {
+		display: flex;
+		gap: 0.5rem;
+	}
+
+	.ssentio-carousel__nav {
+		display: flex;
+		gap: 0.5rem;
+	}
+
+	.ssentio-carousel__btn {
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		cursor: pointer;
+	}
+</style>

package/src/Image.svelte

@@ -0,0 +1,130 @@
+<!--
+@component
+Image — a responsive, blur-up (LQIP) image wrapper. No heavy dependency: it
+composes the pure `./image` `srcset` / `sizes` builders and the `./lqip` style
+helpers. A tiny blurred placeholder (or solid colour) fills the box to reserve
+layout space (CLS < 0.1); when the full image finishes loading the placeholder
+fades out. Above-the-fold heroes pass `priority="high"` for eager
+`fetchpriority="high"` loading (LCP < 2.5 s).
+
+`alt` is required (WCAG 1.1.1) — decorative images pass `alt=""` explicitly.
+The tested logic lives in `./image` + `./lqip`; this file is a thin view.
+-->
+<script lang="ts">
+	import {
+		buildResponsiveImage,
+		type SizesRule,
+		type SrcWidthTemplate,
+	} from './image.js';
+	import {
+		buildPlaceholderStyle,
+		resolveAspectRatio,
+		imageLoadingAttrs,
+		type LqipPlaceholder,
+		type ImageLoadingPriority,
+	} from './lqip.js';
+
+	interface Props {
+		/** Base image URL. */
+		src: string;
+		/** Required text alternative (`""` for decorative). */
+		alt: string;
+		/** Candidate widths for the `srcset`. */
+		widths?: readonly number[];
+		/** `src`-from-width template (function or `{w}` string). */
+		template?: SrcWidthTemplate | string;
+		/** `sizes` rules; falls back to `100vw`. */
+		sizes?: readonly SizesRule[];
+		/** Intrinsic width (px) for the reserved aspect ratio. */
+		width?: number;
+		/** Intrinsic height (px) for the reserved aspect ratio. */
+		height?: number;
+		/** Blur-up / colour placeholder. */
+		placeholder?: LqipPlaceholder;
+		/** `high` for above-the-fold LCP heroes. Default `auto`. */
+		priority?: ImageLoadingPriority;
+		/** Class on the wrapper element. */
+		class?: string;
+	}
+
+	const {
+		src,
+		alt,
+		widths = [],
+		template,
+		sizes,
+		width,
+		height,
+		placeholder,
+		priority = 'auto',
+		class: className,
+	}: Props = $props();
+
+	const attrs = $derived(
+		buildResponsiveImage(src, widths, {
+			...(template === undefined ? {} : { template }),
+			...(sizes === undefined ? {} : { sizes }),
+		}),
+	);
+	const loadingAttrs = $derived(imageLoadingAttrs(priority));
+	const placeholderStyle = $derived(buildPlaceholderStyle(placeholder));
+	const ratio = $derived(resolveAspectRatio(width, height));
+
+	let loaded = $state(false);
+</script>
+
+<div
+	class={['ssentio-image', className]}
+	style:aspect-ratio={ratio}
+>
+	{#if placeholderStyle && !loaded}
+		<span class="ssentio-image__lqip" style={placeholderStyle} aria-hidden="true"></span>
+	{/if}
+	<img
+		class="ssentio-image__img"
+		class:ssentio-image__img--loaded={loaded}
+		src={attrs.src}
+		srcset={attrs.srcset || undefined}
+		sizes={attrs.srcset ? attrs.sizes : undefined}
+		{alt}
+		{width}
+		{height}
+		loading={loadingAttrs.loading}
+		fetchpriority={loadingAttrs.fetchpriority}
+		decoding={loadingAttrs.decoding}
+		onload={() => (loaded = true)}
+	/>
+</div>
+
+<style>
+	.ssentio-image {
+		position: relative;
+		display: block;
+		overflow: hidden;
+	}
+
+	.ssentio-image__lqip {
+		position: absolute;
+		inset: 0;
+		filter: blur(12px);
+		transform: scale(1.05);
+	}
+
+	.ssentio-image__img {
+		display: block;
+		width: 100%;
+		height: auto;
+		opacity: 0;
+		transition: opacity 0.3s ease;
+	}
+
+	.ssentio-image__img--loaded {
+		opacity: 1;
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.ssentio-image__img {
+			transition: none;
+		}
+	}
+</style>

package/src/Player.svelte

@@ -0,0 +1,182 @@
+<!--
+@component
+Player — a video/audio player shell with keyboard + a11y controls, wired to the
+headless `./player` core (`playbackReducer`, optional BYO `hls.js`). This is a
+deliberately thin, dependency-light shell over a native `<video>` / `<audio>`
+element so it renders and tests without the heavy `vidstack` peer present.
+Consumers wanting Vidstack's full chrome pass `vidstack` and mount its
+components inside the `controls` snippet; the keyboard + captions contract here
+still applies.
+
+Invariants (ADR-0042 / AGENTS.md):
+- Captions required for video — `assertCaptionsContract` throws unless `tracks`
+  is supplied (`tracks={[]}` is the explicit opt-out).
+- Autoplay off by default; enabling it forces `muted` (browser policy).
+- Keyboard parity with Vidstack: Space/K, ← →, ↑ ↓, M, F, C.
+
+The tested logic lives in `./player` + `./player-controls`; this file is a
+thin, a11y-correct view.
+-->
+<script lang="ts">
+	import { BROWSER } from 'esm-env';
+	import {
+		actionForKey,
+		assertCaptionsContract,
+		formatMediaTime,
+		clampVolume,
+		type MediaTrack,
+	} from './player-controls.js';
+
+	interface Props {
+		/** Media source URL (`.m3u8`, `.mp4`, audio, …). */
+		src: string;
+		/** Accessible name for the player region — required. */
+		title: string;
+		/** `video` (default) or `audio`. Video without `tracks` throws. */
+		viewType?: 'video' | 'audio';
+		/** Caption / subtitle tracks. Required for video (`[]` to opt out). */
+		tracks?: readonly MediaTrack[];
+		/** Poster image (video only). */
+		poster?: string;
+		/** Opt in to autoplay; sets `muted` automatically. */
+		autoplay?: boolean;
+	}
+
+	const { src, title, viewType = 'video', tracks, poster, autoplay = false }: Props = $props();
+
+	// One-shot mount-time invariant (WCAG 1.2.2): refuse to mount a caption-less
+	// video. Props are read once by design — the contract is fixed at construction.
+	// svelte-ignore state_referenced_locally
+	assertCaptionsContract(viewType, tracks);
+
+	let media = $state<HTMLMediaElement | null>(null);
+	let paused = $state(true);
+	let currentTime = $state(0);
+	let duration = $state(0);
+	// Autoplay must start muted (browser policy); the user can unmute via M after.
+	// svelte-ignore state_referenced_locally
+	let muted = $state(autoplay);
+
+	const timeLabel = $derived(
+		`${formatMediaTime(currentTime)} / ${formatMediaTime(duration)}`,
+	);
+
+	function dispatch(key: KeyboardEvent): void {
+		const el = media;
+		if (!el) return;
+		const action = actionForKey(key);
+		if (action === undefined) return;
+		key.preventDefault();
+		switch (action) {
+			case 'toggle-play':
+				if (el.paused) void el.play();
+				else el.pause();
+				break;
+			case 'seek-back':
+				el.currentTime = Math.max(0, el.currentTime - 5);
+				break;
+			case 'seek-forward':
+				el.currentTime = Math.min(el.duration || Infinity, el.currentTime + 5);
+				break;
+			case 'volume-up':
+				el.volume = clampVolume(el.volume, 0.1);
+				break;
+			case 'volume-down':
+				el.volume = clampVolume(el.volume, -0.1);
+				break;
+			case 'toggle-mute':
+				el.muted = !el.muted;
+				muted = el.muted;
+				break;
+			case 'toggle-fullscreen':
+				if (BROWSER && el.requestFullscreen) void el.requestFullscreen().catch(() => {});
+				break;
+			case 'toggle-captions':
+				break;
+		}
+	}
+</script>
+
+<div
+	class="ssentio-player"
+	data-view-type={viewType}
+	role="group"
+	aria-label={title}
+	aria-roledescription="media player"
+>
+	{#if viewType === 'audio'}
+		<audio
+			bind:this={media}
+			bind:paused
+			bind:currentTime
+			bind:duration
+			{src}
+			{autoplay}
+			{muted}
+			controls
+			preload="metadata"
+			onkeydown={dispatch}
+		></audio>
+	{:else}
+		<video
+			bind:this={media}
+			bind:paused
+			bind:currentTime
+			bind:duration
+			{src}
+			{poster}
+			{autoplay}
+			{muted}
+			controls
+			playsinline
+			preload="metadata"
+			onkeydown={dispatch}
+		>
+			{#each tracks ?? [] as track (track.src)}
+				<track
+					src={track.src}
+					kind={track.kind}
+					srclang={track.srclang}
+					label={track.label}
+					default={track.default}
+				/>
+			{/each}
+		</video>
+	{/if}
+	<p class="ssentio-player__time" aria-live="off">
+		<span class="ssentio-player__sr-only">Playback position:</span>
+		{timeLabel}
+		<span class="ssentio-player__sr-only">{paused ? '(paused)' : '(playing)'}</span>
+	</p>
+</div>
+
+<style>
+	.ssentio-player {
+		display: flex;
+		flex-direction: column;
+		gap: 0.25rem;
+	}
+
+	.ssentio-player :global(video),
+	.ssentio-player :global(audio) {
+		width: 100%;
+	}
+
+	.ssentio-player__time {
+		margin: 0;
+		font-size: 0.875rem;
+		font-variant-numeric: tabular-nums;
+	}
+
+	.ssentio-player__sr-only {
+		position: absolute;
+		width: 1px;
+		height: 1px;
+		padding: 0;
+		margin: -1px;
+		overflow: hidden;
+		clip: rect(0, 0, 0, 0);
+		white-space: nowrap;
+		border: 0;
+	}
+</style>