@sveltesentio/media 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [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.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",
   "type": "module",
   "private": false,
   "sideEffects": false,
@@ -9,20 +9,22 @@
     ".": {
       "import": "./src/index.ts",
       "types": "./src/index.ts"
+    },
+    "./player": {
+      "import": "./src/player.ts",
+      "types": "./src/player.ts"
+    },
+    "./image": {
+      "import": "./src/image.ts",
+      "types": "./src/image.ts"
     }
   },
   "peerDependencies": {
-    "vidstack": ">=0.6.0",
-    "hls.js": ">=1.6.0",
-    "embla-carousel-svelte": ">=8.0.0",
-    "svelte": ">=5.0.0"
+    "hls.js": ">=1.6.0"
   },
   "peerDependenciesMeta": {
     "hls.js": {
       "optional": true
-    },
-    "embla-carousel-svelte": {
-      "optional": true
     }
   },
   "devDependencies": {
@@ -32,9 +34,9 @@
   "keywords": [
     "sveltesentio",
     "media",
-    "vidstack",
     "hls",
-    "carousel",
+    "srcset",
+    "media-session",
     "10-foot-ui"
   ],
   "publishConfig": {
@@ -48,6 +50,6 @@
     "build": "tsc",
     "lint": "eslint src/",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run --passWithNoTests"
+    "test": "vitest run"
   }
 }

package/src/image.ts

@@ -0,0 +1,160 @@
+/**
+ * Pure responsive-image helpers: `srcset` / `sizes` string builders plus a
+ * width-descriptor candidate model. Framework-agnostic — no DOM, no Svelte —
+ * so the same logic drives a `<picture>`, an `<img srcset>`, or a server-side
+ * `Link: rel=preload` header.
+ */
+
+/** A `src`-templating function: maps a target pixel width to a URL. */
+export type SrcWidthTemplate = (width: number) => string;
+
+/** One `srcset` candidate: a URL paired with its intrinsic pixel width. */
+export interface SrcSetCandidate {
+	readonly url: string;
+	readonly width: number;
+}
+
+export interface SrcSetOptions {
+	/**
+	 * How to derive each candidate URL from a width. Either a template function
+	 * or a token-substitution string containing `{w}` (replaced with the width).
+	 * When omitted, `?w=<width>` is appended to `src` (or merged into an
+	 * existing query string).
+	 */
+	readonly template?: SrcWidthTemplate | string;
+}
+
+const WIDTH_TOKEN = /\{w\}/g;
+
+/** De-duplicate, drop non-positive/non-finite entries, and sort ascending. */
+function normaliseWidths(widths: readonly number[]): number[] {
+	const seen = new Set<number>();
+	for (const w of widths) {
+		if (Number.isFinite(w) && w > 0) seen.add(Math.round(w));
+	}
+	return [...seen].sort((a, b) => a - b);
+}
+
+/** Append/merge a `w` query param onto a URL without a URL parser dependency. */
+function appendWidthQuery(src: string, width: number): string {
+	const [base, hash = ''] = src.split('#', 2);
+	const safeBase = base ?? src;
+	const sep = safeBase.includes('?') ? '&' : '?';
+	const suffix = hash ? `#${hash}` : '';
+	return `${safeBase}${sep}w=${width}${suffix}`;
+}
+
+function resolveTemplate(
+	src: string,
+	template: SrcWidthTemplate | string | undefined,
+): SrcWidthTemplate {
+	if (typeof template === 'function') return template;
+	if (typeof template === 'string') {
+		return (width) => template.replace(WIDTH_TOKEN, String(width));
+	}
+	return (width) => appendWidthQuery(src, width);
+}
+
+/**
+ * Build the structured candidate list backing a `srcset`. Widths are
+ * normalised (de-duped, positive, integer, ascending) so callers can pass a
+ * raw breakpoint list in any order.
+ */
+export function buildSrcSetCandidates(
+	src: string,
+	widths: readonly number[],
+	options: SrcSetOptions = {},
+): SrcSetCandidate[] {
+	const resolved = resolveTemplate(src, options.template);
+	return normaliseWidths(widths).map((width) => ({
+		url: resolved(width),
+		width,
+	}));
+}
+
+/**
+ * Build a `srcset` attribute string with `w` width descriptors, e.g.
+ * `"/img?w=320 320w, /img?w=640 640w"`. Returns `""` for an empty width list.
+ */
+export function buildSrcSet(
+	src: string,
+	widths: readonly number[],
+	options: SrcSetOptions = {},
+): string {
+	return buildSrcSetCandidates(src, widths, options)
+		.map((c) => `${c.url} ${c.width}w`)
+		.join(', ');
+}
+
+/** One `sizes` media-condition / length pair. */
+export interface SizesRule {
+	/** A media condition, e.g. `"(min-width: 768px)"`. */
+	readonly condition: string;
+	/** A CSS length, e.g. `"50vw"` or `"600px"`. */
+	readonly size: string;
+}
+
+export interface BuildSizesOptions {
+	/**
+	 * The trailing default length applied when no condition matches. Defaults to
+	 * `"100vw"` — the responsive-image-correct fallback for a fluid layout.
+	 */
+	readonly fallback?: string;
+}
+
+/**
+ * Build a `sizes` attribute string from ordered conditional rules plus a
+ * fallback length, e.g. `"(min-width: 768px) 50vw, 100vw"`. Rules are emitted
+ * in array order — the browser uses the first matching condition.
+ */
+export function buildSizes(
+	rules: readonly SizesRule[],
+	options: BuildSizesOptions = {},
+): string {
+	const fallback = options.fallback ?? '100vw';
+	const conditional = rules.map((r) => `${r.condition} ${r.size}`);
+	return [...conditional, fallback].join(', ');
+}
+
+export interface ResponsiveImageAttrs {
+	readonly src: string;
+	readonly srcset: string;
+	readonly sizes: string;
+}
+
+export interface BuildResponsiveImageOptions extends SrcSetOptions {
+	readonly sizes?: readonly SizesRule[];
+	readonly sizesFallback?: string;
+	/**
+	 * Which width to use for the legacy `src` fallback attribute. Defaults to
+	 * the largest provided width so non-`srcset` browsers get full quality.
+	 */
+	readonly fallbackWidth?: number;
+}
+
+/**
+ * Compose `{ src, srcset, sizes }` ready to spread onto an `<img>`. The `src`
+ * fallback targets `fallbackWidth` (default: largest width) so legacy browsers
+ * without `srcset` support still receive a sensibly-sized asset.
+ */
+export function buildResponsiveImage(
+	src: string,
+	widths: readonly number[],
+	options: BuildResponsiveImageOptions = {},
+): ResponsiveImageAttrs {
+	const candidates = buildSrcSetCandidates(src, widths, options);
+	const fallbackWidth =
+		options.fallbackWidth ?? candidates.at(-1)?.width;
+	const resolved = resolveTemplate(src, options.template);
+	const fallbackSrc =
+		fallbackWidth === undefined ? src : resolved(fallbackWidth);
+	return {
+		src: fallbackSrc,
+		srcset: candidates.map((c) => `${c.url} ${c.width}w`).join(', '),
+		sizes: buildSizes(options.sizes ?? [], {
+			...(options.sizesFallback === undefined
+				? {}
+				: { fallback: options.sizesFallback }),
+		}),
+	};
+}

package/src/index.ts

@@ -1,2 +1,37 @@
-// @sveltesentio/media — not yet implemented (see .workingdir/PLAN.md)
-export {};
+export type {
+	HlsRendition,
+	PickRenditionOptions,
+	MediaSessionArtwork,
+	MediaSessionMetadataInit,
+	MediaSessionMetadata,
+	PlaybackStatus,
+	PlaybackEvent,
+	PlaybackState,
+	HlsLike,
+	HlsConstructorLike,
+	HlsAttachmentOptions,
+	HlsAttachment,
+} from './player.js';
+export {
+	pickRendition,
+	buildMediaSessionMetadata,
+	initialPlaybackState,
+	playbackReducer,
+	createHlsAttachment,
+} from './player.js';
+
+export type {
+	SrcWidthTemplate,
+	SrcSetCandidate,
+	SrcSetOptions,
+	SizesRule,
+	BuildSizesOptions,
+	ResponsiveImageAttrs,
+	BuildResponsiveImageOptions,
+} from './image.js';
+export {
+	buildSrcSet,
+	buildSrcSetCandidates,
+	buildSizes,
+	buildResponsiveImage,
+} from './image.js';

package/src/player.ts

@@ -0,0 +1,255 @@
+/**
+ * Headless player-source model: rendition selection, OS media-session
+ * metadata, a typed play/pause/quality state machine, and a bring-your-own
+ * `hls.js` attachment seam. Pure and framework-agnostic — the heavy
+ * `<Player>` UI shell (vidstack) is a follow-through and intentionally absent
+ * here so this package stays free of runtime media dependencies.
+ *
+ * @see ADR-0042 (Vidstack `@next` + `hls.js`) — issues #67 / #68.
+ */
+
+/**
+ * One HLS variant. Models separate-rendition (un-muxed) streaming as used by
+ * media servers: a rendition may carry video, audio, or both, so quality and
+ * audio-track switching are independent concerns.
+ */
+export interface HlsRendition {
+	/** Stable identifier (e.g. the HLS level index or a server stream id). */
+	readonly id: string;
+	/** Vertical resolution in pixels; omit for audio-only renditions. */
+	readonly height?: number;
+	/** Average/peak bitrate in bits per second, if known. */
+	readonly bitrate?: number;
+	/** RFC 6381 codec string, e.g. `"hvc1.1.6.L93.B0"` or `"avc1.640028"`. */
+	readonly codec?: string;
+	/** BCP 47 language tag for audio renditions, e.g. `"en"`. */
+	readonly language?: string;
+	/** Whether this is the server-default rendition. */
+	readonly default?: boolean;
+}
+
+export interface PickRenditionOptions {
+	/** Cap selection to renditions at or below this height. */
+	readonly maxHeight?: number;
+	/**
+	 * Prefer renditions whose `codec` starts with this prefix (case-insensitive),
+	 * e.g. `"hvc1"` / `"hev1"` for HEVC, `"avc1"` for H.264. Non-matching
+	 * renditions remain eligible as a fallback.
+	 */
+	readonly preferCodec?: string;
+}
+
+function isAtOrBelowHeight(r: HlsRendition, maxHeight: number | undefined): boolean {
+	if (maxHeight === undefined) return true;
+	if (r.height === undefined) return true; // audio-only is never excluded by height
+	return r.height <= maxHeight;
+}
+
+function rank(r: HlsRendition): number {
+	if (r.height !== undefined) return r.height * 1_000_000 + (r.bitrate ?? 0);
+	return r.bitrate ?? 0;
+}
+
+/**
+ * Select the best HLS rendition under the given constraints. Picks the highest
+ * eligible height (then bitrate). When `preferCodec` is set, codec-matching
+ * renditions win over non-matching ones of equal-or-greater rank, so a HEVC
+ * preference is honoured without discarding an H.264 fallback. Returns
+ * `undefined` only when `renditions` is empty.
+ */
+export function pickRendition(
+	renditions: readonly HlsRendition[],
+	options: PickRenditionOptions = {},
+): HlsRendition | undefined {
+	const { maxHeight, preferCodec } = options;
+	const eligible = renditions.filter((r) => isAtOrBelowHeight(r, maxHeight));
+	const pool = eligible.length > 0 ? eligible : renditions;
+	if (pool.length === 0) return undefined;
+
+	const prefix = preferCodec?.toLowerCase();
+	const matches = (r: HlsRendition): boolean =>
+		prefix !== undefined && (r.codec?.toLowerCase().startsWith(prefix) ?? false);
+
+	let best: HlsRendition | undefined;
+	for (const r of pool) {
+		if (best === undefined) {
+			best = r;
+			continue;
+		}
+		const rMatch = matches(r);
+		const bestMatch = matches(best);
+		if (rMatch !== bestMatch) {
+			if (rMatch) best = r;
+			continue;
+		}
+		if (rank(r) > rank(best)) best = r;
+	}
+	return best;
+}
+
+/** One album-art / poster image for the OS media session. */
+export interface MediaSessionArtwork {
+	readonly src: string;
+	/** e.g. `"512x512"`. */
+	readonly sizes?: string;
+	/** e.g. `"image/png"`. */
+	readonly type?: string;
+}
+
+export interface MediaSessionMetadataInit {
+	readonly title: string;
+	readonly artist?: string;
+	readonly album?: string;
+	readonly artwork?: readonly MediaSessionArtwork[];
+}
+
+/**
+ * Shape compatible with the `MediaMetadataInit` accepted by the browser
+ * `navigator.mediaSession.metadata = new MediaMetadata(...)` API. Returned as a
+ * plain object so the caller — not this package — owns the DOM boundary.
+ */
+export interface MediaSessionMetadata {
+	readonly title: string;
+	readonly artist: string;
+	readonly album: string;
+	readonly artwork: readonly MediaSessionArtwork[];
+}
+
+/**
+ * Build a normalised media-session metadata object for the OS lock-screen /
+ * media keys. Empty `artist` / `album` default to `""` (the API's own
+ * defaults) so the result can be passed straight to `new MediaMetadata(...)`.
+ */
+export function buildMediaSessionMetadata(
+	init: MediaSessionMetadataInit,
+): MediaSessionMetadata {
+	return {
+		title: init.title,
+		artist: init.artist ?? '',
+		album: init.album ?? '',
+		artwork: init.artwork ?? [],
+	};
+}
+
+/** Playback lifecycle states for the headless machine. */
+export type PlaybackStatus = 'idle' | 'loading' | 'playing' | 'paused' | 'ended';
+
+/** Events the state machine accepts. */
+export type PlaybackEvent =
+	| { readonly type: 'load' }
+	| { readonly type: 'ready' }
+	| { readonly type: 'play' }
+	| { readonly type: 'pause' }
+	| { readonly type: 'end' }
+	| { readonly type: 'selectQuality'; readonly renditionId: string }
+	| { readonly type: 'reset' };
+
+export interface PlaybackState {
+	readonly status: PlaybackStatus;
+	/** Currently-selected rendition id, or `null` for automatic (ABR). */
+	readonly renditionId: string | null;
+}
+
+export const initialPlaybackState: PlaybackState = {
+	status: 'idle',
+	renditionId: null,
+};
+
+/**
+ * Pure reducer for the play/pause/quality machine. Invalid transitions (e.g.
+ * `play` while `idle`) are no-ops that return the input state unchanged, so the
+ * machine never throws on a stray event. Quality selection is orthogonal to the
+ * play/pause lifecycle and is accepted in any non-terminal state.
+ */
+export function playbackReducer(
+	state: PlaybackState,
+	event: PlaybackEvent,
+): PlaybackState {
+	switch (event.type) {
+		case 'load':
+			return state.status === 'idle'
+				? { ...state, status: 'loading' }
+				: state;
+		case 'ready':
+			return state.status === 'loading'
+				? { ...state, status: 'paused' }
+				: state;
+		case 'play':
+			return state.status === 'paused' || state.status === 'ended'
+				? { ...state, status: 'playing' }
+				: state;
+		case 'pause':
+			return state.status === 'playing'
+				? { ...state, status: 'paused' }
+				: state;
+		case 'end':
+			return state.status === 'playing'
+				? { ...state, status: 'ended' }
+				: state;
+		case 'selectQuality':
+			return state.status === 'idle'
+				? state
+				: { ...state, renditionId: event.renditionId };
+		case 'reset':
+			return initialPlaybackState;
+	}
+}
+
+/**
+ * Minimal structural view of an `hls.js` instance — only the members the
+ * attachment seam touches. Kept local so this package needs no `hls.js`
+ * dependency (it is an optional peer).
+ */
+export interface HlsLike {
+	loadSource(url: string): void;
+	attachMedia(media: HTMLMediaElement): void;
+	destroy(): void;
+	/** Manual quality override; `-1` restores automatic ABR. */
+	currentLevel?: number;
+}
+
+/** A constructor compatible with `new Hls(config)`. */
+export type HlsConstructorLike = new (config?: unknown) => HlsLike;
+
+export interface HlsAttachmentOptions {
+	/** Optional `hls.js` config passed straight to its constructor. */
+	readonly config?: unknown;
+}
+
+export interface HlsAttachment {
+	/** Wire an HLS source to a media element; returns a detach/destroy handle. */
+	attach(media: HTMLMediaElement, source: string): { destroy(): void };
+}
+
+/**
+ * Bring-your-own-`hls.js` seam. The caller injects the `hls.js` constructor
+ * (so this package neither bundles nor dynamically imports it), and gets back a
+ * tiny attachment helper that wires a source to a media element. Downstreams
+ * already on raw `hls.js` can adopt this without pulling any UI shell.
+ *
+ * @example
+ * import Hls from 'hls.js';
+ * const hls = createHlsAttachment(Hls);
+ * const handle = hls.attach(videoEl, manifestUrl);
+ * // later: handle.destroy();
+ */
+export function createHlsAttachment(
+	HlsCtor: HlsConstructorLike,
+	options: HlsAttachmentOptions = {},
+): HlsAttachment {
+	return {
+		attach(media, source) {
+			const instance =
+				options.config === undefined
+					? new HlsCtor()
+					: new HlsCtor(options.config);
+			instance.attachMedia(media);
+			instance.loadSource(source);
+			return {
+				destroy: () => {
+					instance.destroy();
+				},
+			};
+		},
+	};
+}