@neta-art/cohub 8.22.0 → 8.24.0

package/dist/media.d.ts

@@ -0,0 +1,81 @@
+//#region src/media.d.ts
+/**
+ * Remote media delivery. Previews and metadata resolve through ordered
+ * strategies — the cheapest trustworthy source first, each later one only
+ * filling what the earlier ones left — so every consumer degrades the same way.
+ *
+ * URL rewrites happen locally without a request, so they apply only to hosts
+ * known to serve Aliyun OSS processing; any other URL is used as is.
+ */
+type MediaType = "image" | "video" | "audio";
+/**
+ * `cover` guarantees the short edge (square tiles), `contain` bounds the long
+ * edge (viewers, textures), `width` bounds only the width, so flowing layouts
+ * keep the original's rendered size.
+ */
+type MediaFit = "cover" | "contain" | "width";
+type MediaInfo = {
+  width?: number;
+  height?: number;
+  durationMs?: number;
+  frameCount?: number;
+  firstFrameUrl?: string;
+  lastFrameUrl?: string;
+  mimeType?: string;
+  bytes?: number;
+};
+/** Fixed variant widths keep CDN cache hits high; pick with `mediaVariantSize`. */
+declare const MEDIA_VARIANT_SIZES: readonly [192, 384, 768, 1536];
+type MediaVariantSize = (typeof MEDIA_VARIANT_SIZES)[number];
+/** Smallest variant covering `pixels` device pixels, capped at the largest. */
+declare function mediaVariantSize(pixels: number): MediaVariantSize;
+/** Append an OSS process to `url`, keeping its query and hash. */
+declare function ossProcessUrl(url: string, process: string): string;
+/**
+ * A resized WebP of an image, fitted per `MediaFit`. Never enlarges. GIFs keep
+ * their original, since a converted variant may lose the animation.
+ */
+declare function imageVariantUrl(url: string, size: MediaVariantSize, fit?: MediaFit): string | null;
+/** A still JPEG of a video's first frame, `width` wide. */
+declare function videoFrameUrl(url: string, width: MediaVariantSize): string | null;
+/**
+ * The media a CDN variant was derived from, to fall back to when processing
+ * fails. Only the process parameter is cut, so the rest of the URL (signed
+ * queries included) stays byte-for-byte.
+ */
+declare function variantSource(url: string): {
+  url: string;
+  type: "image" | "video";
+} | null;
+type MediaPreviewSource = {
+  type: MediaType;
+  url?: string | null;
+  /** Provider cover or poster: art chosen for the work, so it ranks first. */
+  previewUrl?: string | null;
+};
+/**
+ * Preview images to try in order: the provider cover (resized, then as is),
+ * then a snapshot of the video itself, then the probed first frame.
+ * An empty list means only the media element itself can render a frame.
+ */
+declare function mediaPreviewCandidates(media: MediaPreviewSource, options: {
+  size: MediaVariantSize;
+  fit?: MediaFit;
+}, info?: Pick<MediaInfo, "firstFrameUrl">): string[];
+/** Media facts from response headers; `x-oss-meta-*` need CORS exposure in browsers. */
+declare function mediaInfoFromHeaders(headers: Headers, url: string): MediaInfo;
+/** Fields of `primary` win; `fallback` fills the rest. */
+declare function mergeMediaInfo(primary: MediaInfo, fallback: MediaInfo): MediaInfo;
+type ProbeOptions = {
+  type: MediaType;
+  fetch?: typeof globalThis.fetch;
+  signal?: AbortSignal;
+};
+/**
+ * Probe remote media: OSS meta headers (one HEAD, the only source of video
+ * duration and frames), then OSS `image/info` for image dimensions. Unknown
+ * hosts and failed steps resolve to what was learned so far; never throws.
+ */
+declare function probeMediaInfo(url: string, options: ProbeOptions): Promise<MediaInfo>;
+//#endregion
+export { MEDIA_VARIANT_SIZES, MediaFit, MediaInfo, MediaPreviewSource, MediaType, MediaVariantSize, imageVariantUrl, mediaInfoFromHeaders, mediaPreviewCandidates, mediaVariantSize, mergeMediaInfo, ossProcessUrl, probeMediaInfo, variantSource, videoFrameUrl };

package/dist/media.js

@@ -0,0 +1,177 @@
+//#region src/media.ts
+const RESIZE = {
+	cover: (size) => `m_mfit,w_${size},h_${size}`,
+	contain: (size) => `m_lfit,w_${size},h_${size}`,
+	width: (size) => `w_${size}`
+};
+const MEDIA_HOSTS = /* @__PURE__ */ new Map([["router-files.neta.art", {
+	process: true,
+	metaHeaders: true
+}], ["public.cohub.live", {
+	process: true,
+	metaHeaders: false
+}]]);
+/** Snapshots render at the requested width, upscaling small videos; cap it. */
+const VIDEO_FRAME_MAX_WIDTH = 768;
+/** Fixed variant widths keep CDN cache hits high; pick with `mediaVariantSize`. */
+const MEDIA_VARIANT_SIZES = [
+	192,
+	384,
+	768,
+	1536
+];
+/** Smallest variant covering `pixels` device pixels, capped at the largest. */
+function mediaVariantSize(pixels) {
+	return MEDIA_VARIANT_SIZES.find((size) => size >= pixels) ?? 1536;
+}
+function capabilities(url) {
+	if (!/^https:\/\//i.test(url)) return void 0;
+	try {
+		return MEDIA_HOSTS.get(new URL(url).hostname);
+	} catch {
+		return;
+	}
+}
+const OSS_PROCESS = /[?&]x-oss-process=/;
+/** Append an OSS process to `url`, keeping its query and hash. */
+function ossProcessUrl(url, process) {
+	if (/^(data|blob):/i.test(url) || OSS_PROCESS.test(url)) return url;
+	const hashIndex = url.indexOf("#");
+	const base = hashIndex >= 0 ? url.slice(0, hashIndex) : url;
+	const hash = hashIndex >= 0 ? url.slice(hashIndex) : "";
+	return `${base}${base.includes("?") ? "&" : "?"}x-oss-process=${process}${hash}`;
+}
+/**
+* A resized WebP of an image, fitted per `MediaFit`. Never enlarges. GIFs keep
+* their original, since a converted variant may lose the animation.
+*/
+function imageVariantUrl(url, size, fit = "contain") {
+	if (!capabilities(url) || /\.gif$/i.test(new URL(url).pathname)) return null;
+	return ossProcessUrl(url, `image/resize,${RESIZE[fit](size)}/quality,q_82/format,webp`);
+}
+/** A still JPEG of a video's first frame, `width` wide. */
+function videoFrameUrl(url, width) {
+	if (!capabilities(url)) return null;
+	return ossProcessUrl(url, `video/snapshot,t_0,f_jpg,w_${width},m_fast`);
+}
+/**
+* The media a CDN variant was derived from, to fall back to when processing
+* fails. Only the process parameter is cut, so the rest of the URL (signed
+* queries included) stays byte-for-byte.
+*/
+function variantSource(url) {
+	const match = /([?&])x-oss-process=([^&#]*)/.exec(url);
+	if (!match) return null;
+	const [segment, separator, process = ""] = match;
+	const head = url.slice(0, match.index);
+	const tail = url.slice(match.index + segment.length);
+	return {
+		url: separator === "?" && tail.startsWith("&") ? `${head}?${tail.slice(1)}` : head + tail,
+		type: process.startsWith("video/") ? "video" : "image"
+	};
+}
+/**
+* Preview images to try in order: the provider cover (resized, then as is),
+* then a snapshot of the video itself, then the probed first frame.
+* An empty list means only the media element itself can render a frame.
+*/
+function mediaPreviewCandidates(media, options, info) {
+	const candidates = [];
+	const add = (url) => {
+		if (url && !candidates.includes(url)) candidates.push(url);
+	};
+	const addImage = (url) => {
+		if (!url) return;
+		add(imageVariantUrl(url, options.size, options.fit));
+		add(url);
+	};
+	addImage(media.type === "image" ? media.url : media.previewUrl);
+	if (media.type === "video" && media.url) {
+		const width = options.fit === "cover" ? options.size * 2 : options.size;
+		add(videoFrameUrl(media.url, mediaVariantSize(Math.min(width, VIDEO_FRAME_MAX_WIDTH))));
+		addImage(info?.firstFrameUrl);
+	}
+	return candidates;
+}
+function positive(value) {
+	const number = typeof value === "string" ? Number(value) : value;
+	return typeof number === "number" && Number.isFinite(number) && number > 0 ? number : void 0;
+}
+/** Frame URLs must stay on the media's own origin. */
+function sameOriginUrl(value, origin) {
+	if (!value) return void 0;
+	try {
+		const url = new URL(value);
+		return url.protocol === "https:" && url.origin === origin ? url.href : void 0;
+	} catch {
+		return;
+	}
+}
+function compact(info) {
+	return Object.fromEntries(Object.entries(info).filter(([, value]) => value !== void 0));
+}
+/** Media facts from response headers; `x-oss-meta-*` need CORS exposure in browsers. */
+function mediaInfoFromHeaders(headers, url) {
+	const origin = new URL(url).origin;
+	const meta = (name) => headers.get(`x-oss-meta-${name}`);
+	const seconds = positive(meta("duration"));
+	const frameCount = positive(meta("nb-frames"));
+	return compact({
+		width: positive(meta("width")),
+		height: positive(meta("height")),
+		durationMs: seconds ? Math.round(seconds * 1e3) : void 0,
+		frameCount: frameCount ? Math.round(frameCount) : void 0,
+		firstFrameUrl: sameOriginUrl(meta("first-frame"), origin),
+		lastFrameUrl: sameOriginUrl(meta("last-frame"), origin),
+		mimeType: headers.get("content-type")?.split(";")[0]?.trim() || void 0,
+		bytes: positive(headers.get("content-length"))
+	});
+}
+/** Fields of `primary` win; `fallback` fills the rest. */
+function mergeMediaInfo(primary, fallback) {
+	return compact({
+		...fallback,
+		...compact(primary)
+	});
+}
+function hasDimensions(info) {
+	return info.width !== void 0 && info.height !== void 0;
+}
+async function probeHeaders(url, options) {
+	const response = await (options.fetch ?? globalThis.fetch)(url, {
+		method: "HEAD",
+		signal: options.signal
+	});
+	return response.ok ? mediaInfoFromHeaders(response.headers, url) : {};
+}
+async function probeImageInfo(url, options) {
+	if (OSS_PROCESS.test(url)) return {};
+	const response = await (options.fetch ?? globalThis.fetch)(ossProcessUrl(url, "image/info"), { signal: options.signal });
+	if (!response.ok) return {};
+	const body = await response.json();
+	return compact({
+		width: positive(body.ImageWidth?.value),
+		height: positive(body.ImageHeight?.value),
+		bytes: positive(body.FileSize?.value)
+	});
+}
+/**
+* Probe remote media: OSS meta headers (one HEAD, the only source of video
+* duration and frames), then OSS `image/info` for image dimensions. Unknown
+* hosts and failed steps resolve to what was learned so far; never throws.
+*/
+async function probeMediaInfo(url, options) {
+	const host = capabilities(url);
+	if (!host) return {};
+	let info = {};
+	const attempt = async (strategy) => {
+		try {
+			info = mergeMediaInfo(info, await strategy());
+		} catch {}
+	};
+	if (host.metaHeaders) await attempt(() => probeHeaders(url, options));
+	if (options.type === "image" && !hasDimensions(info)) await attempt(() => probeImageInfo(url, options));
+	return info;
+}
+//#endregion
+export { MEDIA_VARIANT_SIZES, imageVariantUrl, mediaInfoFromHeaders, mediaPreviewCandidates, mediaVariantSize, mergeMediaInfo, ossProcessUrl, probeMediaInfo, variantSource, videoFrameUrl };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neta-art/cohub",
-  "version": "8.22.0",
+  "version": "8.24.0",
   "description": "Cohub SDK for spaces, sessions, boards, and realtime agent collaboration.",
   "license": "Apache-2.0",
   "private": false,
@@ -49,6 +49,10 @@
       "types": "./dist/space-picker.d.ts",
       "import": "./dist/space-picker.js"
     },
+    "./media": {
+      "types": "./dist/media.d.ts",
+      "import": "./dist/media.js"
+    },
     "./board": {
       "types": "./dist/board/index.d.ts",
       "import": "./dist/board/index.js"