@sveltesentio/media 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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)
 
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sveltesentio/media",
-  "version": "0.2.0",
-  "description": "Headless media player model (HLS rendition picking, media-session, play/pause/quality machine, BYO hls.js seam) + responsive-image srcset/sizes builders",
+  "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,
@@ -14,27 +14,75 @@
       "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": {
-    "hls.js": ">=1.6.0"
+    "embla-carousel-svelte": ">=8.6.0",
+    "hls.js": ">=1.6.0",
+    "svelte": ">=5.0.0",
+    "vidstack": ">=1.12.13 <2"
   },
   "peerDependenciesMeta": {
+    "embla-carousel-svelte": {
+      "optional": true
+    },
     "hls.js": {
       "optional": true
+    },
+    "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",
     "hls",
+    "player",
+    "carousel",
+    "image",
     "srcset",
     "media-session",
     "10-foot-ui"

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>

package/src/carousel.ts

@@ -0,0 +1,83 @@
+/**
+ * Headless carousel helpers shared by the `<Carousel>` shell and any consumer
+ * driving `embla-carousel-svelte` directly: a preset-aware embla options
+ * builder that bakes in the two obligations ADR-0012 leaves to the caller —
+ * reduced-motion (collapse transition duration to 0) and target-size
+ * (WCAG 2.5.8 nav-button sizing per interface preset). Pure and DOM-free.
+ *
+ * @see ADR-0012 (embla via shadcn) — the three consumer obligations.
+ */
+
+/** Interface-type preset governing nav-button target size (ADR-0047). */
+export type CarouselPreset = 'desktop' | 'handheld' | 'tv';
+
+/** Carousel scroll axis. */
+export type CarouselOrientation = 'horizontal' | 'vertical';
+
+/**
+ * The subset of `embla-carousel`'s options this helper sets. Structural so the
+ * package needs no `embla-carousel-svelte` dependency (it is an optional peer);
+ * the result spreads onto embla's own options object.
+ */
+export interface EmblaOptionsLike {
+	readonly loop: boolean;
+	readonly align: 'start' | 'center' | 'end';
+	readonly axis: 'x' | 'y';
+	readonly duration: number;
+	readonly dragFree: boolean;
+	/**
+	 * Per-media-query option overrides. The reduced-motion query collapses the
+	 * transition duration so SC 2.3.3 / 2.2.2 are honoured without JS.
+	 */
+	readonly breakpoints: Readonly<Record<string, { readonly duration: number }>>;
+}
+
+export interface CarouselOptionsInput {
+	/** Wrap from last slide to first. Default `false`. */
+	readonly loop?: boolean;
+	/** Slide alignment within the viewport. Default `'start'`. */
+	readonly align?: 'start' | 'center' | 'end';
+	/** Scroll axis. Default `'horizontal'`. */
+	readonly orientation?: CarouselOrientation;
+	/** Embla transition duration (embla time units). Default `25`. */
+	readonly duration?: number;
+	/** Allow free-scroll momentum dragging. Default `false`. */
+	readonly dragFree?: boolean;
+}
+
+const REDUCED_MOTION_QUERY = '(prefers-reduced-motion: reduce)';
+
+/**
+ * Build embla options with the reduced-motion breakpoint always present, so a
+ * consumer who forgets obligation (a) from ADR-0012 still gets a
+ * reduced-motion-correct carousel. The breakpoint sets `duration: 0` (instant
+ * snap) under `prefers-reduced-motion: reduce`.
+ */
+export function buildCarouselOptions(input: CarouselOptionsInput = {}): EmblaOptionsLike {
+	return {
+		loop: input.loop ?? false,
+		align: input.align ?? 'start',
+		axis: (input.orientation ?? 'horizontal') === 'vertical' ? 'y' : 'x',
+		duration: input.duration ?? 25,
+		dragFree: input.dragFree ?? false,
+		breakpoints: {
+			[REDUCED_MOTION_QUERY]: { duration: 0 },
+		},
+	};
+}
+
+/**
+ * Minimum CSS px target size for the carousel's prev/next buttons per preset.
+ * `handheld` / `tv` upgrade to 44 px (WCAG 2.5.8 enhanced / touch + 10-foot
+ * reach); `desktop` keeps the shadcn `size="icon"` 32 px default — above the
+ * 24 px AA minimum (SC 2.5.8).
+ */
+export function navButtonTargetPx(preset: CarouselPreset): number {
+	return preset === 'desktop' ? 32 : 44;
+}
+
+/** Whether the user has requested reduced motion. SSR-safe (`false` server-side). */
+export function carouselPrefersReducedMotion(): boolean {
+	if (typeof globalThis.matchMedia !== 'function') return false;
+	return globalThis.matchMedia(REDUCED_MOTION_QUERY).matches;
+}

package/src/index.ts

@@ -35,3 +35,34 @@ export {
 	buildSizes,
 	buildResponsiveImage,
 } from './image.js';
+
+export type { PlayerAction, MediaTrack } from './player-controls.js';
+export {
+	actionForKey,
+	assertCaptionsContract,
+	formatMediaTime,
+	clampVolume,
+} from './player-controls.js';
+
+export type {
+	CarouselPreset,
+	CarouselOrientation,
+	EmblaOptionsLike,
+	CarouselOptionsInput,
+} from './carousel.js';
+export {
+	buildCarouselOptions,
+	navButtonTargetPx,
+	carouselPrefersReducedMotion,
+} from './carousel.js';
+
+export type {
+	LqipPlaceholder,
+	ImageLoadingPriority,
+	ImageLoadingAttrs,
+} from './lqip.js';
+export {
+	buildPlaceholderStyle,
+	resolveAspectRatio,
+	imageLoadingAttrs,
+} from './lqip.js';

package/src/lqip.ts

@@ -0,0 +1,82 @@
+/**
+ * Headless LQIP (low-quality image placeholder) / blur-up helpers for the
+ * `<Image>` wrapper. Builds the inline background style for the blurred
+ * placeholder and resolves the layout-shift-free aspect ratio. Pure and
+ * DOM-free so the styling logic is unit-tested without rendering.
+ *
+ * @see docs/compose/image-optimization.md — LCP < 2.5 s / CLS < 0.1 gates.
+ */
+
+/** A placeholder source: an inline data-URI (or any URL) plus an optional solid colour. */
+export interface LqipPlaceholder {
+	/** Tiny blurred image, typically a base64 data-URI. */
+	readonly src?: string;
+	/** Solid fallback colour shown before the blurred image decodes. */
+	readonly color?: string;
+}
+
+/**
+ * Build the `background` CSS for the placeholder layer. A data-URI / URL becomes
+ * a covering `background-image` (with an optional solid colour beneath it);
+ * a colour-only placeholder becomes a flat fill. Returns `undefined` when no
+ * placeholder is supplied, so the caller can omit the layer entirely.
+ */
+export function buildPlaceholderStyle(placeholder: LqipPlaceholder | undefined): string | undefined {
+	if (placeholder === undefined) return undefined;
+	const { src, color } = placeholder;
+	if (src !== undefined && src !== '') {
+		const layers = [`url("${cssEscapeUrl(src)}") center / cover no-repeat`];
+		if (color !== undefined && color !== '') layers.push(color);
+		return `background: ${layers.join(', ')};`;
+	}
+	if (color !== undefined && color !== '') return `background: ${color};`;
+	return undefined;
+}
+
+/** Escape the characters that would break out of a CSS `url("…")` token. */
+function cssEscapeUrl(url: string): string {
+	return url.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+/**
+ * Resolve an `aspect-ratio` CSS value from intrinsic width/height. Returns
+ * `undefined` when either dimension is missing or non-positive, so the caller
+ * only reserves space when it can do so correctly (avoids a wrong-ratio CLS).
+ */
+export function resolveAspectRatio(
+	width: number | undefined,
+	height: number | undefined,
+): string | undefined {
+	if (
+		width === undefined ||
+		height === undefined ||
+		!Number.isFinite(width) ||
+		!Number.isFinite(height) ||
+		width <= 0 ||
+		height <= 0
+	) {
+		return undefined;
+	}
+	return `${width} / ${height}`;
+}
+
+/** Loading priority for the underlying `<img>`. */
+export type ImageLoadingPriority = 'auto' | 'high';
+
+export interface ImageLoadingAttrs {
+	readonly loading: 'lazy' | 'eager';
+	readonly fetchpriority: 'high' | 'auto';
+	readonly decoding: 'async';
+}
+
+/**
+ * Derive the `loading` / `fetchpriority` / `decoding` attributes. `high`
+ * priority (an above-the-fold LCP hero) eager-loads with `fetchpriority="high"`;
+ * everything else lazy-loads. `decoding` is always `async` to keep the main
+ * thread free.
+ */
+export function imageLoadingAttrs(priority: ImageLoadingPriority = 'auto'): ImageLoadingAttrs {
+	return priority === 'high'
+		? { loading: 'eager', fetchpriority: 'high', decoding: 'async' }
+		: { loading: 'lazy', fetchpriority: 'auto', decoding: 'async' };
+}

package/src/player-controls.ts

@@ -0,0 +1,124 @@
+/**
+ * Headless player-control helpers for the `<Player>` shell: keyboard-event →
+ * action mapping (Vidstack-compatible defaults), a captions-invariant guard,
+ * and time formatting for the progress label. Pure and DOM-free so the mapping
+ * table is unit-tested without rendering a component.
+ *
+ * @see ADR-0042 (Vidstack `@next` + `hls.js`) — keyboard parity with Vidstack.
+ */
+
+import { ProblemError } from '@sveltesentio/core';
+
+/** A discrete player control intent produced by a key press. */
+export type PlayerAction =
+	| 'toggle-play'
+	| 'seek-back'
+	| 'seek-forward'
+	| 'volume-up'
+	| 'volume-down'
+	| 'toggle-mute'
+	| 'toggle-fullscreen'
+	| 'toggle-captions';
+
+/**
+ * Map a keyboard event to a player action, mirroring Vidstack's default
+ * shortcuts: Space / K toggle play, ← → seek, ↑ ↓ volume, M mute, F fullscreen,
+ * C captions. Returns `undefined` for unmapped keys or when a modifier is held
+ * (so browser/OS chords are never hijacked). Matching is case-insensitive.
+ */
+export function actionForKey(event: {
+	readonly key: string;
+	readonly ctrlKey?: boolean;
+	readonly metaKey?: boolean;
+	readonly altKey?: boolean;
+}): PlayerAction | undefined {
+	if (event.ctrlKey || event.metaKey || event.altKey) return undefined;
+	switch (event.key.toLowerCase()) {
+		case ' ':
+		case 'spacebar':
+		case 'k':
+			return 'toggle-play';
+		case 'arrowleft':
+			return 'seek-back';
+		case 'arrowright':
+			return 'seek-forward';
+		case 'arrowup':
+			return 'volume-up';
+		case 'arrowdown':
+			return 'volume-down';
+		case 'm':
+			return 'toggle-mute';
+		case 'f':
+			return 'toggle-fullscreen';
+		case 'c':
+			return 'toggle-captions';
+		default:
+			return undefined;
+	}
+}
+
+/** One caption / subtitle track for a consumer-supplied video. */
+export interface MediaTrack {
+	readonly src: string;
+	/** Track kind; `captions` / `subtitles` satisfy WCAG 1.2.2. */
+	readonly kind: 'captions' | 'subtitles' | 'descriptions' | 'chapters' | 'metadata';
+	/** BCP 47 language tag, e.g. `"en"`. */
+	readonly srclang?: string;
+	/** Human label shown in the track menu, e.g. `"English"`. */
+	readonly label?: string;
+	/** Whether the browser shows this track by default. */
+	readonly default?: boolean;
+}
+
+/**
+ * Enforce the captions invariant for video (WCAG 2.2 SC 1.2.2): a video
+ * `<Player>` must receive a `tracks` prop, even if empty. Passing `tracks`
+ * (including `[]`) is the explicit opt-out a consumer makes when the source has
+ * no spoken audio. Audio-only players are exempt. Throws an RFC 9457
+ * `ProblemError` rather than rendering a caption-less video.
+ */
+export function assertCaptionsContract(
+	viewType: 'video' | 'audio',
+	tracks: readonly MediaTrack[] | undefined,
+): void {
+	if (viewType === 'audio') return;
+	if (tracks === undefined) {
+		throw new ProblemError({
+			status: 500,
+			title: 'Captions contract violated',
+			detail:
+				'A video <Player> requires a `tracks` prop (use `tracks={[]}` to opt out explicitly when the source has no spoken audio). WCAG 2.2 SC 1.2.2.',
+			type: 'https://sveltesentio.dev/problems/media/captions-required',
+		});
+	}
+}
+
+/** Pad a non-negative integer to two digits. */
+function pad2(n: number): string {
+	return n < 10 ? `0${n}` : String(n);
+}
+
+/**
+ * Format a media time (seconds) as `M:SS` or `H:MM:SS`. Non-finite or negative
+ * input clamps to `0:00`. Used for the visible time-code and the progress
+ * slider's `aria-valuetext`.
+ */
+export function formatMediaTime(seconds: number): string {
+	const total = Number.isFinite(seconds) && seconds > 0 ? Math.floor(seconds) : 0;
+	const hrs = Math.floor(total / 3600);
+	const mins = Math.floor((total % 3600) / 60);
+	const secs = total % 60;
+	if (hrs > 0) return `${hrs}:${pad2(mins)}:${pad2(secs)}`;
+	return `${mins}:${pad2(secs)}`;
+}
+
+/**
+ * Clamp a volume to the valid `[0, 1]` range, mapping non-finite input to `0`.
+ * Volume key steps add/subtract `step` (default `0.1`) before clamping.
+ */
+export function clampVolume(value: number, step = 0): number {
+	const v = Number.isFinite(value) ? value + step : 0;
+	if (v < 0) return 0;
+	if (v > 1) return 1;
+	return v;
+}