@classic-homes/theme-svelte 1.2.3 → 1.3.0

package/dist/lib/utils/media.js

@@ -0,0 +1,715 @@
+/**
+ * Media utilities
+ *
+ * Pure helpers shared by the media components. Nothing here touches the DOM or
+ * component state, so it is all directly unit-testable.
+ */
+/** Numeric width/height ratios for the named aspect ratios. */
+export const ASPECT_RATIOS = {
+    square: 1,
+    video: 16 / 9,
+    photo: 4 / 3,
+    portrait: 3 / 4,
+    wide: 21 / 9,
+};
+/**
+ * Resolve a ratio prop to a numeric width/height ratio.
+ *
+ * @example
+ * resolveAspectRatio('video') // 1.777…
+ * resolveAspectRatio(2.35)    // 2.35
+ */
+export function resolveAspectRatio(ratio) {
+    return typeof ratio === 'number' ? ratio : ASPECT_RATIOS[ratio];
+}
+/**
+ * Format a duration in seconds as `m:ss`, or `h:mm:ss` past an hour.
+ *
+ * Non-finite and negative inputs collapse to `0:00` so a player showing
+ * `NaN` before metadata loads is impossible.
+ *
+ * @example
+ * formatDuration(83)   // '1:23'
+ * formatDuration(3723) // '1:02:03'
+ * formatDuration(NaN)  // '0:00'
+ */
+export function formatDuration(seconds) {
+    if (!Number.isFinite(seconds) || seconds < 0)
+        return '0:00';
+    const total = Math.floor(seconds);
+    const hours = Math.floor(total / 3600);
+    const minutes = Math.floor((total % 3600) / 60);
+    const secs = total % 60;
+    const paddedSecs = String(secs).padStart(2, '0');
+    if (hours > 0) {
+        return `${hours}:${String(minutes).padStart(2, '0')}:${paddedSecs}`;
+    }
+    return `${minutes}:${paddedSecs}`;
+}
+/**
+ * Spoken form of a duration, for `aria-label` and `aria-valuetext`.
+ *
+ * Screen readers announce `1:23` as "one twenty-three", which is ambiguous.
+ *
+ * @example
+ * formatDurationSpoken(83) // '1 minute 23 seconds'
+ */
+export function formatDurationSpoken(seconds) {
+    if (!Number.isFinite(seconds) || seconds < 0)
+        return '0 seconds';
+    const total = Math.floor(seconds);
+    const hours = Math.floor(total / 3600);
+    const minutes = Math.floor((total % 3600) / 60);
+    const secs = total % 60;
+    const parts = [];
+    if (hours > 0)
+        parts.push(`${hours} hour${hours === 1 ? '' : 's'}`);
+    if (minutes > 0)
+        parts.push(`${minutes} minute${minutes === 1 ? '' : 's'}`);
+    if (secs > 0 || parts.length === 0)
+        parts.push(`${secs} second${secs === 1 ? '' : 's'}`);
+    return parts.join(' ');
+}
+const IMAGE_EXTENSIONS = ['jpg', 'jpeg', 'png', 'gif', 'webp', 'avif', 'svg', 'bmp', 'ico'];
+const VIDEO_EXTENSIONS = ['mp4', 'webm', 'ogv', 'mov', 'm4v', 'mkv'];
+const AUDIO_EXTENSIONS = ['mp3', 'wav', 'ogg', 'oga', 'm4a', 'aac', 'flac', 'opus'];
+/**
+ * Extract the lower-cased file extension from a URL, ignoring query strings
+ * and hash fragments.
+ */
+export function getFileExtension(url) {
+    const withoutQuery = url.split(/[?#]/)[0];
+    const lastSegment = withoutQuery.split('/').pop() ?? '';
+    const dotIndex = lastSegment.lastIndexOf('.');
+    if (dotIndex === -1 || dotIndex === lastSegment.length - 1)
+        return '';
+    return lastSegment.slice(dotIndex + 1).toLowerCase();
+}
+/**
+ * Infer a media kind from a URL or MIME type.
+ *
+ * MIME type wins when supplied, since a URL may have no extension at all.
+ * Returns `null` when nothing can be inferred, so callers can decide whether
+ * to fall back or warn.
+ *
+ * @example
+ * inferMediaKind('/clip.mp4')                  // 'video'
+ * inferMediaKind('/asset', 'image/png')        // 'image'
+ * inferMediaKind('https://youtu.be/dQw4w9Wg')  // 'embed'
+ */
+export function inferMediaKind(url, mimeType) {
+    if (mimeType) {
+        if (mimeType.startsWith('image/'))
+            return 'image';
+        if (mimeType.startsWith('video/'))
+            return 'video';
+        if (mimeType.startsWith('audio/'))
+            return 'audio';
+    }
+    if (parseEmbedUrl(url))
+        return 'embed';
+    const extension = getFileExtension(url);
+    if (IMAGE_EXTENSIONS.includes(extension))
+        return 'image';
+    if (VIDEO_EXTENSIONS.includes(extension))
+        return 'video';
+    if (AUDIO_EXTENSIONS.includes(extension))
+        return 'audio';
+    return null;
+}
+/** MIME type browsers use for HLS playlists. */
+export const HLS_MIME_TYPE = 'application/vnd.apple.mpegurl';
+/** MIME type browsers use for MPEG-DASH manifests. */
+export const DASH_MIME_TYPE = 'application/dash+xml';
+/**
+ * Whether a source is an HLS playlist.
+ *
+ * Checks the declared MIME type first, then the `.m3u8` extension, so a
+ * manifest served from an extensionless or query-laden URL still resolves
+ * correctly as long as its type is declared.
+ */
+export function isHlsSource(source) {
+    const src = typeof source === 'string' ? source : source.src;
+    const type = typeof source === 'string' ? undefined : source.type;
+    if (type)
+        return type.toLowerCase() === HLS_MIME_TYPE || type.toLowerCase() === 'application/x-mpegurl';
+    const extension = getFileExtension(src);
+    return extension === 'm3u8';
+}
+/** Normalize a `src` prop to the list of sources a `<video>`/`<audio>` should render. */
+export function toMediaSources(src) {
+    if (Array.isArray(src))
+        return src;
+    const extension = getFileExtension(src);
+    const type = extension ? guessMimeType(extension) : undefined;
+    return [{ src, type }];
+}
+/** Best-effort MIME type for a media file extension. */
+export function guessMimeType(extension) {
+    const map = {
+        m3u8: HLS_MIME_TYPE,
+        mpd: DASH_MIME_TYPE,
+        mp4: 'video/mp4',
+        m4v: 'video/mp4',
+        webm: 'video/webm',
+        ogv: 'video/ogg',
+        mov: 'video/quicktime',
+        mp3: 'audio/mpeg',
+        wav: 'audio/wav',
+        ogg: 'audio/ogg',
+        oga: 'audio/ogg',
+        m4a: 'audio/mp4',
+        aac: 'audio/aac',
+        flac: 'audio/flac',
+        opus: 'audio/opus',
+    };
+    return map[extension.toLowerCase()];
+}
+/**
+ * Cloudflare Stream
+ *
+ * Stream serves every asset for a video from one host, keyed by the video UID.
+ * A signed playback token substitutes for the UID in exactly the same
+ * position, so private videos need no separate code path — pass the token as
+ * `videoId`.
+ *
+ * @see https://developers.cloudflare.com/stream/viewing-videos/using-own-player/
+ */
+/** Resolve the host serving a Stream account's assets. */
+export function cloudflareStreamHost(account) {
+    if (account.domain)
+        return account.domain.replace(/^https?:\/\//, '').replace(/\/$/, '');
+    if (account.customerCode)
+        return `customer-${account.customerCode}.cloudflarestream.com`;
+    return null;
+}
+/**
+ * Thumbnail URL for a Cloudflare Stream video.
+ *
+ * Unlike Vimeo, Stream generates thumbnails on demand from a predictable URL,
+ * so a poster never needs a network lookup to discover.
+ *
+ * @example
+ * cloudflareStreamThumbnail('a1b2c3', { customerCode: 'abc', time: '1s', height: 600 })
+ * // 'https://customer-abc.cloudflarestream.com/a1b2c3/thumbnails/thumbnail.jpg?time=1s&height=600'
+ */
+export function cloudflareStreamThumbnail(videoId, options) {
+    const host = cloudflareStreamHost(options);
+    if (!host || !videoId)
+        return null;
+    const params = new URLSearchParams();
+    if (options.time)
+        params.set('time', options.time);
+    if (options.height !== undefined)
+        params.set('height', String(options.height));
+    if (options.width !== undefined)
+        params.set('width', String(options.width));
+    if (options.fit)
+        params.set('fit', options.fit);
+    if (options.animated) {
+        if (options.duration)
+            params.set('duration', options.duration);
+        if (options.fps !== undefined)
+            params.set('fps', String(options.fps));
+    }
+    const file = options.animated ? 'thumbnail.gif' : 'thumbnail.jpg';
+    const query = params.toString();
+    return `https://${host}/${videoId}/thumbnails/${file}${query ? `?${query}` : ''}`;
+}
+/**
+ * Build the playback URLs for a Cloudflare Stream video.
+ *
+ * Returns `null` when the account cannot be resolved, so a missing customer
+ * code surfaces as a clear failure rather than a malformed request.
+ *
+ * @example
+ * cloudflareStreamUrls('a1b2c3', { customerCode: 'abc' })?.hls
+ * // 'https://customer-abc.cloudflarestream.com/a1b2c3/manifest/video.m3u8'
+ */
+export function cloudflareStreamUrls(videoId, options) {
+    const host = cloudflareStreamHost(options);
+    if (!host || !videoId)
+        return null;
+    const params = new URLSearchParams();
+    if (options.lowLatency)
+        params.set('protocol', 'llhls');
+    if (options.clientBandwidthHint !== undefined) {
+        params.set('clientBandwidthHint', String(options.clientBandwidthHint));
+    }
+    const query = params.toString();
+    const base = `https://${host}/${videoId}`;
+    return {
+        hls: `${base}/manifest/video.m3u8${query ? `?${query}` : ''}`,
+        dash: `${base}/manifest/video.mpd${query ? `?${query}` : ''}`,
+        iframe: `${base}/iframe`,
+        thumbnail: `${base}/thumbnails/thumbnail.jpg`,
+        download: `${base}/downloads/default.mp4`,
+    };
+}
+/**
+ * Build a media item for a Cloudflare Stream video, playable by `Video`,
+ * `MediaGrid`, `MediaCarousel`, and `Lightbox`.
+ *
+ * The item's source is the HLS playlist, so playback uses the design system's
+ * own controls rather than Cloudflare's player. Use `MediaEmbed` with
+ * `provider="cloudflare"` when you want Cloudflare's player instead.
+ *
+ * Throws when the account cannot be resolved, because every URL on the
+ * returned item would otherwise be malformed.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { Video, cloudflareStream } from '@classic-homes/theme-svelte';
+ *
+ *   const tour = cloudflareStream('a1b2c3', {
+ *     customerCode: 'abc123',
+ *     title: 'Product tour',
+ *   });
+ * </script>
+ *
+ * <Video item={tour} />
+ * ```
+ */
+export function cloudflareStream(videoId, options) {
+    const urls = cloudflareStreamUrls(videoId, options);
+    if (!urls) {
+        throw new Error('cloudflareStream: could not resolve the Stream host. Pass "customerCode" (from the Stream dashboard) or "domain".');
+    }
+    const poster = options.poster ??
+        cloudflareStreamThumbnail(videoId, {
+            customerCode: options.customerCode,
+            domain: options.domain,
+            time: options.posterTime ?? '1s',
+            height: options.posterHeight ?? 720,
+        }) ??
+        undefined;
+    return {
+        kind: 'video',
+        id: options.id ?? videoId,
+        src: [{ src: urls.hls, type: HLS_MIME_TYPE }],
+        poster,
+        thumbnail: poster,
+        title: options.title,
+        caption: options.caption,
+        duration: options.duration,
+        tracks: options.tracks,
+        downloadUrl: options.downloadable ? urls.download : undefined,
+    };
+}
+/**
+ * Matterport
+ *
+ * Matterport embeds an interactive 3D space, not a video, so it has no
+ * timeline, no duration, and no derivable thumbnail. The showcase player is
+ * driven entirely by query parameters on one URL.
+ *
+ * @see https://support.matterport.com/s/article/URL-Parameters
+ */
+/** Hosts that serve the Matterport showcase player. */
+const MATTERPORT_HOSTS = ['my.matterport.com', 'matterport.com'];
+/**
+ * Build the showcase URL for a Matterport space.
+ *
+ * Matterport's own defaults are left alone unless an option asks otherwise,
+ * so the embed looks the way the space's owner configured it.
+ *
+ * @example
+ * buildMatterportSrc('SxQL3iGyoDo', { brand: false })
+ * // 'https://my.matterport.com/show/?m=SxQL3iGyoDo&qs=1&brand=0'
+ */
+export function buildMatterportSrc(modelId, options = {}) {
+    const params = new URLSearchParams({ m: modelId });
+    // Quick start is on by default: without it the space shows a black frame
+    // for several seconds before the first view resolves.
+    if (options.quickStart !== false)
+        params.set('qs', '1');
+    if (options.autoplay)
+        params.set('play', '1');
+    if (options.brand === false)
+        params.set('brand', '0');
+    if (options.help === false)
+        params.set('help', '0');
+    if (options.highlightReel === false)
+        params.set('hr', '0');
+    if (options.vr === false)
+        params.set('vr', '0');
+    if (options.floorSelector === false)
+        params.set('f', '0');
+    if (options.mls)
+        params.set('mls', '1');
+    if (options.lang)
+        params.set('lang', options.lang);
+    if (options.guidedTourStart !== undefined) {
+        params.set('ts', String(Math.max(0, Math.floor(options.guidedTourStart))));
+    }
+    // Escape hatch for the long tail of showcase parameters.
+    for (const [key, value] of Object.entries(options.params ?? {})) {
+        params.set(key, typeof value === 'boolean' ? (value ? '1' : '0') : String(value));
+    }
+    return `https://my.matterport.com/show/?${params.toString()}`;
+}
+/**
+ * Choose a usable preview image from a space's metadata.
+ *
+ * The payload's top-level `image` is deliberately ignored: Matterport hands it
+ * out already expired, and requesting it answers 410. The signatures inside
+ * `images` are freshly minted, so those are the only ones worth using — the
+ * hero shot first, and its thumbnail variant ahead of the full-size original,
+ * which is tens of times larger for no benefit at facade size.
+ */
+function pickMatterportImage(images) {
+    const ordered = [...images].sort((a, b) => Number(Boolean(b.is_hero)) - Number(Boolean(a.is_hero)));
+    for (const image of ordered) {
+        const url = image.thumbnail_signed_src ?? image.signed_src;
+        if (url)
+            return url;
+    }
+    return null;
+}
+/**
+ * Look up a Matterport space's name and preview image.
+ *
+ * Matterport publishes no oEmbed endpoint and no derivable thumbnail URL, so
+ * a real preview needs this request. It is never made automatically — the
+ * caller opts in — because contacting the provider before the viewer clicks is
+ * exactly what the lazy facade exists to avoid.
+ *
+ * The returned image URL is signed and short-lived, so it must be used
+ * promptly rather than stored.
+ *
+ * Resolves to `null` on any failure rather than throwing, so a preview is
+ * always an enhancement and never breaks a render.
+ */
+export async function fetchMatterportMetadata(modelId, options = {}) {
+    if (!modelId)
+        return null;
+    try {
+        const response = await fetch(`https://my.matterport.com/api/v1/player/models/${encodeURIComponent(modelId)}/`, { signal: options.signal });
+        if (!response.ok)
+            return null;
+        const data = (await response.json());
+        return { name: data.name ?? '', image: pickMatterportImage(data.images ?? []) };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Build a media item for a Matterport space, usable by `MediaEmbed`,
+ * `MediaGrid`, `MediaCarousel`, and `Lightbox`.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { MediaGrid, matterportTour } from '@classic-homes/theme-svelte';
+ *
+ *   const items = [matterportTour('SxQL3iGyoDo', { title: 'Show home' })];
+ * </script>
+ *
+ * <MediaGrid {items} />
+ * ```
+ */
+export function matterportTour(modelId, options = {}) {
+    return {
+        kind: 'embed',
+        provider: 'matterport',
+        id: options.id ?? modelId,
+        videoId: modelId,
+        title: options.title,
+        caption: options.caption,
+        poster: options.poster,
+        thumbnail: options.poster,
+        matterport: {
+            autoplay: options.autoplay,
+            quickStart: options.quickStart,
+            brand: options.brand,
+            help: options.help,
+            highlightReel: options.highlightReel,
+            vr: options.vr,
+            floorSelector: options.floorSelector,
+            guidedTourStart: options.guidedTourStart,
+            mls: options.mls,
+            lang: options.lang,
+            params: options.params,
+        },
+    };
+}
+const YOUTUBE_ID = /^[\w-]{11}$/;
+const VIMEO_ID = /^\d+$/;
+/**
+ * Parse a YouTube, Vimeo, or Cloudflare Stream URL into a provider and video id.
+ *
+ * Handles `youtube.com/watch?v=`, `youtu.be/`, `/embed/`, `/shorts/`, and
+ * `/live/` for YouTube; `vimeo.com/<id>` (including unlisted-hash and
+ * `player.vimeo.com/video/<id>` forms) for Vimeo; and every
+ * `customer-<CODE>.cloudflarestream.com/<UID>/…` form plus the legacy
+ * `videodelivery.net` hosts for Stream. Returns `null` for anything else
+ * rather than guessing.
+ *
+ * @example
+ * parseEmbedUrl('https://youtu.be/dQw4w9WgXcQ?t=30')
+ * // { provider: 'youtube', videoId: 'dQw4w9WgXcQ', start: 30 }
+ *
+ * @example
+ * parseEmbedUrl('https://customer-abc.cloudflarestream.com/a1b2c3/iframe')
+ * // { provider: 'cloudflare', videoId: 'a1b2c3', customerCode: 'abc' }
+ */
+export function parseEmbedUrl(url) {
+    if (!url)
+        return null;
+    let parsed;
+    try {
+        parsed = new URL(url, 'https://placeholder.invalid');
+    }
+    catch {
+        return null;
+    }
+    const host = parsed.hostname.replace(/^www\./, '');
+    const segments = parsed.pathname.split('/').filter(Boolean);
+    const start = parseStartParam(parsed.searchParams.get('t') ?? parsed.searchParams.get('start'));
+    const cloudflare = parseCloudflareStreamHost(host, segments, parsed);
+    if (cloudflare)
+        return withStart(cloudflare, start);
+    if (MATTERPORT_HOSTS.includes(host)) {
+        // The showcase always carries the space in `?m=`; `/show/` is just the
+        // player route. Anything else on the domain is a marketing page.
+        const modelId = parsed.searchParams.get('m');
+        return modelId ? { provider: 'matterport', videoId: modelId } : null;
+    }
+    if (host === 'youtu.be') {
+        const videoId = segments[0];
+        return videoId && YOUTUBE_ID.test(videoId)
+            ? withStart({ provider: 'youtube', videoId }, start)
+            : null;
+    }
+    if (host === 'youtube.com' || host === 'youtube-nocookie.com' || host === 'm.youtube.com') {
+        const fromQuery = parsed.searchParams.get('v');
+        if (fromQuery && YOUTUBE_ID.test(fromQuery)) {
+            return withStart({ provider: 'youtube', videoId: fromQuery }, start);
+        }
+        // /embed/<id>, /shorts/<id>, /live/<id>, /v/<id>
+        if (['embed', 'shorts', 'live', 'v'].includes(segments[0])) {
+            const videoId = segments[1];
+            return videoId && YOUTUBE_ID.test(videoId)
+                ? withStart({ provider: 'youtube', videoId }, start)
+                : null;
+        }
+        return null;
+    }
+    if (host === 'vimeo.com' || host === 'player.vimeo.com') {
+        // player.vimeo.com/video/<id>, vimeo.com/<id>, vimeo.com/channels/x/<id>
+        const videoId = [...segments].reverse().find((segment) => VIMEO_ID.test(segment));
+        return videoId ? withStart({ provider: 'vimeo', videoId }, start) : null;
+    }
+    return null;
+}
+function withStart(embed, start) {
+    return start === undefined ? embed : { ...embed, start };
+}
+/**
+ * Recognise a Cloudflare Stream URL.
+ *
+ * Stream puts the video UID — or a signed playback token, which can be
+ * hundreds of characters — directly after the host, followed by the asset
+ * being requested (`iframe`, `watch`, `manifest/…`, `thumbnails/…`). The id is
+ * therefore whatever the first path segment is, with no shape to validate
+ * against.
+ */
+function parseCloudflareStreamHost(host, segments, parsed) {
+    const customerMatch = host.match(/^customer-([^.]+)\.cloudflarestream\.com$/);
+    const isLegacy = host === 'videodelivery.net' || host === 'iframe.videodelivery.net';
+    if (!customerMatch && !isLegacy)
+        return null;
+    const videoId = segments[0];
+    if (!videoId)
+        return null;
+    // Stream's own player uses `startTime` rather than YouTube's `t`.
+    const startTime = parseStartParam(parsed.searchParams.get('startTime'));
+    const embed = { provider: 'cloudflare', videoId };
+    if (customerMatch)
+        embed.customerCode = customerMatch[1];
+    if (startTime !== undefined)
+        embed.start = startTime;
+    return embed;
+}
+/** Parse YouTube's `t` parameter, which accepts both `90` and `1m30s`. */
+function parseStartParam(raw) {
+    if (!raw)
+        return undefined;
+    if (/^\d+$/.test(raw))
+        return Number(raw);
+    const match = raw.match(/^(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?$/);
+    if (!match || !match.slice(1).some(Boolean))
+        return undefined;
+    const [, hours, minutes, seconds] = match;
+    return Number(hours ?? 0) * 3600 + Number(minutes ?? 0) * 60 + Number(seconds ?? 0);
+}
+/**
+ * Build the iframe `src` for an embedded video.
+ *
+ * YouTube defaults to the `youtube-nocookie.com` domain, which does not set
+ * tracking cookies until playback begins. Cloudflare Stream needs the account
+ * to be resolvable, so pass `customerCode` or `domain` for that provider.
+ *
+ * @example
+ * buildEmbedSrc('youtube', 'dQw4w9WgXcQ', { autoplay: true, start: 30 })
+ * // 'https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ?autoplay=1&start=30&rel=0'
+ *
+ * @example
+ * buildEmbedSrc('cloudflare', 'a1b2c3', { customerCode: 'abc' })
+ * // 'https://customer-abc.cloudflarestream.com/a1b2c3/iframe'
+ */
+export function buildEmbedSrc(provider, videoId, options = {}) {
+    const { privacy = true, autoplay = false, start, showRelated = false } = options;
+    const params = new URLSearchParams();
+    if (provider === 'matterport') {
+        return buildMatterportSrc(videoId, { ...options.matterport, autoplay });
+    }
+    if (provider === 'cloudflare') {
+        const host = cloudflareStreamHost(options);
+        if (!host) {
+            throw new Error('buildEmbedSrc: Cloudflare Stream needs "customerCode" (from the Stream dashboard) or "domain".');
+        }
+        if (autoplay) {
+            params.set('autoplay', 'true');
+            // Browsers only permit autoplay without a gesture while muted, and
+            // Stream's player follows the same rule.
+            params.set('muted', 'true');
+        }
+        if (options.muted && !autoplay)
+            params.set('muted', 'true');
+        if (options.loop)
+            params.set('loop', 'true');
+        if (options.controls === false)
+            params.set('controls', 'false');
+        if (options.preload)
+            params.set('preload', options.preload);
+        if (options.poster)
+            params.set('poster', options.poster);
+        if (start !== undefined)
+            params.set('startTime', `${Math.floor(start)}s`);
+        if (options.primaryColor)
+            params.set('primaryColor', options.primaryColor);
+        if (options.letterboxColor)
+            params.set('letterboxColor', options.letterboxColor);
+        if (options.defaultTextTrack)
+            params.set('defaultTextTrack', options.defaultTextTrack);
+        const query = params.toString();
+        return `https://${host}/${videoId}/iframe${query ? `?${query}` : ''}`;
+    }
+    if (provider === 'youtube') {
+        const domain = privacy ? 'www.youtube-nocookie.com' : 'www.youtube.com';
+        if (autoplay)
+            params.set('autoplay', '1');
+        if (start !== undefined)
+            params.set('start', String(Math.floor(start)));
+        if (!showRelated)
+            params.set('rel', '0');
+        const query = params.toString();
+        return `https://${domain}/embed/${videoId}${query ? `?${query}` : ''}`;
+    }
+    // Vimeo
+    if (autoplay)
+        params.set('autoplay', '1');
+    if (privacy)
+        params.set('dnt', '1');
+    if (start !== undefined)
+        params.set('#t', `${Math.floor(start)}s`);
+    const query = params.toString();
+    return `https://player.vimeo.com/video/${videoId}${query ? `?${query}` : ''}`;
+}
+/**
+ * Poster image URL for an embedded video, when one can be derived without a
+ * network request.
+ *
+ * YouTube and Cloudflare Stream both expose predictable thumbnail URLs. Vimeo
+ * does not — its thumbnails require an oEmbed lookup — so this returns `null`
+ * and the caller should supply `poster` explicitly.
+ */
+export function getEmbedThumbnail(provider, videoId, account = {}) {
+    if (provider === 'youtube') {
+        return `https://i.ytimg.com/vi/${videoId}/hqdefault.jpg`;
+    }
+    if (provider === 'cloudflare') {
+        return cloudflareStreamThumbnail(videoId, { ...account, time: '1s', height: 720 });
+    }
+    return null;
+}
+/**
+ * Best available thumbnail for a media item, for grids and thumbnail strips.
+ *
+ * Returns `null` when the item has no visual representation (audio without
+ * artwork, video without a poster), so callers can render an icon instead.
+ */
+export function getMediaThumbnail(item) {
+    if (item.thumbnail)
+        return item.thumbnail;
+    switch (item.kind) {
+        case 'image':
+            return item.src;
+        case 'video':
+            return item.poster ?? null;
+        case 'audio':
+            return item.artwork ?? null;
+        case 'embed':
+            return (item.poster ??
+                getEmbedThumbnail(item.provider, item.videoId, {
+                    customerCode: item.customerCode,
+                    domain: item.domain,
+                }));
+    }
+}
+/**
+ * Accessible name for a media item.
+ *
+ * Prefers an explicit title, then image alt text, then a positional fallback
+ * so a tile is never announced as just "button".
+ */
+export function getMediaLabel(item, index) {
+    if (item.title)
+        return item.title;
+    if (item.kind === 'image' && item.alt)
+        return item.alt;
+    const kindLabel = isSpatialMedia(item) ? '3D tour' : item.kind === 'embed' ? 'video' : item.kind;
+    return index === undefined
+        ? `Untitled ${kindLabel}`
+        : `${kindLabel.charAt(0).toUpperCase()}${kindLabel.slice(1)} ${index + 1}`;
+}
+/** Whether an item is an interactive 3D space rather than something that plays. */
+export function isSpatialMedia(item) {
+    return item.kind === 'embed' && item.provider === 'matterport';
+}
+/**
+ * Whether an item has a timeline, and so shows a duration badge and play
+ * affordance.
+ *
+ * A Matterport space is embedded like a video but has no timeline — offering
+ * it a play button would promise something the player does not do.
+ */
+export function isTimeBasedMedia(item) {
+    if (isSpatialMedia(item))
+        return false;
+    return item.kind === 'video' || item.kind === 'audio' || item.kind === 'embed';
+}
+/**
+ * Flatten a `TimeRanges` object into plain start/end pairs.
+ *
+ * `TimeRanges` is an opaque, non-iterable browser type; this makes buffered
+ * ranges renderable and testable.
+ */
+export function timeRangesToArray(ranges) {
+    if (!ranges)
+        return [];
+    const result = [];
+    for (let i = 0; i < ranges.length; i += 1) {
+        result.push({ start: ranges.start(i), end: ranges.end(i) });
+    }
+    return result;
+}
+/** Clamp a number into an inclusive range. */
+export function clamp(value, min, max) {
+    if (Number.isNaN(value))
+        return min;
+    return Math.min(Math.max(value, min), max);
+}