@neta-art/cohub 12.5.0 → 13.0.0

package/dist/indexeddb.js

@@ -0,0 +1,79 @@
+//#region src/indexeddb.ts
+const OPEN_TIMEOUT_MS = 3e3;
+const connections = /* @__PURE__ */ new Map();
+function open(name, version, upgrade) {
+	const existing = connections.get(name);
+	if (existing) return existing;
+	const opening = new Promise((resolve, reject) => {
+		const factory = globalThis.indexedDB;
+		if (!factory) {
+			reject(/* @__PURE__ */ new Error("IndexedDB is unavailable."));
+			return;
+		}
+		let late = false;
+		const timer = setTimeout(() => {
+			late = true;
+			reject(/* @__PURE__ */ new Error("IndexedDB did not open in time."));
+		}, OPEN_TIMEOUT_MS);
+		const request = factory.open(name, version);
+		request.onupgradeneeded = () => upgrade(request.result);
+		request.onsuccess = () => {
+			clearTimeout(timer);
+			const db = request.result;
+			if (late) {
+				db.close();
+				return;
+			}
+			const forget = () => {
+				if (connections.get(name) === opening) connections.delete(name);
+			};
+			db.onversionchange = () => {
+				db.close();
+				forget();
+			};
+			db.onclose = forget;
+			resolve(db);
+		};
+		request.onerror = () => {
+			clearTimeout(timer);
+			reject(request.error ?? /* @__PURE__ */ new Error("IndexedDB failed to open."));
+		};
+	});
+	connections.set(name, opening);
+	opening.catch(() => {
+		if (connections.get(name) === opening) connections.delete(name);
+	});
+	return opening;
+}
+function indexedDb(name, version, upgrade) {
+	async function transact(stores, mode, work, retry = true) {
+		const db = await open(name, version, upgrade);
+		let tx;
+		try {
+			tx = db.transaction(stores, mode);
+		} catch (error) {
+			if (!retry) throw error;
+			db.close();
+			connections.delete(name);
+			return transact(stores, mode, work, false);
+		}
+		return new Promise((resolve, reject) => {
+			const result = work(tx);
+			tx.oncomplete = () => resolve(result());
+			tx.onerror = () => reject(tx.error ?? /* @__PURE__ */ new Error("IndexedDB transaction failed."));
+			tx.onabort = () => reject(tx.error ?? /* @__PURE__ */ new Error("IndexedDB transaction aborted."));
+		});
+	}
+	return { transact: (stores, mode, work) => transact(stores, mode, work) };
+}
+function deleteByIndex(store, index, key) {
+	const request = store.index(index).openKeyCursor(IDBKeyRange.only(key));
+	request.onsuccess = () => {
+		const cursor = request.result;
+		if (!cursor) return;
+		store.delete(cursor.primaryKey);
+		cursor.continue();
+	};
+}
+//#endregion
+export { deleteByIndex, indexedDb };

package/dist/media.d.ts

@@ -1,48 +1,34 @@
-import { MediaInfo, mediaInfoFromHeaders, mergeMediaInfo, ossProcessUrl, probeMediaInfo, probeMediaSize, probeVideoFrameSize } from "./protocol/dist/core/media.js";
+import { MEDIA_VARIANT_MAX, MEDIA_VARIANT_SIZES, MediaFacts, MediaFit, MediaInfo, MediaSize, MediaSource, MediaVariantSize, VideoFrameOptions, fitsVideoFrames, imageVariantUrl, mediaFacts, mediaInfoFromHeaders, mediaVariantSize, mergeMediaInfo, ossProcessUrl, probeMediaInfo, probeMediaSize, probeVideoFrameSize, variantSource, videoFrameUrl } from "./protocol/dist/core/media.js";
 //#region src/media.d.ts
 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";
-/** Fixed variant widths keep CDN cache hits high; pick with `mediaVariantSize`. */
-declare const MEDIA_VARIANT_SIZES: readonly [192, 384, 768, 1536];
-declare const MEDIA_VARIANT_MAX = 1536;
-type MediaVariantSize = (typeof MEDIA_VARIANT_SIZES)[number];
-/** Smallest variant covering `pixels` device pixels, capped at the largest. */
-declare function mediaVariantSize(pixels: number): MediaVariantSize;
-/**
- * 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): {
+type ResolvedFile = {
   url: string;
-  type: "image" | "video";
-} | null;
+  media?: MediaFacts;
+};
+type ResolveFileOptions = {
+  /** `playback` needs a streamable URL; `preview` (the default) may take an inline one. */
+  purpose?: "preview" | "playback";
+  fresh?: boolean;
+};
 type MediaPreviewSource = {
   type: MediaType;
   url?: string | null;
   /** Provider cover or poster: art chosen for the work, so it ranks first. */
   previewUrl?: string | null;
+  width?: number | null;
+  height?: number | 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.
+ * Preview images to try in order: the provider cover, a CDN frame of the
+ * video, then its probed first frame. The CDN frame needs no request, so the
+ * first paint never waits and a later probe never swaps the shown still.
  */
 declare function mediaPreviewCandidates(media: MediaPreviewSource, options: {
   size: MediaVariantSize;
   fit?: MediaFit;
 }, info?: Pick<MediaInfo, "firstFrameUrl">): string[];
+declare function cachedMediaInfo(url: string): MediaInfo | undefined;
+declare function loadMediaInfo(url: string, type: MediaType): Promise<MediaInfo>;
+declare function loadMediaSize(url: string, type: "image" | "video"): Promise<MediaSize | null>;
 //#endregion
-export { MEDIA_VARIANT_MAX, MEDIA_VARIANT_SIZES, MediaFit, type MediaInfo, MediaPreviewSource, MediaType, MediaVariantSize, imageVariantUrl, mediaInfoFromHeaders, mediaPreviewCandidates, mediaVariantSize, mergeMediaInfo, ossProcessUrl, probeMediaInfo, probeMediaSize, probeVideoFrameSize, variantSource, videoFrameUrl };
+export { MEDIA_VARIANT_MAX, MEDIA_VARIANT_SIZES, type MediaFacts, type MediaFit, type MediaInfo, MediaPreviewSource, type MediaSize, type MediaSource, MediaType, type MediaVariantSize, ResolveFileOptions, ResolvedFile, type VideoFrameOptions, cachedMediaInfo, fitsVideoFrames, imageVariantUrl, loadMediaInfo, loadMediaSize, mediaFacts, mediaInfoFromHeaders, mediaPreviewCandidates, mediaVariantSize, mergeMediaInfo, ossProcessUrl, probeMediaInfo, probeMediaSize, probeVideoFrameSize, variantSource, videoFrameUrl };

package/dist/media.js

@@ -1,69 +1,9 @@
-import { mediaHost, mediaInfoFromHeaders, mergeMediaInfo, ossProcessUrl, probeMediaInfo, probeMediaSize, probeVideoFrameSize } from "./protocol/dist/core/media.js";
+import { MEDIA_VARIANT_MAX, MEDIA_VARIANT_SIZES, fitsVideoFrames, imageVariantUrl, mediaFacts, mediaInfoFromHeaders, mediaVariantSize, mergeMediaInfo, ossProcessUrl, probeMediaInfo, probeMediaSize, probeVideoFrameSize, variantSource, videoFrameUrl } from "./protocol/dist/core/media.js";
 //#region src/media.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.
-*/
-const RESIZE = {
-	cover: (size) => `m_mfit,w_${size},h_${size}`,
-	contain: (size) => `m_lfit,w_${size},h_${size}`,
-	width: (size) => `w_${size}`
-};
-/** 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
-];
-const MEDIA_VARIANT_MAX = 1536;
-/** Smallest variant covering `pixels` device pixels, capped at the largest. */
-function mediaVariantSize(pixels) {
-	return MEDIA_VARIANT_SIZES.find((size) => size >= pixels) ?? 1536;
-}
-function ossHost(url) {
-	const host = mediaHost(url);
-	return host?.transform === "oss" ? host : void 0;
-}
-/**
-* 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 (!ossHost(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 (!ossHost(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.
+* Preview images to try in order: the provider cover, a CDN frame of the
+* video, then its probed first frame. The CDN frame needs no request, so the
+* first paint never waits and a later probe never swaps the shown still.
 */
 function mediaPreviewCandidates(media, options, info) {
 	const candidates = [];
@@ -77,11 +17,85 @@ function mediaPreviewCandidates(media, options, info) {
 	};
 	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))));
+		const natural = media.width && media.height ? {
+			width: media.width,
+			height: media.height
+		} : null;
+		add(videoFrameUrl(media.url, options.size, {
+			fit: options.fit,
+			natural
+		}));
 		addImage(info?.firstFrameUrl);
 	}
 	return candidates;
 }
+const INFO_CONCURRENCY = 4;
+const INFO_LIMIT = 2e3;
+const EMPTY_INFO_RETRY_MS = 6e4;
+const infoCache = /* @__PURE__ */ new Map();
+const infoRequests = /* @__PURE__ */ new Map();
+const infoWaiting = [];
+let infoActive = 0;
+function cachedMediaInfo(url) {
+	const entry = infoCache.get(url);
+	if (!entry) return void 0;
+	infoCache.delete(url);
+	if (entry.expiresAt <= Date.now()) return void 0;
+	infoCache.set(url, entry);
+	return entry.info;
+}
+async function withInfoSlot(run) {
+	if (infoActive < INFO_CONCURRENCY) infoActive += 1;
+	else await new Promise((resolve) => infoWaiting.push(resolve));
+	try {
+		return await run();
+	} finally {
+		const next = infoWaiting.shift();
+		if (next) next();
+		else infoActive -= 1;
+	}
+}
+function loadMediaInfo(url, type) {
+	const hit = cachedMediaInfo(url);
+	if (hit) return Promise.resolve(hit);
+	let request = infoRequests.get(url);
+	if (!request) {
+		request = withInfoSlot(() => probeMediaInfo(url, { type })).then((info) => {
+			const empty = Object.keys(info).length === 0;
+			infoCache.set(url, {
+				info,
+				expiresAt: empty ? Date.now() + EMPTY_INFO_RETRY_MS : Number.POSITIVE_INFINITY
+			});
+			if (infoCache.size > INFO_LIMIT) infoCache.delete(infoCache.keys().next().value);
+			return info;
+		}).finally(() => infoRequests.delete(url));
+		infoRequests.set(url, request);
+	}
+	return request;
+}
+const sizeRequests = /* @__PURE__ */ new Map();
+function loadMediaSize(url, type) {
+	let request = sizeRequests.get(url);
+	if (!request) {
+		request = loadMediaInfo(url, type).then(async ({ width, height }) => {
+			if (width && height) return {
+				width,
+				height
+			};
+			if (type !== "video") return null;
+			const frame = await withInfoSlot(() => probeVideoFrameSize(url)).catch(() => ({}));
+			return frame.width && frame.height ? {
+				width: frame.width,
+				height: frame.height
+			} : null;
+		});
+		sizeRequests.set(url, request);
+		if (sizeRequests.size > INFO_LIMIT) sizeRequests.delete(sizeRequests.keys().next().value);
+		request.then((size) => {
+			if (!size && sizeRequests.get(url) === request) sizeRequests.delete(url);
+		});
+	}
+	return request;
+}
 //#endregion
-export { MEDIA_VARIANT_MAX, MEDIA_VARIANT_SIZES, imageVariantUrl, mediaInfoFromHeaders, mediaPreviewCandidates, mediaVariantSize, mergeMediaInfo, ossProcessUrl, probeMediaInfo, probeMediaSize, probeVideoFrameSize, variantSource, videoFrameUrl };
+export { MEDIA_VARIANT_MAX, MEDIA_VARIANT_SIZES, cachedMediaInfo, fitsVideoFrames, imageVariantUrl, loadMediaInfo, loadMediaSize, mediaFacts, mediaInfoFromHeaders, mediaPreviewCandidates, mediaVariantSize, mergeMediaInfo, ossProcessUrl, probeMediaInfo, probeMediaSize, probeVideoFrameSize, variantSource, videoFrameUrl };

package/dist/protocol/dist/board-model.d.ts

@@ -2201,52 +2201,59 @@ declare const BoardAnimationSchema: z.ZodObject<{
 type BoardAnimation = z.infer<typeof BoardAnimationSchema>;
 declare const BOARD_ENTER_PRESETS: readonly ["fade-in", "rise", "drop", "pop", "deal"];
 type BoardEnterPreset = (typeof BOARD_ENTER_PRESETS)[number];
+declare const BOARD_BACKGROUND_PATTERNS: readonly ["none", "dots", "grid"];
+type BoardBackgroundPattern = (typeof BOARD_BACKGROUND_PATTERNS)[number];
+declare const BOARD_BACKGROUND_FITS: readonly ["cover", "contain", "repeat"];
+type BoardBackgroundFit = (typeof BOARD_BACKGROUND_FITS)[number];
 declare const BoardBackgroundSchema: z.ZodObject<{
-  kind: z.ZodDefault<z.ZodEnum<{
-    dots: "dots";
-    grid: "grid";
-    image: "image";
-    solid: "solid";
-  }>>;
   color: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
     light: z.ZodString;
     dark: z.ZodString;
   }, z.core.$strict>]>>;
-  imageUrl: z.ZodOptional<z.ZodString>;
-  fit: z.ZodOptional<z.ZodEnum<{
-    contain: "contain";
-    cover: "cover";
-    repeat: "repeat";
+  pattern: z.ZodOptional<z.ZodEnum<{
+    dots: "dots";
+    grid: "grid";
+    none: "none";
   }>>;
-  opacity: z.ZodOptional<z.ZodNumber>;
+  image: z.ZodOptional<z.ZodObject<{
+    src: z.ZodString;
+    fit: z.ZodDefault<z.ZodEnum<{
+      contain: "contain";
+      cover: "cover";
+      repeat: "repeat";
+    }>>;
+    opacity: z.ZodOptional<z.ZodNumber>;
+  }, z.core.$strict>>;
 }, z.core.$strict>;
+type BoardBackground = z.infer<typeof BoardBackgroundSchema>;
 declare const BOARD_GRID_MIN_SIZE = 4;
 declare const BOARD_GRID_MAX_SIZE = 512;
 declare const BOARD_GRID_DEFAULT_SIZE = 24;
 declare const BoardSettingsSchema: z.ZodObject<{
   title: z.ZodOptional<z.ZodString>;
   background: z.ZodDefault<z.ZodObject<{
-    kind: z.ZodDefault<z.ZodEnum<{
-      dots: "dots";
-      grid: "grid";
-      image: "image";
-      solid: "solid";
-    }>>;
     color: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
       light: z.ZodString;
       dark: z.ZodString;
     }, z.core.$strict>]>>;
-    imageUrl: z.ZodOptional<z.ZodString>;
-    fit: z.ZodOptional<z.ZodEnum<{
-      contain: "contain";
-      cover: "cover";
-      repeat: "repeat";
+    pattern: z.ZodOptional<z.ZodEnum<{
+      dots: "dots";
+      grid: "grid";
+      none: "none";
     }>>;
-    opacity: z.ZodOptional<z.ZodNumber>;
+    image: z.ZodOptional<z.ZodObject<{
+      src: z.ZodString;
+      fit: z.ZodDefault<z.ZodEnum<{
+        contain: "contain";
+        cover: "cover";
+        repeat: "repeat";
+      }>>;
+      opacity: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
   }, z.core.$strict>>;
   grid: z.ZodOptional<z.ZodObject<{
-    visible: z.ZodDefault<z.ZodBoolean>;
     size: z.ZodDefault<z.ZodNumber>;
+    snap: z.ZodDefault<z.ZodBoolean>;
   }, z.core.$strict>>;
   enter: z.ZodOptional<z.ZodObject<{
     preset: z.ZodEnum<{
@@ -2288,4 +2295,4 @@ type BoardDelta = {
 };
 declare function isEmptyBoardDelta(delta: BoardDelta): boolean;
 //#endregion
-export { BOARD_ANCHOR_SIDES, BOARD_ARROW_ROUTES, BOARD_CAMERA_TARGET, BOARD_COLOR_TOKENS, BOARD_DASHES, BOARD_DERIVED_SIZE_TYPES, BOARD_EFFECT_KINDS, BOARD_EFFECT_KIND_INFO, BOARD_ENTER_PRESETS, BOARD_EXTENSION_TYPE_PATTERN, BOARD_GRID_DEFAULT_SIZE, BOARD_GRID_MAX_SIZE, BOARD_GRID_MIN_SIZE, BOARD_ID_MAX_LENGTH, BOARD_ITEM_SCHEMAS, BOARD_ITEM_TYPES, BOARD_PLAY_MODES, BOARD_SHAPE_GEOMETRIES, BOARD_TASK_ARTIFACT_LIMIT, BOARD_TEXT_ALIGNS, BoardAnchorSide, BoardAnimation, BoardAnimationHeader, BoardAnimationHeaderSchema, BoardAnimationSchema, BoardArrowAnchor, BoardArrowAnchorSchema, BoardArrowBinding, BoardArrowBindingSchema, BoardArrowEnd, BoardArrowEndSchema, BoardArrowItem, BoardArrowItemSchema, BoardArrowRoute, BoardAudioItem, BoardAudioItemSchema, BoardBackgroundSchema, BoardBuiltinItem, BoardBuiltinItemType, BoardColor, BoardColorSchema, BoardColorToken, BoardCropSchema, BoardCustomItem, BoardCustomItemSchema, BoardDash, BoardDelta, BoardDiagnostic, BoardDocument, BoardDrawItem, BoardDrawItemSchema, BoardDrawPoint, BoardDrawPointSchema, BoardEaseSchema, BoardEffectItem, BoardEffectItemSchema, BoardEffectKind, BoardEnterPreset, BoardExtensionItem, BoardExtensionItemSchema, BoardFileBackedItem, BoardFileItem, BoardFileItemSchema, BoardFrameItem, BoardFrameItemSchema, BoardIdSchema, BoardImageItem, BoardImageItemSchema, BoardItem, BoardItemPreview, BoardItemPreviewSchema, BoardItemType, BoardKeySchema, BoardKeyframe, BoardKeyframeSchema, BoardMarker, BoardMarkerSchema, BoardMediaOrigin, BoardMediaOriginSchema, BoardMediaSnapshot, BoardMediaSnapshotSchema, BoardMediaSource, BoardMediaSourceSchema, BoardPatch, BoardPatchSchema, BoardPlayMode, BoardScript, BoardScriptSchema, BoardSettings, BoardSettingsSchema, BoardShapeGeometry, BoardShapeItem, BoardShapeItemSchema, BoardSize, BoardSizeSchema, BoardStyle, BoardStyleSchema, BoardTaskArtifact, BoardTaskArtifactSchema, BoardTaskItem, BoardTaskItemSchema, BoardTaskSnapshot, BoardTaskSnapshotSchema, BoardTextItem, BoardTextItemSchema, BoardTrack, BoardTrackSchema, BoardVec2, BoardVec2Schema, BoardVideoItem, BoardVideoItemSchema, boardItemPreview, boardItemSchema, emptyBoardDocument, hasAuthoredSize, isBoardColorString, isBoardEase, isBuiltinItem, isBuiltinItemType, isEmptyBoardDelta, isFileBackedItem, isMediaItem, isSafeBoardSourcePath, parseBoardItem, parseBoardMediaSource };
+export { BOARD_ANCHOR_SIDES, BOARD_ARROW_ROUTES, BOARD_BACKGROUND_FITS, BOARD_BACKGROUND_PATTERNS, BOARD_CAMERA_TARGET, BOARD_COLOR_TOKENS, BOARD_DASHES, BOARD_DERIVED_SIZE_TYPES, BOARD_EFFECT_KINDS, BOARD_EFFECT_KIND_INFO, BOARD_ENTER_PRESETS, BOARD_EXTENSION_TYPE_PATTERN, BOARD_GRID_DEFAULT_SIZE, BOARD_GRID_MAX_SIZE, BOARD_GRID_MIN_SIZE, BOARD_ID_MAX_LENGTH, BOARD_ITEM_SCHEMAS, BOARD_ITEM_TYPES, BOARD_PLAY_MODES, BOARD_SHAPE_GEOMETRIES, BOARD_TASK_ARTIFACT_LIMIT, BOARD_TEXT_ALIGNS, BoardAnchorSide, BoardAnimation, BoardAnimationHeader, BoardAnimationHeaderSchema, BoardAnimationSchema, BoardArrowAnchor, BoardArrowAnchorSchema, BoardArrowBinding, BoardArrowBindingSchema, BoardArrowEnd, BoardArrowEndSchema, BoardArrowItem, BoardArrowItemSchema, BoardArrowRoute, BoardAudioItem, BoardAudioItemSchema, BoardBackground, BoardBackgroundFit, BoardBackgroundPattern, BoardBackgroundSchema, BoardBuiltinItem, BoardBuiltinItemType, BoardColor, BoardColorSchema, BoardColorToken, BoardCropSchema, BoardCustomItem, BoardCustomItemSchema, BoardDash, BoardDelta, BoardDiagnostic, BoardDocument, BoardDrawItem, BoardDrawItemSchema, BoardDrawPoint, BoardDrawPointSchema, BoardEaseSchema, BoardEffectItem, BoardEffectItemSchema, BoardEffectKind, BoardEnterPreset, BoardExtensionItem, BoardExtensionItemSchema, BoardFileBackedItem, BoardFileItem, BoardFileItemSchema, BoardFrameItem, BoardFrameItemSchema, BoardIdSchema, BoardImageItem, BoardImageItemSchema, BoardItem, BoardItemPreview, BoardItemPreviewSchema, BoardItemType, BoardKeySchema, BoardKeyframe, BoardKeyframeSchema, BoardMarker, BoardMarkerSchema, BoardMediaOrigin, BoardMediaOriginSchema, BoardMediaSnapshot, BoardMediaSnapshotSchema, BoardMediaSource, BoardMediaSourceSchema, BoardPatch, BoardPatchSchema, BoardPlayMode, BoardScript, BoardScriptSchema, BoardSettings, BoardSettingsSchema, BoardShapeGeometry, BoardShapeItem, BoardShapeItemSchema, BoardSize, BoardSizeSchema, BoardStyle, BoardStyleSchema, BoardTaskArtifact, BoardTaskArtifactSchema, BoardTaskItem, BoardTaskItemSchema, BoardTaskSnapshot, BoardTaskSnapshotSchema, BoardTextItem, BoardTextItemSchema, BoardTrack, BoardTrackSchema, BoardVec2, BoardVec2Schema, BoardVideoItem, BoardVideoItemSchema, boardItemPreview, boardItemSchema, emptyBoardDocument, hasAuthoredSize, isBoardColorString, isBoardEase, isBuiltinItem, isBuiltinItemType, isEmptyBoardDelta, isFileBackedItem, isMediaItem, isSafeBoardSourcePath, parseBoardItem, parseBoardMediaSource };

package/dist/protocol/dist/board-model.js

@@ -574,31 +574,34 @@ const BOARD_ENTER_PRESETS = [
 	"pop",
 	"deal"
 ];
+const BOARD_BACKGROUND_PATTERNS = [
+	"none",
+	"dots",
+	"grid"
+];
+const BOARD_BACKGROUND_FITS = [
+	"cover",
+	"contain",
+	"repeat"
+];
 const BoardBackgroundSchema = z.object({
-	kind: z.enum([
-		"solid",
-		"dots",
-		"grid",
-		"image"
-	]).default("dots"),
 	color: BoardColorSchema.optional(),
-	imageUrl: z.string().url().max(4096).optional().describe("Background image for kind image."),
-	fit: z.enum([
-		"cover",
-		"contain",
-		"repeat"
-	]).optional(),
-	opacity: ratio.optional()
-}).strict();
+	pattern: z.enum(BOARD_BACKGROUND_PATTERNS).optional().describe("Spaced by grid.size; omit to follow the theme."),
+	image: z.object({
+		src: BoardMediaSourceSchema,
+		fit: z.enum(BOARD_BACKGROUND_FITS).default("cover").describe("cover and contain fill the view; repeat tiles the Board at one board unit per image pixel."),
+		opacity: ratio.optional()
+	}).strict().optional()
+}).strict().describe("Layers drawn under every item: color, then image, then pattern. Without a color or image the theme's backdrop shows.");
 const BOARD_GRID_MIN_SIZE = 4;
 const BOARD_GRID_MAX_SIZE = 512;
 const BOARD_GRID_DEFAULT_SIZE = 24;
 const BoardSettingsSchema = z.object({
 	title: z.string().min(1).max(255).optional(),
-	background: BoardBackgroundSchema.default({ kind: "dots" }),
+	background: BoardBackgroundSchema.default({}),
 	grid: z.object({
-		visible: z.boolean().default(false).describe("Show the grid overlay."),
-		size: finite.min(4).max(512).default(24)
+		size: finite.min(4).max(512).default(24).describe("Pattern spacing and snap step, in board units."),
+		snap: z.boolean().default(false).describe("Snap moved and resized items to the grid.")
 	}).strict().optional(),
 	enter: z.object({
 		preset: z.enum(BOARD_ENTER_PRESETS),
@@ -622,4 +625,4 @@ function isEmptyBoardDelta(delta) {
 	return !delta.board && Object.keys(delta.items ?? {}).length === 0 && Object.keys(delta.animations ?? {}).length === 0 && Object.keys(delta.tracks ?? {}).length === 0;
 }
 //#endregion
-export { BOARD_ANCHOR_SIDES, BOARD_ARROW_ROUTES, BOARD_CAMERA_TARGET, BOARD_COLOR_TOKENS, BOARD_DASHES, BOARD_DERIVED_SIZE_TYPES, BOARD_EFFECT_KINDS, BOARD_EFFECT_KIND_INFO, BOARD_ENTER_PRESETS, BOARD_EXTENSION_TYPE_PATTERN, BOARD_GRID_DEFAULT_SIZE, BOARD_GRID_MAX_SIZE, BOARD_GRID_MIN_SIZE, BOARD_ID_MAX_LENGTH, BOARD_ITEM_SCHEMAS, BOARD_ITEM_TYPES, BOARD_PLAY_MODES, BOARD_SHAPE_GEOMETRIES, BOARD_TASK_ARTIFACT_LIMIT, BOARD_TEXT_ALIGNS, BoardAnimationHeaderSchema, BoardAnimationSchema, BoardArrowAnchorSchema, BoardArrowBindingSchema, BoardArrowEndSchema, BoardArrowItemSchema, BoardAudioItemSchema, BoardBackgroundSchema, BoardColorSchema, BoardCropSchema, BoardCustomItemSchema, BoardDrawItemSchema, BoardDrawPointSchema, BoardEaseSchema, BoardEffectItemSchema, BoardExtensionItemSchema, BoardFileItemSchema, BoardFrameItemSchema, BoardIdSchema, BoardImageItemSchema, BoardItemPreviewSchema, BoardKeySchema, BoardKeyframeSchema, BoardMarkerSchema, BoardMediaOriginSchema, BoardMediaSnapshotSchema, BoardMediaSourceSchema, BoardPatchSchema, BoardScriptSchema, BoardSettingsSchema, BoardShapeItemSchema, BoardSizeSchema, BoardStyleSchema, BoardTaskArtifactSchema, BoardTaskItemSchema, BoardTaskSnapshotSchema, BoardTextItemSchema, BoardTrackSchema, BoardVec2Schema, BoardVideoItemSchema, boardItemPreview, boardItemSchema, emptyBoardDocument, hasAuthoredSize, isBoardColorString, isBoardEase, isBuiltinItem, isBuiltinItemType, isEmptyBoardDelta, isFileBackedItem, isMediaItem, isSafeBoardSourcePath, parseBoardItem, parseBoardMediaSource };
+export { BOARD_ANCHOR_SIDES, BOARD_ARROW_ROUTES, BOARD_BACKGROUND_FITS, BOARD_BACKGROUND_PATTERNS, BOARD_CAMERA_TARGET, BOARD_COLOR_TOKENS, BOARD_DASHES, BOARD_DERIVED_SIZE_TYPES, BOARD_EFFECT_KINDS, BOARD_EFFECT_KIND_INFO, BOARD_ENTER_PRESETS, BOARD_EXTENSION_TYPE_PATTERN, BOARD_GRID_DEFAULT_SIZE, BOARD_GRID_MAX_SIZE, BOARD_GRID_MIN_SIZE, BOARD_ID_MAX_LENGTH, BOARD_ITEM_SCHEMAS, BOARD_ITEM_TYPES, BOARD_PLAY_MODES, BOARD_SHAPE_GEOMETRIES, BOARD_TASK_ARTIFACT_LIMIT, BOARD_TEXT_ALIGNS, BoardAnimationHeaderSchema, BoardAnimationSchema, BoardArrowAnchorSchema, BoardArrowBindingSchema, BoardArrowEndSchema, BoardArrowItemSchema, BoardAudioItemSchema, BoardBackgroundSchema, BoardColorSchema, BoardCropSchema, BoardCustomItemSchema, BoardDrawItemSchema, BoardDrawPointSchema, BoardEaseSchema, BoardEffectItemSchema, BoardExtensionItemSchema, BoardFileItemSchema, BoardFrameItemSchema, BoardIdSchema, BoardImageItemSchema, BoardItemPreviewSchema, BoardKeySchema, BoardKeyframeSchema, BoardMarkerSchema, BoardMediaOriginSchema, BoardMediaSnapshotSchema, BoardMediaSourceSchema, BoardPatchSchema, BoardScriptSchema, BoardSettingsSchema, BoardShapeItemSchema, BoardSizeSchema, BoardStyleSchema, BoardTaskArtifactSchema, BoardTaskItemSchema, BoardTaskSnapshotSchema, BoardTextItemSchema, BoardTrackSchema, BoardVec2Schema, BoardVideoItemSchema, boardItemPreview, boardItemSchema, emptyBoardDocument, hasAuthoredSize, isBoardColorString, isBoardEase, isBuiltinItem, isBuiltinItemType, isEmptyBoardDelta, isFileBackedItem, isMediaItem, isSafeBoardSourcePath, parseBoardItem, parseBoardMediaSource };

package/dist/protocol/dist/board.d.ts

@@ -14,6 +14,25 @@ type BoardManifest = z.infer<typeof BoardManifestSchema>;
 declare function parseBoardManifest(input: string | unknown): BoardManifest;
 declare function serializeBoardManifest(manifest: BoardManifest): string;
 declare function isBoardPath(path: string): boolean;
+declare const BoardReadInputSchema: z.ZodObject<{
+  only: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+    animations: "animations";
+    items: "items";
+  }>>>;
+  rect: z.ZodOptional<z.ZodObject<{
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+  }, z.core.$strict>>;
+  within: z.ZodOptional<z.ZodString>;
+  items: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  animations: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  limit: z.ZodOptional<z.ZodNumber>;
+  cursor: z.ZodOptional<z.ZodString>;
+  since: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+type BoardReadInput = z.infer<typeof BoardReadInputSchema>;
 type BoardReadResult = {
   id: string;
   title: string;
@@ -24,6 +43,7 @@ type BoardReadResult = {
   animations?: Record<string, Record<string, unknown>>;
   playback: BoardPlaybackSnapshot | null;
   next?: string;
+  changes?: BoardDelta[];
 };
 type BoardChangeSummary = {
   board: boolean;
@@ -94,4 +114,4 @@ declare const BoardPlaybackCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strict>], "type">;
 type BoardPlaybackCommand = z.infer<typeof BoardPlaybackCommandSchema>;
 //#endregion
-export { BOARD_CLIPBOARD_KIND, BOARD_CLIPBOARD_MIME, BoardApplyResult, BoardChangeSummary, BoardHistoryPage, BoardManifest, BoardManifestSchema, type BoardPatch, BoardPlaybackCommand, BoardPlaybackCommandSchema, BoardPlaybackSnapshot, BoardPlaybackStatus, BoardReadResult, BoardTransactionRecord, isBoardPath, parseBoardManifest, serializeBoardManifest };
+export { BOARD_CLIPBOARD_KIND, BOARD_CLIPBOARD_MIME, BoardApplyResult, BoardChangeSummary, BoardHistoryPage, BoardManifest, BoardManifestSchema, type BoardPatch, BoardPlaybackCommand, BoardPlaybackCommandSchema, BoardPlaybackSnapshot, BoardPlaybackStatus, BoardReadInput, BoardReadInputSchema, BoardReadResult, BoardTransactionRecord, isBoardPath, parseBoardManifest, serializeBoardManifest };

package/dist/protocol/dist/board.js

@@ -50,10 +50,14 @@ z.object({
 	items: z.array(z.string().min(1)).max(5e4).optional(),
 	animations: z.array(z.string().min(1)).max(1e4).optional(),
 	limit: z.number().int().min(1).max(5e4).optional(),
-	cursor: z.string().min(1).optional()
+	cursor: z.string().min(1).optional(),
+	since: z.number().int().nonnegative().optional()
 }).strict().refine((read) => !(read.cursor && (read.rect || read.within)), {
 	path: ["cursor"],
 	message: "cursor pages by id, so it cannot be combined with rect or within"
+}).refine((read) => read.since === void 0 || Object.entries(read).every(([key, value]) => key === "since" || value === void 0), {
+	path: ["since"],
+	message: "since syncs the whole Board, so it cannot be combined with other read options"
 });
 z.object({
 	patch: BoardPatchSchema,

package/dist/protocol/dist/core/media.d.ts

@@ -1,6 +1,30 @@
 //#region ../protocol/dist/core/media.d.ts
+type MediaFit = "cover" | "contain" | "width";
+type MediaSize = {
+  width: number;
+  height: number;
+};
+type MediaSource = {
+  url: string;
+  type: "image" | "video";
+};
+/** Fixed variant edges keep CDN cache hits high; pick one with `mediaVariantSize`. */
+declare const MEDIA_VARIANT_SIZES: readonly [192, 384, 768, 1536];
+declare const MEDIA_VARIANT_MAX = 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;
+declare function imageVariantUrl(url: string, size: MediaVariantSize, fit?: MediaFit): string | null;
+type VideoFrameOptions = {
+  fit?: MediaFit;
+  natural?: MediaSize | null;
+  aspect?: number | null;
+};
+declare function videoFrameUrl(url: string, size: MediaVariantSize, options?: VideoFrameOptions): string | null;
+declare function fitsVideoFrames(url: string): boolean;
+declare function variantSource(url: string): MediaSource | null;
 type MediaInfo = {
   width?: number;
   height?: number;
@@ -11,6 +35,12 @@ type MediaInfo = {
   mimeType?: string;
   bytes?: number;
 };
+type MediaFacts = {
+  width: number;
+  height: number;
+  durationMs?: number;
+};
+declare function mediaFacts(facts: Partial<MediaFacts> | null | undefined): MediaFacts | null;
 /** Media facts from response headers; `x-oss-meta-*` need CORS exposure in browsers. */
 declare function mediaInfoFromHeaders(headers: Headers, url: string): MediaInfo;
 declare function mergeMediaInfo(primary: MediaInfo, fallback: MediaInfo): MediaInfo;
@@ -20,10 +50,6 @@ type ProbeOptions = {
   signal?: AbortSignal;
 };
 declare function probeMediaInfo(url: string, options: ProbeOptions): Promise<MediaInfo>;
-/**
- * A video's dimensions, read from the header of its first frame rendered as a
- * full-size PNG by OSS; only the first 24 bytes are read. Throws on failure.
- */
 declare function probeVideoFrameSize(url: string, options?: {
   fetch?: typeof globalThis.fetch;
   signal?: AbortSignal;
@@ -31,9 +57,6 @@ declare function probeVideoFrameSize(url: string, options?: {
 declare function probeMediaSize(url: string, type: "image" | "video", options?: {
   fetch?: typeof globalThis.fetch;
   signal?: AbortSignal;
-}): Promise<{
-  width: number;
-  height: number;
-} | null>;
+}): Promise<MediaSize | null>;
 //#endregion
-export { MediaInfo, mediaInfoFromHeaders, mergeMediaInfo, ossProcessUrl, probeMediaInfo, probeMediaSize, probeVideoFrameSize };
+export { MEDIA_VARIANT_MAX, MEDIA_VARIANT_SIZES, MediaFacts, MediaFit, MediaInfo, MediaSize, MediaSource, MediaVariantSize, VideoFrameOptions, fitsVideoFrames, imageVariantUrl, mediaFacts, mediaInfoFromHeaders, mediaVariantSize, mergeMediaInfo, ossProcessUrl, probeMediaInfo, probeMediaSize, probeVideoFrameSize, variantSource, videoFrameUrl };