@neta-art/cohub-cli 10.12.1 → 10.12.2

package/README.md

@@ -323,6 +323,7 @@ Use the filters so a large Board is not read whole:
 cohub -s <spaceId> boards get <boardId> --items title,note
 cohub -s <spaceId> boards get <boardId> --within s1
 cohub -s <spaceId> boards get <boardId> --rect 0,0,960,540
+cohub -s <spaceId> boards get <boardId> --since 12   # only the changes after version 12
 ```
 
 Start from an example and write it with `apply`, a JSON Merge Patch where fields

package/dist/avatar.d.ts

@@ -18,7 +18,11 @@ export declare function uploadAvatarAsset(input: {
     uploadMethod: "PUT";
     uploadHeaders?: Record<string, string>;
 }>;
-export declare function normalizeChatImageFile(path: string): Promise<Buffer>;
+export declare function normalizeChatImageFile(path: string): Promise<{
+    body: Buffer<ArrayBuffer>;
+    width: number;
+    height: number;
+}>;
 export declare function uploadChatImageAsset(input: {
     client: CohubHttpClient;
     spaceId?: string;
@@ -32,5 +36,7 @@ export declare function uploadChatImageAsset(input: {
     uploadMethod: "PUT";
     uploadHeaders?: Record<string, string>;
     size: number;
+    width: number;
+    height: number;
 }>;
 export {};

package/dist/avatar.js

@@ -51,14 +51,15 @@ const CHAT_IMAGE_MAX_EDGE = 1984;
 const CHAT_IMAGE_QUALITY = 86;
 export async function normalizeChatImageFile(path) {
     const sharp = await loadSharp();
-    return sharp(path)
+    const { data, info } = await sharp(path)
         .rotate()
         .resize(CHAT_IMAGE_MAX_EDGE, CHAT_IMAGE_MAX_EDGE, { fit: "inside", withoutEnlargement: true })
         .webp({ quality: CHAT_IMAGE_QUALITY })
-        .toBuffer();
+        .toBuffer({ resolveWithObject: true });
+    return { body: data, width: info.width, height: info.height };
 }
 export async function uploadChatImageAsset(input) {
-    const body = await normalizeChatImageFile(input.path);
+    const { body, width, height } = await normalizeChatImageFile(input.path);
     const asset = await input.client.publicAssets.uploadChatImageAttachment({
         spaceId: input.spaceId,
         sessionId: input.sessionId,
@@ -66,5 +67,5 @@ export async function uploadChatImageAsset(input) {
         mimeType: "image/webp",
         filename: "image.webp",
     });
-    return { ...asset, size: body.byteLength };
+    return { ...asset, size: body.byteLength, width, height };
 }

package/dist/board-export.js

@@ -9,7 +9,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { tmpdir } from "node:os";
 const execFile = promisify(execFileCallback);
-import { parseBoardMediaSource } from "@neta-art/cohub/board";
+import { boardMediaNaturalSize, parseBoardMediaSource } from "@neta-art/cohub/board";
 import { imageVariantUrl, MEDIA_VARIANT_MAX, mediaVariantSize, videoFrameUrl } from "@neta-art/cohub/media";
 import { hasBoardScripts, boardAssetKey, boardAssetKeySource, boardDocumentAt, boardRenderTheme, boardTextureEdge, boardTexturePixels, createBoardRenderSampler, buildBoardScene, createNodeBoardRenderer, createNodeBoardScriptHost, exportBoardImageBytes, parseBoardDocument, planBoardExport, prepareBoardExport, selectBoardExportAssets, } from "./board-kernel.js";
 import { settleBoardDocument } from "./board-media.js";
@@ -135,12 +135,10 @@ async function fetchBoardPicture(client, spaceId, source, item, edge) {
     const url = source.kind === "url"
         ? source.value
         : video || variantEdge
-            ? await client.space(spaceId).files.resolveUrl(source.value, { purpose: "playback" }).catch(() => null)
+            ? (await client.space(spaceId).files.resolve(source.value, { purpose: "playback" }).catch(() => null))?.url
             : null;
     if (video) {
-        const { naturalWidth: w, naturalHeight: h } = (item.type === "video" && item.props.snapshot) || {};
-        const width = w && h ? Math.min(w, (edge * w) / Math.max(w, h)) : edge;
-        const frame = url && videoFrameUrl(url, mediaVariantSize(width));
+        const frame = url && videoFrameUrl(url, mediaVariantSize(edge), { natural: boardMediaNaturalSize(item) });
         return frame ? downloadPublicImage(frame) : null;
     }
     const variant = url && variantEdge && imageVariantUrl(url, variantEdge);
@@ -309,13 +307,12 @@ export async function runBoardExport(options) {
         const warnings = [];
         const textures = textureCache.textures;
         let omittedKeys = new Set();
-        const declaredBackground = document.board.background;
-        if (options.withImages &&
-            options.background === "paper" &&
-            declaredBackground.kind === "image" &&
-            declaredBackground.imageUrl) {
+        const backgroundSource = document.board.background.image && parseBoardMediaSource(document.board.background.image.src);
+        if (options.withImages && options.background === "paper" && backgroundSource) {
             try {
-                const { bytes, mimeType } = await downloadPublicImage(declaredBackground.imageUrl);
+                const { bytes, mimeType } = backgroundSource.kind === "url"
+                    ? await downloadPublicImage(backgroundSource.value)
+                    : await readSpaceFileBytes(createClient(), options.spaceId, backgroundSource.value);
                 backgroundTexture = await renderer.decodeImage(bytes, mimeType);
             }
             catch (error) {
@@ -333,9 +330,6 @@ export async function runBoardExport(options) {
                 },
             });
         const host = scriptHost;
-        const backgroundImage = backgroundTexture
-            ? { texture: backgroundTexture, fit: declaredBackground.fit ?? "cover", position: "center", opacity: declaredBackground.opacity ?? 1 }
-            : undefined;
         const assetKey = (item) => {
             const key = boardExportAssetKey(item);
             return key && omittedKeys.has(key) ? null : key;
@@ -389,7 +383,7 @@ export async function runBoardExport(options) {
                 background: options.background,
                 textures,
                 scripts: scriptHost ?? undefined,
-                backgroundImage,
+                backgroundTexture,
                 assetKey,
                 format: options.format,
                 quality: options.quality,

package/dist/board-kernel.js

@@ -6281,27 +6281,28 @@ const BOARD_ENTER_PRESETS$1 = [
 	"deal"
 ];
 const BoardBackgroundSchema$1 = object({
-	kind: _enum([
-		"solid",
-		"dots",
-		"grid",
-		"image"
-	]).default("dots"),
 	color: BoardColorSchema$1.optional(),
-	imageUrl: string().url().max(4096).optional().describe("Background image for kind image."),
-	fit: _enum([
-		"cover",
-		"contain",
-		"repeat"
-	]).optional(),
-	opacity: ratio$1.optional()
-}).strict();
+	pattern: _enum([
+		"none",
+		"dots",
+		"grid"
+	]).optional().describe("Spaced by grid.size; omit to follow the theme."),
+	image: object({
+		src: BoardMediaSourceSchema$1,
+		fit: _enum([
+			"cover",
+			"contain",
+			"repeat"
+		]).default("cover").describe("cover and contain fill the view; repeat tiles the Board at one board unit per image pixel."),
+		opacity: ratio$1.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 BoardSettingsSchema$1 = object({
 	title: string().min(1).max(255).optional(),
-	background: BoardBackgroundSchema$1.default({ kind: "dots" }),
+	background: BoardBackgroundSchema$1.default({}),
 	grid: object({
-		visible: boolean().default(false).describe("Show the grid overlay."),
-		size: finite$1.min(4).max(512).default(24)
+		size: finite$1.min(4).max(512).default(24).describe("Pattern spacing and snap step, in board units."),
+		snap: boolean().default(false).describe("Snap moved and resized items to the grid.")
 	}).strict().optional(),
 	enter: object({
 		preset: _enum(BOARD_ENTER_PRESETS$1),
@@ -7455,10 +7456,14 @@ object({
 	items: array(string().min(1)).max(5e4).optional(),
 	animations: array(string().min(1)).max(1e4).optional(),
 	limit: number$1().int().min(1).max(5e4).optional(),
-	cursor: string().min(1).optional()
+	cursor: string().min(1).optional(),
+	since: number$1().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"
 });
 object({
 	patch: BoardPatchSchema$1,
@@ -9305,57 +9310,7 @@ function createStrokeRibbonBuilder(size) {
 }
 //#endregion
 //#region ../protocol/src/core/media.ts
-const MEDIA_HOSTS = /* @__PURE__ */ new Map([
-	["router-files.neta.art", {
-		transform: "oss",
-		metaHeaders: true
-	}],
-	["oss.talesofai.com", { transform: "oss" }],
-	["public.cohub.live", { transform: "oss" }],
-	["public.cohub.run", { transform: "oss" }],
-	["sessions.cohub.live", { transform: "oss" }],
-	["works.cohub.live", { transform: "oss" }],
-	["works.cohub.run", { transform: "oss" }],
-	["cca.neta.art", { transform: "cloudflare" }]
-]);
-const parseHttpsUrl = (url) => {
-	if (!/^https:\/\//i.test(url)) return null;
-	try {
-		return new URL(url);
-	} catch {
-		return null;
-	}
-};
-function mediaHost(url) {
-	const parsed = parseHttpsUrl(url);
-	return parsed ? MEDIA_HOSTS.get(parsed.hostname) : void 0;
-}
-const OSS_PROCESS_PATTERN = /[?&]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_PATTERN.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}`;
-}
-const { maxEdge, quality } = {
-	maxEdge: 1280,
-	quality: 75
-};
-`${maxEdge}${maxEdge}${quality}`;
-`${maxEdge}${maxEdge}${quality}`;
-//#endregion
-//#region ../sdk/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.
-*/
-/** Fixed variant widths keep CDN cache hits high; pick with `mediaVariantSize`. */
+/** Fixed variant edges keep CDN cache hits high; pick one with `mediaVariantSize`. */
 const MEDIA_VARIANT_SIZES = [
 	192,
 	384,
@@ -9366,15 +9321,7 @@ const MEDIA_VARIANT_SIZES = [
 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 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`);
-}
+Number.POSITIVE_INFINITY;
 //#endregion
 //#region ../sdk/src/board/model/media.ts
 function getMediaResourceTitle(value) {
@@ -9430,9 +9377,10 @@ function taskPreviewKey(item) {
 	const artifact = featuredTaskArtifact(item.props.snapshot.artifacts);
 	const cover = taskArtifactPreviewUrl(artifact);
 	if (cover) return `url:${cover}`;
-	if (artifact?.type !== "video") return null;
-	const frame = videoFrameUrl(artifact.url, 768);
-	return frame ? `url:${frame}` : `video-url:${encodeURIComponent(artifact.url)}`;
+	return artifact?.type === "video" ? stillKey("video", {
+		kind: "url",
+		value: artifact.url
+	}, void 0) : null;
 }
 function boardAssetKey(item) {
 	if (item.type === "task") return taskPreviewKey(item);
@@ -9913,7 +9861,13 @@ const BOARD_THEME_DATA = {
 				label: 15330286
 			}
 		},
-		style: {}
+		style: {},
+		backdrop: { pattern: {
+			kind: "dots",
+			pitch: 24,
+			color: 2566444,
+			size: 2
+		} }
 	},
 	light: {
 		colorScheme: "light",
@@ -9976,7 +9930,13 @@ const BOARD_THEME_DATA = {
 				label: 66050
 			}
 		},
-		style: {}
+		style: {},
+		backdrop: { pattern: {
+			kind: "dots",
+			pitch: 24,
+			color: 15001321,
+			size: 2
+		} }
 	},
 	"solarized-dark": {
 		colorScheme: "dark",
@@ -10039,7 +9999,13 @@ const BOARD_THEME_DATA = {
 				label: 12572374
 			}
 		},
-		style: {}
+		style: {},
+		backdrop: { pattern: {
+			kind: "dots",
+			pitch: 24,
+			color: 1122594,
+			size: 2
+		} }
 	},
 	"solarized-light": {
 		colorScheme: "light",
@@ -10102,7 +10068,13 @@ const BOARD_THEME_DATA = {
 				label: 2110772
 			}
 		},
-		style: {}
+		style: {},
+		backdrop: { pattern: {
+			kind: "dots",
+			pitch: 24,
+			color: 15130570,
+			size: 2
+		} }
 	},
 	"neta-studio": {
 		colorScheme: "dark",
@@ -10252,7 +10224,14 @@ const BOARD_THEME_DATA = {
 			motion: "stepped",
 			font: "\"Figtree Variable\", \"PingFang SC\", \"Noto Sans CJK SC\", \"Microsoft YaHei\", system-ui, sans-serif",
 			frameLabelSize: 16
-		}
+		},
+		backdrop: { pattern: {
+			kind: "dots",
+			pitch: 24,
+			color: 14935011,
+			size: 2,
+			shape: "square"
+		} }
 	},
 	"neta-pixel-dark": {
 		colorScheme: "dark",
@@ -10336,7 +10315,14 @@ const BOARD_THEME_DATA = {
 			motion: "stepped",
 			font: "\"Figtree Variable\", \"PingFang SC\", \"Noto Sans CJK SC\", \"Microsoft YaHei\", system-ui, sans-serif",
 			frameLabelSize: 16
-		}
+		},
+		backdrop: { pattern: {
+			kind: "dots",
+			pitch: 24,
+			color: 3816512,
+			size: 2,
+			shape: "square"
+		} }
 	}
 };
 //#endregion
@@ -33089,6 +33075,288 @@ function boardTextSize(item) {
 	return clampBoardFontSize(item.props.fontSize ?? 24) * scale;
 }
 //#endregion
+//#region ../sdk/src/board/render/backdrop.ts
+const PATTERN_DEFAULTS = {
+	dots: {
+		alpha: .5,
+		size: 2
+	},
+	grid: {
+		alpha: 1,
+		size: 1
+	}
+};
+function resolveBoardBackdrop(settings, theme, purpose = "stage") {
+	const { color, image, pattern } = settings.background;
+	const themed = !(color !== void 0 || image !== void 0) && purpose === "stage" ? theme.backdrop : void 0;
+	return {
+		color: backgroundColor(settings.background.color, theme),
+		image: image ? {
+			src: image.src,
+			fit: image.fit,
+			opacity: image.opacity ?? 1
+		} : themed?.image ?? null,
+		pattern: purpose === "export" || pattern === "none" ? null : pattern ? patternStyle(theme, pattern, settings.grid?.size ?? 24, false) : themed?.pattern ? patternStyle(theme, themed.pattern.kind, themed.pattern.pitch, true) : null
+	};
+}
+function backgroundColor(color, theme) {
+	const value = typeof color === "object" ? color[theme.colorScheme] : color;
+	if (!value) return theme.palette.bg;
+	const token = value.trim().toLowerCase();
+	if (isBoardColorId(token)) return pickBoardColor(theme.colors, token, theme.colorScheme).fill;
+	return parseBoardCssColor(value) ?? theme.palette.bg;
+}
+function patternStyle(theme, kind, pitch, subdivide) {
+	const own = theme.backdrop?.pattern?.kind === kind ? theme.backdrop.pattern : void 0;
+	const defaults = PATTERN_DEFAULTS[kind];
+	return {
+		kind,
+		pitch,
+		color: own?.color ?? (kind === "grid" ? theme.palette.border : theme.palette.muted),
+		alpha: own ? own.alpha ?? 1 : defaults.alpha,
+		size: own?.size ?? defaults.size,
+		shape: own?.shape ?? "round",
+		subdivide
+	};
+}
+const MIN_GAP = 8;
+const FADE = .25;
+function boardPatternLevel(pattern, zoom) {
+	const gap = Math.max(pattern.pitch / 1.25, MIN_GAP);
+	const unit = pattern.pitch * Math.max(zoom, 1e-6);
+	const level = Math.ceil(Math.log2(gap / unit));
+	const pitch = unit * 2 ** (pattern.subdivide ? level : Math.max(0, level));
+	const t = Math.min(1, Math.max(0, (pitch / gap - 1) / FADE));
+	return {
+		pitch,
+		fade: t * t * (3 - 2 * t)
+	};
+}
+//#endregion
+//#region ../sdk/src/board/render/backdrop-layer.ts
+const VERTEX = `
+in vec2 aPosition;
+out vec2 vPosition;
+
+uniform mat3 uProjectionMatrix;
+uniform mat3 uWorldTransformMatrix;
+uniform mat3 uTransformMatrix;
+
+void main() {
+	mat3 mvp = uProjectionMatrix * uWorldTransformMatrix * uTransformMatrix;
+	gl_Position = vec4((mvp * vec3(aPosition, 1.0)).xy, 0.0, 1.0);
+	vPosition = aPosition;
+}
+`;
+const FRAGMENT = `
+in vec2 vPosition;
+out vec4 finalColor;
+
+uniform float uDensity;
+uniform vec2 uOrigin;
+uniform float uPitch;
+uniform float uFade;
+uniform float uSize;
+uniform float uSquare;
+uniform float uLines;
+uniform vec4 uInk;
+
+vec2 snap(vec2 center) {
+	return mod(uSize, 2.0) == 1.0 ? floor(center) + 0.5 : floor(center + 0.5);
+}
+
+float coverage(vec2 p, float pitch) {
+	vec2 d = abs(p - snap(uOrigin + floor((p - uOrigin) / pitch + 0.5) * pitch));
+	float radius = uSize * 0.5;
+	if (uLines > 0.5) return min(d.x, d.y) < radius ? 1.0 : 0.0;
+	if (uSquare > 0.5) return max(d.x, d.y) < radius ? 1.0 : 0.0;
+	float edge = 0.5 * uDensity;
+	return clamp((radius + edge - length(d)) / edge, 0.0, 1.0);
+}
+
+void main() {
+	vec2 p = vPosition * uDensity;
+	float alpha = uInk.a * max(coverage(p, uPitch * 2.0), coverage(p, uPitch) * uFade);
+	finalColor = vec4(uInk.rgb * alpha, alpha);
+}
+`;
+function wrap(value, period) {
+	return (value % period + period) % period;
+}
+function createPatternMesh() {
+	const positions = /* @__PURE__ */ new Float32Array(8);
+	const geometry = new Geometry({
+		attributes: { aPosition: {
+			buffer: positions,
+			format: "float32x2"
+		} },
+		indexBuffer: new Uint32Array([
+			0,
+			1,
+			2,
+			0,
+			2,
+			3
+		])
+	});
+	const uniforms = new UniformGroup({
+		uDensity: {
+			value: 1,
+			type: "f32"
+		},
+		uOrigin: {
+			value: /* @__PURE__ */ new Float32Array(2),
+			type: "vec2<f32>"
+		},
+		uPitch: {
+			value: 1,
+			type: "f32"
+		},
+		uFade: {
+			value: 0,
+			type: "f32"
+		},
+		uSize: {
+			value: 1,
+			type: "f32"
+		},
+		uSquare: {
+			value: 0,
+			type: "f32"
+		},
+		uLines: {
+			value: 0,
+			type: "f32"
+		},
+		uInk: {
+			value: /* @__PURE__ */ new Float32Array(4),
+			type: "vec4<f32>"
+		}
+	});
+	const shader = Shader.from({
+		gl: {
+			name: "board-backdrop-pattern",
+			vertex: VERTEX,
+			fragment: FRAGMENT,
+			preferredFragmentPrecision: "highp"
+		},
+		resources: { patternUniforms: uniforms }
+	});
+	const mesh = new Mesh({
+		geometry,
+		shader,
+		label: "board-backdrop-pattern"
+	});
+	let width = 0;
+	let height = 0;
+	return {
+		mesh,
+		sync(pattern, view) {
+			if (view.width !== width || view.height !== height) {
+				width = view.width;
+				height = view.height;
+				positions.set([
+					0,
+					0,
+					width,
+					0,
+					width,
+					height,
+					0,
+					height
+				]);
+				geometry.getBuffer("aPosition").update();
+			}
+			const level = boardPatternLevel(pattern, view.zoom);
+			const pitch = level.pitch * view.density;
+			const values = uniforms.uniforms;
+			values.uDensity = view.density;
+			values.uOrigin[0] = wrap(view.x * view.density, pitch * 2);
+			values.uOrigin[1] = wrap(view.y * view.density, pitch * 2);
+			values.uPitch = pitch;
+			values.uFade = level.fade;
+			values.uSize = Math.max(1, Math.round(pattern.size * view.density));
+			values.uSquare = pattern.shape === "square" ? 1 : 0;
+			values.uLines = pattern.kind === "grid" ? 1 : 0;
+			values.uInk[0] = (pattern.color >> 16 & 255) / 255;
+			values.uInk[1] = (pattern.color >> 8 & 255) / 255;
+			values.uInk[2] = (pattern.color & 255) / 255;
+			values.uInk[3] = pattern.alpha;
+		},
+		destroy() {
+			mesh.destroy();
+			geometry.destroy();
+			shader.destroy();
+		}
+	};
+}
+function placeImage(parts, image, texture, view, alpha) {
+	if (image.fit === "repeat") {
+		if (parts.picture) parts.picture.visible = false;
+		parts.tiles ??= parts.container.addChildAt(new TilingSprite({
+			texture,
+			label: "board-backdrop-tiles"
+		}), 0);
+		const tiles = parts.tiles;
+		const tileWidth = (image.tile?.width ?? texture.width) * view.zoom;
+		const tileHeight = (image.tile?.height ?? texture.height) * view.zoom;
+		tiles.texture = texture;
+		tiles.visible = true;
+		tiles.alpha = alpha;
+		tiles.width = view.width;
+		tiles.height = view.height;
+		tiles.tileScale.set(tileWidth / texture.width, tileHeight / texture.height);
+		tiles.tilePosition.set(wrap(view.x, tileWidth), wrap(view.y, tileHeight));
+		return;
+	}
+	if (parts.tiles) parts.tiles.visible = false;
+	parts.picture ??= parts.container.addChildAt(new Sprite({
+		texture,
+		label: "board-backdrop-picture"
+	}), 0);
+	const picture = parts.picture;
+	const scale = (image.fit === "cover" ? Math.max : Math.min)(view.width / texture.width, view.height / texture.height);
+	picture.texture = texture;
+	picture.visible = true;
+	picture.alpha = alpha;
+	picture.width = texture.width * scale;
+	picture.height = texture.height * scale;
+	picture.position.set((view.width - picture.width) / 2, (view.height - picture.height) / 2);
+}
+function createBoardBackdropLayer(options) {
+	const container = new Container({ label: "board-backdrop" });
+	const parts = {
+		tiles: null,
+		picture: null,
+		container
+	};
+	let pattern = null;
+	return {
+		container,
+		sync(backdrop, view, texture, imageAlpha = 1) {
+			if (backdrop.image && texture) placeImage(parts, backdrop.image, texture, view, backdrop.image.opacity * imageAlpha);
+			else {
+				if (parts.tiles) parts.tiles.visible = false;
+				if (parts.picture) parts.picture.visible = false;
+			}
+			const shown = options.patterns && backdrop.pattern !== null;
+			if (shown && backdrop.pattern) {
+				if (!pattern) {
+					pattern = createPatternMesh();
+					container.addChild(pattern.mesh);
+				}
+				pattern.sync(backdrop.pattern, view);
+			}
+			if (pattern) pattern.mesh.visible = shown;
+		},
+		destroy() {
+			pattern?.destroy();
+			pattern = null;
+			container.destroy({ children: true });
+		}
+	};
+}
+//#endregion
 //#region ../sdk/src/board/render/text-fit.ts
 function fitTextToLines(text, value, maxLines, wrapWidth) {
 	text.style.wordWrap = false;
@@ -36929,27 +37197,28 @@ const BOARD_ENTER_PRESETS = [
 	"deal"
 ];
 const BoardBackgroundSchema = object({
-	kind: _enum([
-		"solid",
-		"dots",
-		"grid",
-		"image"
-	]).default("dots"),
 	color: BoardColorSchema.optional(),
-	imageUrl: string().url().max(4096).optional().describe("Background image for kind image."),
-	fit: _enum([
-		"cover",
-		"contain",
-		"repeat"
-	]).optional(),
-	opacity: ratio.optional()
-}).strict();
+	pattern: _enum([
+		"none",
+		"dots",
+		"grid"
+	]).optional().describe("Spaced by grid.size; omit to follow the theme."),
+	image: object({
+		src: BoardMediaSourceSchema,
+		fit: _enum([
+			"cover",
+			"contain",
+			"repeat"
+		]).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.");
 object({
 	title: string().min(1).max(255).optional(),
-	background: BoardBackgroundSchema.default({ kind: "dots" }),
+	background: BoardBackgroundSchema.default({}),
 	grid: object({
-		visible: 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: boolean().default(false).describe("Snap moved and resized items to the grid.")
 	}).strict().optional(),
 	enter: object({
 		preset: _enum(BOARD_ENTER_PRESETS),
@@ -37349,12 +37618,14 @@ function resolveBoardRenderStyle(mode, style) {
 //#region ../sdk/src/board/render/theme.ts
 /** A built-in Cohub theme as the app draws it; spread it into export or sampler options. */
 function boardRenderTheme(id) {
-	const { colorScheme, palette, colors, style } = BOARD_THEME_DATA[id];
+	const data = BOARD_THEME_DATA[id];
+	const { colorScheme, palette, colors, style } = data;
 	return {
 		colorScheme,
 		palette: { ...palette },
 		colors: Object.fromEntries(Object.entries(colors).map(([key, value]) => [key, { ...value }])),
-		style: resolveBoardRenderStyle(colorScheme, style)
+		style: resolveBoardRenderStyle(colorScheme, style),
+		..."backdrop" in data ? { backdrop: structuredClone(data.backdrop) } : {}
 	};
 }
 //#endregion
@@ -37405,31 +37676,23 @@ function createBoardExportScene(input) {
 	const root = new Container({ label: "board-export-root" });
 	const outputWidth = input.world.width * input.scale;
 	const outputHeight = input.world.height * input.scale;
-	if (input.background != null) root.addChild(new Graphics().rect(0, 0, outputWidth, outputHeight).fill({
-		color: input.background,
-		alpha: 1
-	}));
-	if (input.backgroundImage) {
-		const { texture, fit, position, opacity } = input.backgroundImage;
-		if (fit === "repeat") root.addChild(new TilingSprite({
-			texture,
+	let backdrop = null;
+	if (input.backdrop) {
+		root.addChild(new Graphics().rect(0, 0, outputWidth, outputHeight).fill({
+			color: input.backdrop.color,
+			alpha: 1
+		}));
+		backdrop = createBoardBackdropLayer({ patterns: false });
+		const view = {
+			x: -input.world.x * input.scale,
+			y: -input.world.y * input.scale,
+			zoom: input.scale,
 			width: outputWidth,
 			height: outputHeight,
-			alpha: opacity
-		}));
-		else {
-			const sprite = new Sprite({
-				texture,
-				alpha: opacity
-			});
-			const scale = fit === "cover" ? Math.max(outputWidth / texture.width, outputHeight / texture.height) : Math.min(outputWidth / texture.width, outputHeight / texture.height);
-			sprite.width = texture.width * scale;
-			sprite.height = texture.height * scale;
-			const x = position === "left" ? 0 : position === "right" ? outputWidth - sprite.width : (outputWidth - sprite.width) / 2;
-			const y = position === "top" ? 0 : position === "bottom" ? outputHeight - sprite.height : (outputHeight - sprite.height) / 2;
-			sprite.position.set(x, y);
-			root.addChild(sprite);
-		}
+			density: 1
+		};
+		backdrop.sync(input.backdrop, view, input.backdropTexture ?? null);
+		root.addChild(backdrop.container);
 	}
 	const world = new Container({
 		isRenderGroup: true,
@@ -37468,17 +37731,21 @@ function createBoardExportScene(input) {
 	return {
 		root,
 		missingImageKeys: [...missing],
-		destroy: () => root.destroy({ children: true })
+		destroy: () => {
+			backdrop?.destroy();
+			root.destroy({ children: true });
+		}
 	};
 }
 //#endregion
 //#region ../sdk/src/board/export/index.ts
-function resolveBackground(background, palette, document, colorScheme) {
-	if (background === "transparent") return null;
-	if (typeof background === "number") return background;
-	const declared = document.board.background.color;
-	const css = typeof declared === "object" ? declared[colorScheme] : declared;
-	return css ? parseBoardCssColor(css) ?? palette.bg : palette.bg;
+function resolveBackdrop(options, document, theme) {
+	if (options.background === "transparent") return null;
+	const backdrop = resolveBoardBackdrop(document.board, theme, "export");
+	return typeof options.background === "number" ? {
+		...backdrop,
+		color: options.background
+	} : backdrop;
 }
 function prepareBoardExport(input, options = {}) {
 	ensureBoardTextMeasurement();
@@ -37545,8 +37812,12 @@ function renderBoardExport(renderer, input, options = {}) {
 		scripts: options.scripts,
 		assetKey: options.assetKey,
 		renderers: options.renderers,
-		background: resolveBackground(options.background, palette, document, colorScheme),
-		backgroundImage: options.backgroundImage
+		backdrop: resolveBackdrop(options, document, {
+			palette,
+			colors: options.colors ?? buildFallbackShapeColors(colorScheme),
+			colorScheme
+		}),
+		backdropTexture: options.backgroundTexture
 	});
 	try {
 		const texture = renderer.textureGenerator.generateTexture({
@@ -38029,15 +38300,12 @@ const MIME = {
 	webp: "image/webp"
 };
 function exportBoardImageBytes(renderer, document, options = {}) {
-	const { format = "png", quality = .92, textures, scripts, backgroundImage, ...rest } = options;
+	const { format = "png", quality = .92, textures, scripts, backgroundTexture, ...rest } = options;
 	const result = renderBoardExport(renderer.renderer, document, {
 		...rest,
 		...scripts ? { scripts } : {},
 		...textures ? { textures } : {},
-		...backgroundImage ? { backgroundImage: {
-			...backgroundImage,
-			texture: backgroundImage.texture
-		} } : {}
+		...backgroundTexture ? { backgroundTexture } : {}
 	});
 	if (!result) return null;
 	const canvas = result.canvas;

package/dist/board-media.js

@@ -1,37 +1,17 @@
-import { execFile } from "node:child_process";
 import { resolve } from "node:path";
-import { promisify } from "node:util";
 import { diffMergePatch, mergePatch, parseBoardItem, settleBoardMediaSizes, } from "@neta-art/cohub/board";
 import { createClient } from "./client.js";
+import { localMediaFacts } from "./local-media.js";
 import { WORKSPACE_ROOT } from "./space-files/operands.js";
-const run = promisify(execFile);
 const isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
-const oriented = (width, height, turned) => width > 0 && height > 0 ? (turned ? { width: height, height: width } : { width, height }) : null;
-async function localMediaSize(file, type, signal) {
-    try {
-        if (type === "image") {
-            const { default: sharp } = await import("sharp");
-            const { width = 0, height = 0, orientation = 1 } = await sharp(file).metadata();
-            return oriented(width, height, orientation >= 5);
-        }
-        const { stdout } = await run("ffprobe", [
-            "-v", "error", "-select_streams", "v:0",
-            "-show_entries", "stream=width,height:stream_side_data=rotation", "-of", "json", file,
-        ], { signal, timeout: 5_000 });
-        const stream = JSON.parse(stdout).streams?.[0];
-        const rotation = stream?.side_data_list?.find((data) => data.rotation !== undefined)?.rotation ?? 0;
-        return oriented(stream?.width ?? 0, stream?.height ?? 0, Math.abs(rotation) % 180 === 90);
-    }
-    catch {
-        return null;
-    }
-}
 export function boardMediaFileResolver(spaceId) {
     const local = process.env.COHUB_SPACE_ID === spaceId;
     return async (path, type, signal) => {
         const file = resolve(WORKSPACE_ROOT, path);
-        const size = local && file.startsWith(`${WORKSPACE_ROOT}/`) ? await localMediaSize(file, type, signal) : null;
-        return size ?? createClient().space(spaceId).files.resolveUrl(path, { purpose: "playback", signal }).catch(() => null);
+        const facts = local && file.startsWith(`${WORKSPACE_ROOT}/`) ? await localMediaFacts(file, type, signal) : null;
+        const resolved = facts ? null : await createClient().space(spaceId).files.resolve(path, { purpose: "playback", signal }).catch(() => null);
+        const size = facts ?? resolved?.media;
+        return size ? { width: size.width, height: size.height } : (resolved?.url ?? null);
     };
 }
 export async function settleBoardDocument(spaceId, document) {

package/dist/commands/boards.js

@@ -361,10 +361,12 @@ Times are milliseconds; 500ms, 12.5s and 2m also work on the command line.`);
         .option("--animations <ids>", "Only these animations")
         .option("--limit <n>", "Page size for items")
         .option("--cursor <cursor>", "Continue from a previous page's next")
+        .option("--since <version>", "Only the changes after this version; the whole Board when they are unavailable")
         .addHelpText("after", `
   cohub boards get plan.board
   cohub boards get plan.board --within s2
-  cohub boards get plan.board --only board`)
+  cohub boards get plan.board --only board
+  cohub boards get plan.board --since 12`)
         .action(async (target, options) => {
         try {
             const only = list(options.only);
@@ -379,6 +381,7 @@ Times are milliseconds; 500ms, 12.5s and 2m also work on the command line.`);
                 ...(list(options.animations) ? { animations: list(options.animations) } : {}),
                 ...(options.limit ? { limit: parseNumber(options.limit, "--limit", { min: 1, integer: true }) } : {}),
                 ...(options.cursor ? { cursor: options.cursor } : {}),
+                ...(options.since ? { since: parseNumber(options.since, "--since", { min: 0, integer: true }) } : {}),
             };
             const result = await (await boardClient(boards, target)).get(input);
             if (!sections)

package/dist/commands/public.js

@@ -2,8 +2,10 @@ import { randomUUID } from "node:crypto";
 import { lstat, readdir } from "node:fs/promises";
 import { basename, relative, resolve } from "node:path";
 import { isTextMime, mimeTypeForPath, } from "@neta-art/cohub";
+import { mediaFacts } from "@neta-art/cohub/media";
 import { createClient } from "../client.js";
 import { HttpPutError, putLocalFile } from "../http-put.js";
+import { localMediaFacts } from "../local-media.js";
 import { error, handleHttp, json as outJson, jsonRequested } from "../output.js";
 import { resolveSpace } from "../space.js";
 const UPLOAD_CONCURRENCY = 4;
@@ -136,6 +138,20 @@ async function putPublicFile(file, plan, fetchImpl) {
         throw error;
     }
 }
+async function publicMediaFacts(files) {
+    const facts = new Map();
+    const media = files.flatMap((file) => {
+        const type = file.mimeType.split("/")[0];
+        return type === "image" || type === "video" ? [{ file, type: type }] : [];
+    });
+    await mapSettledWithConcurrency(media, UPLOAD_CONCURRENCY, async ({ file, type }) => {
+        // Facts only help previews; out-of-range ones are dropped rather than failing the upload.
+        const found = mediaFacts(await localMediaFacts(file.localPath, type));
+        if (found)
+            facts.set(file.id, found);
+    });
+    return facts;
+}
 function uploadFailure(errors) {
     if (errors.length === 1)
         return errors[0];
@@ -155,6 +171,7 @@ async function uploadPublic(command, source, destination, opts, deps) {
     const spaceId = await resolveSpace(command, { home: true });
     try {
         const upload = await collectPublicUpload(source, destination);
+        const media = await publicMediaFacts(upload.files);
         const plan = await client.space(spaceId).publicFiles.createUpload({
             overwrite: Boolean(opts.overwrite),
             entries: upload.files.map((file) => ({
@@ -162,6 +179,7 @@ async function uploadPublic(command, source, destination, opts, deps) {
                 relativePath: file.publicPath,
                 size: file.size,
                 mimeType: file.mimeType,
+                ...(media.has(file.id) ? { media: media.get(file.id) } : {}),
             })),
         });
         if (opts.overwrite && !jsonRequested(opts)) {

package/dist/commands/spaces.js

@@ -222,6 +222,8 @@ async function sendPrompt(command, words, opts) {
                         filename: basename(path),
                         mediaType: "image/webp",
                         size: asset.size,
+                        width: asset.width,
+                        height: asset.height,
                         objectKey: asset.objectKey,
                     },
                 };

package/dist/local-media.d.ts

@@ -0,0 +1,2 @@
+import type { MediaFacts } from "@neta-art/cohub/media";
+export declare function localMediaFacts(file: string, type: "image" | "video", signal?: AbortSignal): Promise<MediaFacts | null>;

package/dist/local-media.js

@@ -0,0 +1,30 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const run = promisify(execFile);
+const oriented = (width, height, turned) => (turned ? { width: height, height: width } : { width, height });
+export async function localMediaFacts(file, type, signal) {
+    try {
+        if (type === "image") {
+            const { default: sharp } = await import("sharp");
+            const { width = 0, height = 0, orientation = 1 } = await sharp(file).metadata();
+            return width > 0 && height > 0 ? oriented(width, height, orientation >= 5) : null;
+        }
+        const { stdout } = await run("ffprobe", [
+            "-v", "error", "-select_streams", "v:0",
+            "-show_entries", "stream=width,height:stream_side_data=rotation:format=duration", "-of", "json", file,
+        ], { signal, timeout: 5_000 });
+        const { streams, format } = JSON.parse(stdout);
+        const stream = streams?.[0];
+        if (!stream?.width || !stream.height)
+            return null;
+        const rotation = stream.side_data_list?.find((data) => data.rotation !== undefined)?.rotation ?? 0;
+        const durationMs = Math.round(Number(format?.duration) * 1000);
+        return {
+            ...oriented(stream.width, stream.height, Math.abs(rotation) % 180 === 90),
+            ...(durationMs > 0 ? { durationMs } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neta-art/cohub-cli",
-  "version": "10.12.1",
+  "version": "10.12.2",
   "description": "CLI for Cohub — spaces, sessions, and agent collaboration.",
   "type": "module",
   "engines": {
@@ -18,7 +18,7 @@
     "NOTICE"
   ],
   "dependencies": {
-    "@neta-art/cohub": "12.6.0",
+    "@neta-art/cohub": "13.0.0",
     "@neta-art/generation": "^0.1.40",
     "commander": "^15.0.0",
     "sharp": "^0.35.4",