@neta-art/cohub 12.2.0 → 12.4.0

package/dist/chunks/http.js

@@ -1,6 +1,768 @@
 import { S as getRealtimeSpaceRoom, c as HttpError, l as HttpTransport, s as isHttpErrorCode, x as getRealtimeBoardRoom, z as isUuid } from "./http-error.js";
 import { l as resolveExecutionToken, o as resolveApiBaseUrl } from "./environment.js";
 import { z } from "zod";
+//#region ../protocol/dist/board-constants.js
+const BOARD_ARROW_STROKE_SIZE = 2.5;
+const BOARD_DEFAULT_ITEM_SIZE = {
+	width: 240,
+	height: 160
+};
+const BOARD_DEFAULT_SIZES = {
+	frame: {
+		width: 480,
+		height: 320
+	},
+	shape: {
+		width: 200,
+		height: 140
+	},
+	image: {
+		width: 480,
+		height: 270
+	},
+	video: {
+		width: 480,
+		height: 270
+	},
+	audio: {
+		width: 320,
+		height: 112
+	},
+	file: {
+		width: 260,
+		height: 132
+	},
+	task: {
+		width: 480,
+		height: 270
+	},
+	effect: {
+		width: 240,
+		height: 240
+	},
+	custom: {
+		width: 480,
+		height: 320
+	}
+};
+function boardDefaultSize(type) {
+	return { ...Object.hasOwn(BOARD_DEFAULT_SIZES, type) ? BOARD_DEFAULT_SIZES[type] : BOARD_DEFAULT_ITEM_SIZE };
+}
+//#endregion
+//#region ../protocol/dist/board-url.js
+const BOARD_REMOTE_URL_MAX_LENGTH = 4096;
+function parseIpv4(host) {
+	const parts = host.split(".").map(Number);
+	return parts.length === 4 && parts.every((part) => Number.isInteger(part) && part >= 0 && part <= 255) ? parts : null;
+}
+function isBlockedIpv4(host) {
+	const parts = parseIpv4(host);
+	if (!parts) return false;
+	const [first, second, third] = parts;
+	if (first === 0 || first === 10 || first === 127) return true;
+	if (first === 100 && second >= 64 && second <= 127) return true;
+	if (first === 169 && second === 254) return true;
+	if (first === 172 && second >= 16 && second <= 31) return true;
+	if (first === 192 && second === 168) return true;
+	if (first === 192 && second === 0 && (third === 0 || third === 2)) return true;
+	if (first === 192 && second === 88 && third === 99) return true;
+	if (first === 198 && (second === 18 || second === 19)) return true;
+	if (first === 198 && second === 51 && third === 100) return true;
+	if (first === 203 && second === 0 && third === 113) return true;
+	return first >= 224;
+}
+function expandIpv6(host) {
+	const [head, tail, extra] = host.toLowerCase().split("::");
+	if (extra !== void 0) return null;
+	const headParts = head ? head.split(":").filter(Boolean) : [];
+	const tailParts = tail ? tail.split(":").filter(Boolean) : [];
+	const missing = 8 - headParts.length - tailParts.length;
+	if (missing < 0 || tail === void 0 && missing !== 0) return null;
+	const parts = [
+		...headParts,
+		...Array.from({ length: missing }, () => "0"),
+		...tailParts
+	];
+	if (parts.length !== 8 || parts.some((part) => !/^[0-9a-f]{1,4}$/.test(part))) return null;
+	return parts.map((part) => part.padStart(4, "0"));
+}
+function isBlockedIpv6(host) {
+	const parts = expandIpv6(host);
+	if (!parts) return true;
+	if (parts.every((part) => part === "0000")) return true;
+	if (parts.slice(0, 7).every((part) => part === "0000") && parts[7] === "0001") return true;
+	if (parts.slice(0, 5).every((part) => part === "0000") && parts[5] === "ffff") {
+		const high = Number.parseInt(parts[6] ?? "0", 16);
+		const low = Number.parseInt(parts[7] ?? "0", 16);
+		return isBlockedIpv4(`${high >> 8}.${high & 255}.${low >> 8}.${low & 255}`);
+	}
+	if (parts.slice(0, 6).every((part) => part === "0000")) return true;
+	const first = Number.parseInt(parts[0] ?? "0", 16);
+	if ((first & 65024) === 64512) return true;
+	if ((first & 65472) === 65152 || (first & 65472) === 65216) return true;
+	if ((first & 65280) === 65280) return true;
+	return parts[0] === "2001" && parts[1] === "0db8";
+}
+function isPublicBoardRemoteAddress(value) {
+	const address = value.toLowerCase().replace(/^\[|\]$/g, "").replace(/\.$/, "");
+	if (parseIpv4(address)) return !isBlockedIpv4(address);
+	return address.includes(":") && !isBlockedIpv6(address);
+}
+function isBlockedHost(hostname) {
+	const host = hostname.toLowerCase().replace(/^\[|\]$/g, "").replace(/\.$/, "");
+	if (host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local") || host.endsWith(".internal")) return true;
+	if (parseIpv4(host) || host.includes(":")) return !isPublicBoardRemoteAddress(host);
+	return false;
+}
+/**
+* Normalize a browser-loadable public HTTP(S) URL. This blocks explicit local
+* addresses; any future server-side fetcher must additionally validate DNS
+* resolution to defend against rebinding.
+*/
+function normalizeBoardRemoteUrl(value) {
+	if (typeof value !== "string") return void 0;
+	const input = value.trim();
+	if (!input || input.length > 4096) return void 0;
+	try {
+		const url = new URL(input);
+		if (url.protocol !== "https:" && url.protocol !== "http:") return void 0;
+		if (url.username || url.password || isBlockedHost(url.hostname)) return;
+		const normalized = url.toString();
+		return normalized.length <= 4096 ? normalized : void 0;
+	} catch {
+		return;
+	}
+}
+z.string().max(BOARD_REMOTE_URL_MAX_LENGTH).refine((value) => normalizeBoardRemoteUrl(value) !== void 0, { message: "URL must be a public HTTP(S) URL without credentials" });
+const BOARD_CAMERA_TARGET = "camera";
+const BoardKeySchema = z.string().min(1).max(160).regex(/^[^\s/]+$/, "ids must not contain whitespace or '/'");
+const BoardIdSchema = BoardKeySchema.refine((value) => value !== BOARD_CAMERA_TARGET, "\"camera\" is reserved");
+const finite = z.number().finite();
+const nonNegative = finite.nonnegative();
+const ratio = finite.min(0).max(1);
+const BoardVec2Schema = z.object({
+	x: finite,
+	y: finite
+}).strict();
+const BoardSizeSchema = z.object({
+	width: finite.positive(),
+	height: finite.positive()
+}).strict();
+const BOARD_COLOR_TOKENS = [
+	"brand",
+	"neutral",
+	"black",
+	"white",
+	"blue",
+	"green",
+	"amber",
+	"violet",
+	"rose"
+];
+const CSS_NAMED_COLORS = new Set("transparent aliceblue antiquewhite aqua aquamarine azure beige bisque blanchedalmond blueviolet brown burlywood cadetblue chartreuse chocolate coral cornflowerblue cornsilk crimson cyan darkblue darkcyan darkgoldenrod darkgray darkgreen darkgrey darkkhaki darkmagenta darkolivegreen darkorange darkorchid darkred darksalmon darkseagreen darkslateblue darkslategray darkslategrey darkturquoise darkviolet deeppink deepskyblue dimgray dimgrey dodgerblue firebrick floralwhite forestgreen fuchsia gainsboro ghostwhite gold goldenrod gray grey greenyellow honeydew hotpink indianred indigo ivory khaki lavender lavenderblush lawngreen lemonchiffon lightblue lightcoral lightcyan lightgoldenrodyellow lightgray lightgreen lightgrey lightpink lightsalmon lightseagreen lightskyblue lightslategray lightslategrey lightsteelblue lightyellow lime limegreen linen magenta maroon mediumaquamarine mediumblue mediumorchid mediumpurple mediumseagreen mediumslateblue mediumspringgreen mediumturquoise mediumvioletred midnightblue mintcream mistyrose moccasin navajowhite navy oldlace olive olivedrab orange orangered orchid palegoldenrod palegreen paleturquoise palevioletred papayawhip peachpuff peru pink plum powderblue purple rebeccapurple red rosybrown royalblue saddlebrown salmon sandybrown seagreen seashell sienna silver skyblue slateblue slategray slategrey snow springgreen steelblue tan teal thistle tomato turquoise violet wheat whitesmoke yellow yellowgreen".split(" "));
+function isBoardColorString(value) {
+	const color = value.trim().toLowerCase();
+	return BOARD_COLOR_TOKENS.includes(color) || CSS_NAMED_COLORS.has(color) || /^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/.test(color) || /^(?:rgba?|hsla?|hwb|lab|lch|oklab|oklch|color)\([^()]*\)$/.test(color);
+}
+const colorString = z.string().max(120).refine(isBoardColorString, "expected a palette token or a CSS color");
+const BoardColorSchema = z.union([colorString, z.object({
+	light: colorString,
+	dark: colorString
+}).strict()]).describe("Palette token (follows the theme), CSS color, or { light, dark }.");
+const BoardStyleSchema = z.object({
+	fill: BoardColorSchema.optional(),
+	fillOpacity: ratio.optional().describe("Fill opacity, independent of the item's opacity."),
+	stroke: BoardColorSchema.optional(),
+	strokeWidth: finite.min(0).max(64).optional(),
+	dash: z.enum([
+		"solid",
+		"dashed",
+		"dotted"
+	]).optional(),
+	radius: nonNegative.optional().describe("Corner radius in board units."),
+	trim: ratio.optional().describe("Fraction of the outline drawn; animate 0 → 1 to draw it in.")
+}).strict();
+function isSafeBoardSourcePath(value) {
+	return value.length > 0 && value.length <= 4096 && !value.startsWith("/") && !/^[a-z][a-z\d+.-]*:/i.test(value.trimStart()) && !value.includes("\\") && value.split("/").every((part) => part.length > 0 && part !== "." && part !== "..");
+}
+const srcSchema = z.string().refine(isSafeBoardSourcePath, "src must be a relative Space file path");
+function parseBoardMediaSource(src) {
+	if (isSafeBoardSourcePath(src)) return {
+		kind: "file",
+		value: src
+	};
+	return normalizeBoardRemoteUrl(src) ? {
+		kind: "url",
+		value: src
+	} : null;
+}
+const BoardMediaSourceSchema = z.string().max(4096).refine((src) => parseBoardMediaSource(src) !== null, "src must be a public HTTP(S) URL or relative Space file path").describe("Prefer a public HTTP(S) URL; a Space path relative to the workspace root also works.");
+const BoardScriptSchema = z.object({
+	src: srcSchema.refine((path) => /\.m?js$/.test(path), "script src must be a .js or .mjs module").describe("A .js or .mjs Space file."),
+	params: z.record(z.string(), z.json()).default({}).describe("Values the module reads as params."),
+	targets: z.record(z.string().min(1).max(80), BoardIdSchema).default({}).describe("Named items the module can reach, as ctx.targets."),
+	seed: z.string().min(1).max(160).optional().describe("Seed for ctx.random(); defaults to the item id."),
+	enabled: z.boolean().default(true)
+}).strict().describe("A JavaScript module attached to the item; `cohub boards schema script` lists its API.");
+const itemEnvelope = {
+	script: BoardScriptSchema.optional(),
+	parent: BoardIdSchema.optional().describe("A frame id; position becomes relative to the frame, and the item moves with it."),
+	z: finite.optional().describe("Order among siblings; new items go on top."),
+	position: BoardVec2Schema.default({
+		x: 0,
+		y: 0
+	}),
+	rotation: finite.default(0),
+	scale: z.union([finite, BoardVec2Schema]).default(1),
+	origin: BoardVec2Schema.default({
+		x: .5,
+		y: .5
+	}).describe("Rotation and scale origin as fractions of the size."),
+	opacity: ratio.default(1),
+	style: BoardStyleSchema.default({}),
+	locked: z.boolean().optional(),
+	metadata: z.record(z.string(), z.unknown()).optional()
+};
+const boxed = (size) => ({
+	...itemEnvelope,
+	size: BoardSizeSchema.default({ ...size })
+});
+const unsized = { ...itemEnvelope };
+const fontSize = finite.min(2).max(512);
+const BOARD_TEXT_ALIGNS = [
+	"left",
+	"center",
+	"right"
+];
+const BOARD_SHAPE_GEOMETRIES = [
+	"rectangle",
+	"rounded",
+	"ellipse",
+	"diamond",
+	"triangle",
+	"path"
+];
+const BoardFrameItemSchema = z.object({
+	...boxed(BOARD_DEFAULT_SIZES.frame),
+	type: z.literal("frame"),
+	props: z.object({
+		label: z.string().max(280).default(""),
+		decoration: z.enum(["frame", "none"]).optional().describe("none hides the title, border and background: an invisible group whose tracks move every child."),
+		clip: z.boolean().default(true).describe("Hide children outside the frame.")
+	}).strict().prefault({})
+}).strict();
+const BoardTextItemSchema = z.object({
+	...unsized,
+	type: z.literal("text"),
+	props: z.object({
+		text: z.string().default(""),
+		fontSize: fontSize.default(24),
+		fontWeight: finite.min(100).max(900).default(500),
+		font: z.string().min(1).max(120).default("sans").describe("sans, serif, mono, or a font family name."),
+		align: z.enum(BOARD_TEXT_ALIGNS).default("left"),
+		lineHeight: finite.min(.5).max(4).default(4 / 3),
+		width: finite.positive().optional().describe("Wrap width; the height follows the text."),
+		reveal: ratio.default(1).describe("Fraction of the text shown; animate 0 → 1 to type it."),
+		caret: z.boolean().default(false).describe("Blink a caret while the text is being revealed.")
+	}).strict().prefault({})
+}).strict();
+const BoardShapeItemSchema = z.object({
+	...boxed(BOARD_DEFAULT_SIZES.shape),
+	type: z.literal("shape"),
+	props: z.object({
+		geometry: z.enum(BOARD_SHAPE_GEOMETRIES).default("rectangle"),
+		path: z.string().min(1).max(2e5).optional().describe("SVG path data for path geometry, fitted to the item size."),
+		text: z.string().default(""),
+		fontSize: fontSize.default(20),
+		align: z.enum(BOARD_TEXT_ALIGNS).default("center")
+	}).strict().refine((props) => props.geometry !== "path" || Boolean(props.path), {
+		message: "path geometry requires props.path",
+		path: ["path"]
+	}).prefault({})
+}).strict();
+const BoardDrawPointSchema = z.object({
+	x: finite,
+	y: finite,
+	p: ratio.default(.5).describe("Pen pressure.")
+}).strict();
+const BoardDrawItemSchema = z.object({
+	...unsized,
+	type: z.literal("draw"),
+	props: z.object({ points: z.array(BoardDrawPointSchema).min(1).max(1e5).describe("Stroke points relative to position; the size follows them.") }).strict()
+}).strict();
+const BoardArrowAnchorSchema = z.union([
+	z.literal("auto"),
+	z.object({
+		side: z.enum([
+			"top",
+			"right",
+			"bottom",
+			"left"
+		]),
+		offset: ratio.default(.5)
+	}).strict(),
+	z.object({
+		x: ratio,
+		y: ratio
+	}).strict()
+]);
+const BoardArrowBindingSchema = z.object({
+	item: BoardIdSchema,
+	anchor: BoardArrowAnchorSchema.default("auto").describe("auto uses the side facing the other end; or a side with an offset, or a point as fractions of the item."),
+	port: z.string().min(1).max(120).optional()
+}).strict();
+const BoardArrowEndSchema = z.union([BoardVec2Schema, BoardArrowBindingSchema]).describe("A point relative to position, or { item } to follow that item.");
+const BOARD_ARROW_ROUTES = [
+	"straight",
+	"curve",
+	"orthogonal"
+];
+const BoardArrowItemSchema = z.object({
+	...unsized,
+	type: z.literal("arrow"),
+	props: z.object({
+		start: BoardArrowEndSchema,
+		end: BoardArrowEndSchema,
+		route: z.enum(BOARD_ARROW_ROUTES).default("straight"),
+		bend: finite.min(-.85).max(.85).default(0).describe("Sideways curve as a fraction of the length; the sign picks the side."),
+		waypoints: z.array(BoardVec2Schema).max(64).default([]).describe("Points the route passes through."),
+		arrowStart: z.boolean().default(false),
+		arrowEnd: z.boolean().default(true),
+		label: z.string().max(280).default(""),
+		fontSize: fontSize.default(14),
+		relation: z.string().max(64).regex(/^[a-z0-9]+(?:[.-][a-z0-9]+)*$/, "relation must be a lowercase slug").optional().describe("What the arrow means, as a slug such as triggers or depends-on.")
+	}).strict()
+}).strict();
+const fileProps = {
+	src: BoardMediaSourceSchema,
+	snapshot: z.object({
+		title: z.string().optional(),
+		mimeType: z.string().optional(),
+		size: nonNegative.optional(),
+		mtimeMs: nonNegative.optional(),
+		naturalWidth: finite.positive().optional(),
+		naturalHeight: finite.positive().optional(),
+		durationMs: nonNegative.optional(),
+		excerpt: z.string().optional(),
+		coverPath: z.string().optional(),
+		coverUrl: z.string().optional()
+	}).strict().describe("Cached facts for an instant preview; filled in when the media loads.").optional()
+};
+const BoardMediaOriginSchema = z.object({
+	taskRunId: z.string().min(1).max(160),
+	artifactId: z.string().min(1).max(240)
+}).strict().describe("The generation run and result this media came from.");
+const mediaProps = {
+	...fileProps,
+	origin: BoardMediaOriginSchema.optional()
+};
+const timedFileProps = {
+	...mediaProps,
+	time: nonNegative.optional().describe("Playback position in milliseconds; animate props.time to play it on a timeline.")
+};
+const BoardCropSchema = z.object({
+	x: ratio,
+	y: ratio,
+	w: ratio,
+	h: ratio
+}).strict().describe("Region shown, as fractions of the image. Without it the whole image fits inside size.");
+const BoardImageItemSchema = z.object({
+	...boxed(BOARD_DEFAULT_SIZES.image),
+	type: z.literal("image"),
+	props: z.object({
+		...mediaProps,
+		crop: BoardCropSchema.optional()
+	}).strict()
+}).strict();
+const BoardVideoItemSchema = z.object({
+	...boxed(BOARD_DEFAULT_SIZES.video),
+	type: z.literal("video"),
+	props: z.object(timedFileProps).strict()
+}).strict();
+const BoardAudioItemSchema = z.object({
+	...boxed(BOARD_DEFAULT_SIZES.audio),
+	type: z.literal("audio"),
+	props: z.object(timedFileProps).strict()
+}).strict();
+const BoardFileItemSchema = z.object({
+	...boxed(BOARD_DEFAULT_SIZES.file),
+	type: z.literal("file"),
+	props: z.object(fileProps).strict()
+}).strict();
+const httpsUrl = z.string().max(4096).url();
+const artifactBase = {
+	id: z.string().min(1).max(240),
+	title: z.string().max(240).optional(),
+	url: httpsUrl,
+	mimeType: z.string().max(160).optional()
+};
+const BoardTaskArtifactSchema = z.discriminatedUnion("type", [
+	z.object({
+		...artifactBase,
+		type: z.literal("image"),
+		naturalWidth: finite.positive().optional(),
+		naturalHeight: finite.positive().optional()
+	}).strict(),
+	z.object({
+		...artifactBase,
+		type: z.literal("video"),
+		previewUrl: httpsUrl.optional(),
+		durationMs: z.number().int().positive().optional(),
+		naturalWidth: finite.positive().optional(),
+		naturalHeight: finite.positive().optional()
+	}).strict(),
+	z.object({
+		...artifactBase,
+		type: z.literal("audio"),
+		previewUrl: httpsUrl.optional(),
+		durationMs: z.number().int().positive().optional()
+	}).strict(),
+	z.object({
+		id: z.string().min(1).max(240),
+		type: z.literal("text"),
+		title: z.string().max(240).optional(),
+		textExcerpt: z.string().min(1).max(480)
+	}).strict()
+]);
+const BoardTaskSnapshotSchema = z.object({
+	taskType: z.string().min(1).max(120),
+	status: z.enum([
+		"pending",
+		"running",
+		"completed",
+		"failed"
+	]),
+	title: z.string().min(1).max(240),
+	model: z.string().max(160).optional(),
+	promptExcerpt: z.string().max(480).optional(),
+	errorExcerpt: z.string().max(240).optional(),
+	artifactCount: z.number().int().nonnegative(),
+	artifacts: z.array(BoardTaskArtifactSchema).max(6).default([]),
+	startedAt: z.string().max(64).optional(),
+	updatedAt: z.string().optional()
+}).strict();
+const BoardTaskItemSchema = z.object({
+	...boxed(BOARD_DEFAULT_SIZES.task),
+	type: z.literal("task"),
+	props: z.object({
+		taskRunId: z.string().min(1).max(160).describe("The generation run shown; the server keeps the card's status and results up to date."),
+		snapshot: BoardTaskSnapshotSchema.describe("Maintained by the server; omit it.")
+	}).strict()
+}).strict();
+const BOARD_EFFECT_KINDS = [
+	"particles",
+	"trail",
+	"impact",
+	"flash",
+	"glow"
+];
+const BoardEffectItemSchema = z.object({
+	...boxed(BOARD_DEFAULT_SIZES.effect),
+	type: z.literal("effect"),
+	props: z.object({
+		kind: z.enum(BOARD_EFFECT_KINDS),
+		rate: nonNegative.max(2e4).default(40),
+		life: finite.positive().max(6e4).default(1200),
+		particleSize: finite.positive().max(512).default(6),
+		speed: nonNegative.max(1e4).default(120),
+		direction: finite.default(-90),
+		spread: finite.min(0).max(360).default(360),
+		gravity: finite.default(0),
+		intensity: nonNegative.max(10).default(1),
+		follow: BoardIdSchema.optional().describe("trail: the item to follow."),
+		seed: z.string().min(1).max(160).optional().describe("Makes procedural motion repeatable.")
+	}).strict()
+}).strict();
+const BoardCustomItemSchema = z.object({
+	...boxed(BOARD_DEFAULT_SIZES.custom),
+	type: z.literal("custom"),
+	script: BoardScriptSchema,
+	props: z.object({}).strict().default({})
+}).strict();
+const BOARD_EXTENSION_TYPE_PATTERN = /^[a-z][a-z0-9]*(?:\.[a-z0-9-]+)+$/;
+const BoardItemPreviewSchema = z.object({
+	title: z.string().max(500).optional(),
+	excerpt: z.string().max(2e3).optional(),
+	cover: BoardMediaSourceSchema.optional().describe("An image for the card."),
+	src: BoardMediaSourceSchema.optional().describe("The file or page the card stands for.")
+}).strict().describe("How a client without this type's renderer shows the card, and what it refers to. The type's own client keeps it current.");
+const BoardExtensionItemSchema = z.object({
+	...boxed(BOARD_DEFAULT_ITEM_SIZE),
+	type: z.string().regex(BOARD_EXTENSION_TYPE_PATTERN),
+	props: z.record(z.string(), z.unknown()).default({}),
+	preview: BoardItemPreviewSchema.optional()
+}).strict();
+const BOARD_ITEM_SCHEMAS = {
+	frame: BoardFrameItemSchema,
+	text: BoardTextItemSchema,
+	shape: BoardShapeItemSchema,
+	draw: BoardDrawItemSchema,
+	arrow: BoardArrowItemSchema,
+	image: BoardImageItemSchema,
+	video: BoardVideoItemSchema,
+	audio: BoardAudioItemSchema,
+	file: BoardFileItemSchema,
+	task: BoardTaskItemSchema,
+	effect: BoardEffectItemSchema,
+	custom: BoardCustomItemSchema
+};
+const BOARD_ITEM_TYPES = Object.keys(BOARD_ITEM_SCHEMAS);
+function isBuiltinItemType(type) {
+	return Object.hasOwn(BOARD_ITEM_SCHEMAS, type);
+}
+function boardItemSchema(type) {
+	if (isBuiltinItemType(type)) return BOARD_ITEM_SCHEMAS[type];
+	return BOARD_EXTENSION_TYPE_PATTERN.test(type) ? BoardExtensionItemSchema : null;
+}
+function issuesToDiagnostics(error, path) {
+	return error.issues.map((issue) => {
+		return {
+			severity: "error",
+			code: "INVALID_ITEM",
+			path: [path, ...issue.path.map(String)].filter(Boolean).join("."),
+			message: issue.code === "unrecognized_keys" ? `unknown ${issue.keys.length === 1 ? "property" : "properties"} ${issue.keys.join(", ")}` : issue.message
+		};
+	});
+}
+function parseBoardItem(value, path = "item") {
+	const type = value && typeof value === "object" && !Array.isArray(value) ? value.type : void 0;
+	if (typeof type !== "string") return {
+		ok: false,
+		diagnostics: [{
+			severity: "error",
+			code: "INVALID_ITEM",
+			path: `${path}.type`,
+			message: "type is required"
+		}]
+	};
+	const schema = boardItemSchema(type);
+	if (!schema) return {
+		ok: false,
+		diagnostics: [{
+			severity: "error",
+			code: "INVALID_ITEM",
+			path: `${path}.type`,
+			message: `unknown type ${type}; expected ${BOARD_ITEM_TYPES.join(", ")} or a namespaced extension type`
+		}]
+	};
+	const parsed = schema.safeParse(value);
+	return parsed.success ? {
+		ok: true,
+		item: parsed.data
+	} : {
+		ok: false,
+		diagnostics: issuesToDiagnostics(parsed.error, path)
+	};
+}
+const CSS_EASE_KEYWORDS = /* @__PURE__ */ new Set([
+	"linear",
+	"ease",
+	"ease-in",
+	"ease-out",
+	"ease-in-out",
+	"step-start",
+	"step-end"
+]);
+function isBoardEase(value) {
+	const ease = value.trim();
+	if (CSS_EASE_KEYWORDS.has(ease)) return true;
+	const bezier = /^cubic-bezier\(\s*([^,()]+),\s*([^,()]+),\s*([^,()]+),\s*([^,()]+)\)$/.exec(ease);
+	if (bezier) {
+		const [x1, , x2] = bezier.slice(1).map(Number);
+		return bezier.slice(1).every((part) => Number.isFinite(Number(part))) && x1 >= 0 && x1 <= 1 && x2 >= 0 && x2 <= 1;
+	}
+	return /^steps\(\s*[1-9]\d*\s*(?:,\s*(?:start|end|jump-start|jump-end|jump-none|jump-both)\s*)?\)$/.test(ease);
+}
+const BoardEaseSchema = z.string().max(120).refine(isBoardEase, "expected a CSS easing: linear, ease-in-out, cubic-bezier(…) or steps(…)");
+const BoardKeyframeSchema = z.object({
+	at: nonNegative.describe("Time in milliseconds."),
+	value: z.unknown(),
+	ease: BoardEaseSchema.optional().describe("Easing into this keyframe: a CSS keyword, cubic-bezier() or steps(); defaults to linear.")
+}).strict();
+const BoardTrackSchema = z.object({
+	target: z.string().min(1).max(160).describe("An item id, camera, or another animation id (its time property nests that timeline)."),
+	property: z.string().min(1).max(200).describe("JSON path in the target, e.g. position, opacity, style.fill, props.text."),
+	keyframes: z.array(BoardKeyframeSchema).min(1).max(1e5).describe("Ordered by at. The value holds before the first and after the last keyframe."),
+	composite: z.enum(["replace", "add"]).default("replace").describe("replace: the latest-started track wins. add: positions and rotations add; scale and opacity multiply."),
+	interpolation: z.enum([
+		"auto",
+		"step",
+		"spline"
+	]).default("auto").describe("auto blends numbers, vectors and colors and steps other values; spline smooths position paths."),
+	orient: z.boolean().optional().describe("Rotate the item along its path.")
+}).strict().superRefine((track, context) => {
+	for (let index = 1; index < track.keyframes.length; index += 1) if ((track.keyframes[index]?.at ?? 0) < (track.keyframes[index - 1]?.at ?? 0)) context.addIssue({
+		code: "custom",
+		message: "keyframes must be ordered by at",
+		path: [
+			"keyframes",
+			index,
+			"at"
+		]
+	});
+});
+const BoardMarkerSchema = z.object({
+	at: nonNegative,
+	label: z.string().max(280).optional(),
+	pause: z.boolean().optional().describe("Hold shared playback here until next.")
+}).strict();
+const BoardAnimationHeaderSchema = z.object({
+	name: z.string().max(280).optional(),
+	duration: finite.positive().max(864e5).describe("Milliseconds; a new animation without it ends at its last keyframe."),
+	play: z.enum([
+		"manual",
+		"auto",
+		"always"
+	]).default("manual").describe("manual: only shared playback starts it. auto: plays when the Board opens. always: loops continuously."),
+	delay: nonNegative.default(0),
+	loop: z.boolean().default(false),
+	end: z.enum(["hold", "reset"]).default("hold").describe("hold keeps the last frame; reset returns to the start."),
+	markers: z.array(BoardMarkerSchema).max(1e4).default([]).describe("Labeled points on this timeline; a nested animation's markers do not carry over.")
+}).strict();
+const BoardAnimationSchema = BoardAnimationHeaderSchema.extend({ tracks: z.record(BoardKeySchema, BoardTrackSchema).default({}) }).strict();
+const BOARD_ENTER_PRESETS = [
+	"fade-in",
+	"rise",
+	"drop",
+	"pop",
+	"deal"
+];
+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();
+const BoardSettingsSchema = z.object({
+	title: z.string().min(1).max(255).optional(),
+	background: BoardBackgroundSchema.default({ kind: "dots" }),
+	grid: z.object({
+		visible: z.boolean().default(false).describe("Show the grid overlay."),
+		size: finite.min(4).max(512).default(24)
+	}).strict().optional(),
+	enter: z.object({
+		preset: z.enum(BOARD_ENTER_PRESETS),
+		duration: finite.positive().max(1e4).optional()
+	}).strict().optional().describe("Motion for items as they are added.")
+}).strict();
+const patchObject = z.record(z.string(), z.unknown());
+const BoardPatchSchema = z.object({
+	board: patchObject.nullable().optional(),
+	items: z.record(BoardIdSchema, patchObject.nullable()).optional(),
+	animations: z.record(BoardIdSchema, patchObject.and(z.object({ tracks: z.record(BoardKeySchema, patchObject.nullable()).optional() })).nullable()).optional()
+}).strict();
+//#endregion
+//#region ../protocol/dist/board.js
+const BOARD_EXTENSION = ".board";
+const BOARD_MIME_TYPE = "application/json";
+const BoardManifestSchema = z.object({
+	kind: z.literal("cohub.board.manifest"),
+	version: z.literal(1),
+	boardId: z.string().uuid(),
+	title: z.string().min(1).max(255)
+});
+var InvalidBoardFileError = class extends Error {
+	code = "INVALID_BOARD_FILE";
+	constructor(message = "Board file is invalid") {
+		super(message);
+		this.name = "InvalidBoardFileError";
+	}
+};
+function parseBoardManifest(input) {
+	let value = input;
+	if (typeof input === "string") try {
+		value = JSON.parse(input);
+	} catch {
+		throw new InvalidBoardFileError("Board file must contain valid JSON");
+	}
+	const parsed = BoardManifestSchema.safeParse(value);
+	if (!parsed.success) throw new InvalidBoardFileError("Board file must contain a valid boardId");
+	return parsed.data;
+}
+function isBoardPath(path) {
+	return path.toLowerCase().endsWith(BOARD_EXTENSION);
+}
+const BOARD_READ_SECTIONS = ["items", "animations"];
+const rectSchema = z.object({
+	x: z.number().finite(),
+	y: z.number().finite(),
+	width: z.number().finite().positive(),
+	height: z.number().finite().positive()
+}).strict();
+z.object({
+	only: z.array(z.enum(BOARD_READ_SECTIONS)).optional(),
+	rect: rectSchema.optional(),
+	within: BoardIdSchema.optional(),
+	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()
+}).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"
+});
+z.object({
+	patch: BoardPatchSchema,
+	replace: z.boolean().default(false),
+	cascade: z.boolean().default(false),
+	dryRun: z.boolean().default(false),
+	baseVersion: z.number().int().nonnegative().optional(),
+	mutationId: z.string().min(1).max(160).optional(),
+	clientId: z.string().min(1).max(160).optional()
+}).strict();
+z.object({
+	path: z.string().min(1),
+	title: z.string().min(1).max(255).optional(),
+	document: BoardPatchSchema.optional(),
+	mutationId: z.string().max(160).optional()
+}).strict();
+z.object({
+	before: z.number().int().positive().optional(),
+	limit: z.number().int().min(1).max(500).default(200)
+}).strict();
+const commandId = z.string().min(1).max(160);
+z.discriminatedUnion("type", [
+	z.object({
+		commandId,
+		type: z.literal("play"),
+		animationId: z.string().min(1),
+		position: z.number().finite().nonnegative().optional(),
+		timeScale: z.number().finite().positive().max(4).optional(),
+		seed: z.string().min(1).max(160).optional()
+	}).strict(),
+	z.object({
+		commandId,
+		type: z.literal("pause")
+	}).strict(),
+	z.object({
+		commandId,
+		type: z.literal("resume")
+	}).strict(),
+	z.object({
+		commandId,
+		type: z.literal("seek"),
+		position: z.number().finite().nonnegative()
+	}).strict(),
+	z.object({
+		commandId,
+		type: z.literal("next")
+	}).strict(),
+	z.object({
+		commandId,
+		type: z.literal("stop")
+	}).strict()
+]);
+//#endregion
 //#region ../protocol/dist/model/metrics.js
 const count = z.number().finite().nonnegative();
 const usageSchema = z.object({
@@ -1132,7 +1894,8 @@ var BoardRealtimeClient = class {
 	subscribe(handlers) {
 		if (!this.websocketClient) throw new Error("realtime transport is not configured for this client");
 		ensureRealtimeConnected(this.websocketClient);
-		const releaseRoom = this.websocketClient.retainRooms([getRealtimeSpaceRoom(this.spaceId), getRealtimeBoardRoom(this.boardId)]);
+		const room = getRealtimeBoardRoom(this.boardId);
+		const releaseRoom = this.websocketClient.retainRooms([getRealtimeSpaceRoom(this.spaceId), room]);
 		const unsubscribe = this.websocketClient.on("event", (event) => {
 			if (event.spaceId !== this.spaceId) return;
 			if (event.type === "board.changed" && event.payload.boardId === this.boardId) {
@@ -1153,8 +1916,13 @@ var BoardRealtimeClient = class {
 				handlers.playback?.(playbackEvent);
 			}
 		});
+		const resync = handlers.resync;
+		const stopResync = resync ? this.websocketClient.on("subscribed", ({ rooms }) => {
+			if (rooms.includes(room)) resync();
+		}) : null;
 		return () => {
 			unsubscribe();
+			stopResync?.();
 			releaseRoom();
 		};
 	}
@@ -1292,14 +2060,25 @@ var BoardClient = class {
 		return this.realtime.on("playback", handler);
 	}
 };
+async function fileText(file, customFetch = fetch) {
+	if (!file.content && file.delivery === "url" && file.url) {
+		const response = await customFetch(file.url);
+		if (!response.ok) throw new Error(`${file.path} could not be read (${response.status})`);
+		return response.text();
+	}
+	if (file.encoding !== "base64") return file.content;
+	return new TextDecoder().decode(Uint8Array.from(atob(file.content), (char) => char.charCodeAt(0)));
+}
 var SpaceBoardsApi = class {
 	http;
 	spaceId;
 	websocket;
-	constructor(http, spaceId, websocket) {
+	files;
+	constructor(http, spaceId, websocket, files) {
 		this.http = http;
 		this.spaceId = spaceId;
 		this.websocket = websocket;
+		this.files = files;
 	}
 	byId(boardId) {
 		return new BoardClient({
@@ -1309,6 +2088,14 @@ var SpaceBoardsApi = class {
 			boardId
 		});
 	}
+	async open(target, customFetch) {
+		return this.byId(isBoardPath(target) ? await this.resolveId(target, customFetch) : target);
+	}
+	async resolveId(path, customFetch) {
+		const file = await this.files.read(path, customFetch);
+		if (!("content" in file)) throw new Error(`${path} is being prepared; try again shortly.`);
+		return parseBoardManifest(await fileText(file, customFetch)).boardId;
+	}
 	/** Create a `.board` file and its Board, optionally with an initial document. */
 	create(input) {
 		return this.http.request(`/api/spaces/${this.spaceId}/boards`, {
@@ -4075,7 +4862,7 @@ var SpaceClient = class {
 		this.displays = new SpaceDisplaysApi(transport, id);
 		this.invitations = new SpaceInvitationsApi(transport, id);
 		this.labels = new SpaceLabelsApi(transport, id);
-		this.boards = new SpaceBoardsApi(transport, id, websocketClient);
+		this.boards = new SpaceBoardsApi(transport, id, websocketClient, this.files);
 		this.wallet = new SpaceWalletApi(transport, id);
 		this.commerce = new SpaceCommerceApi(transport, id);
 	}
@@ -5036,4 +5823,4 @@ var CohubHttpClient = class {
 };
 const createHttpClient = (options) => new CohubHttpClient(options);
 //#endregion
-export { isTerminalDesktopCommandStatus as $, BoardClient as A, CronJobsApi as B, SessionPatchReducer as C, connectDisplay as D, DisplayConnection as E, PublicAssetsApi as F, DESKTOP_COMMAND_OPEN_TIMEOUT_MS as G, DESKTOP_COMMAND_ACCEPT_TIMEOUT_MS as H, SkillsApi as I, DESKTOP_COMMAND_SETTLEMENT_GRACE_SECONDS as J, DESKTOP_COMMAND_PAYLOAD_MAX_BYTES as K, PromptsApi as L, SessionAccessApi as M, ReferencesApi as N, readRtcTransportStats as O, SearchApi as P, isDesktopCallMethod as Q, ModelsApi as R, parseAssistantMessageCommit as S, SpaceDisplaysApi as T, DESKTOP_COMMAND_DEFAULT_TIMEOUT_MS as U, ChannelsApi as V, DESKTOP_COMMAND_MAX_TIMEOUT_MS as W, DESKTOP_COMMAND_VERSION as X, DESKTOP_COMMAND_TERMINAL_TTL_SECONDS as Y, defaultDesktopCommandTimeoutMs as Z, PublicInviteApi as _, WorkCommerceApi as a, DISPLAY_INPUT_MAX_SCHEDULE_MS as at, SessionGenerationStreamClient as b, AppsApi as c, normalizeDisplayPoint as ct, UserApi as d, parseDesktopCommand as et, TasksApi as f, SpacesApi as g, SpaceWebhooksApi as h, AppCommerceApi as i, DISPLAY_ELEMENT_REF_PATTERN as it, ensureRealtimeConnected as j, waitForIceGathering as k, ReferralsApi as l, splitDisplayText as lt, SpacePublicFilesApi as m, createHttpClient as n, resolveOpenSurface as nt, DesktopCommandsApi as o, DISPLAY_INPUT_MAX_TEXT as ot, SpaceClient as p, DESKTOP_COMMAND_PENDING_TTL_SECONDS as q, RoomsApi as r, NAVIGATION_ERROR_MESSAGE_MAX_LENGTH as rt, UiCommandsApi as s, DISPLAY_SYSTEM_ACTIONS as st, CohubHttpClient as t, parseDesktopCommandId as tt, UsersApi as u, buildSpaceInvitePath as v, createSessionPatchReducer as w, createSessionGenerationStreamClient as x, buildSpacePath as y, GenerationsApi as z };
+export { isTerminalDesktopCommandStatus as $, BoardClient as A, CronJobsApi as B, SessionPatchReducer as C, isBuiltinItemType as Ct, connectDisplay as D, boardDefaultSize as Dt, DisplayConnection as E, BOARD_ARROW_STROKE_SIZE as Et, PublicAssetsApi as F, DESKTOP_COMMAND_OPEN_TIMEOUT_MS as G, DESKTOP_COMMAND_ACCEPT_TIMEOUT_MS as H, SkillsApi as I, DESKTOP_COMMAND_SETTLEMENT_GRACE_SECONDS as J, DESKTOP_COMMAND_PAYLOAD_MAX_BYTES as K, PromptsApi as L, SessionAccessApi as M, ReferencesApi as N, readRtcTransportStats as O, SearchApi as P, isDesktopCallMethod as Q, ModelsApi as R, parseAssistantMessageCommit as S, boardItemSchema as St, SpaceDisplaysApi as T, normalizeBoardRemoteUrl as Tt, DESKTOP_COMMAND_DEFAULT_TIMEOUT_MS as U, ChannelsApi as V, DESKTOP_COMMAND_MAX_TIMEOUT_MS as W, DESKTOP_COMMAND_VERSION as X, DESKTOP_COMMAND_TERMINAL_TTL_SECONDS as Y, defaultDesktopCommandTimeoutMs as Z, PublicInviteApi as _, BoardColorSchema as _t, WorkCommerceApi as a, DISPLAY_INPUT_MAX_SCHEDULE_MS as at, SessionGenerationStreamClient as b, BoardTrackSchema as bt, AppsApi as c, normalizeDisplayPoint as ct, UserApi as d, BOARD_MIME_TYPE as dt, parseDesktopCommand as et, TasksApi as f, BOARD_CAMERA_TARGET as ft, SpacesApi as g, BoardAnimationSchema as gt, SpaceWebhooksApi as h, BoardAnimationHeaderSchema as ht, AppCommerceApi as i, DISPLAY_ELEMENT_REF_PATTERN as it, ensureRealtimeConnected as j, waitForIceGathering as k, ReferralsApi as l, splitDisplayText as lt, SpacePublicFilesApi as m, BOARD_ITEM_TYPES as mt, createHttpClient as n, resolveOpenSurface as nt, DesktopCommandsApi as o, DISPLAY_INPUT_MAX_TEXT as ot, SpaceClient as p, BOARD_COLOR_TOKENS as pt, DESKTOP_COMMAND_PENDING_TTL_SECONDS as q, RoomsApi as r, NAVIGATION_ERROR_MESSAGE_MAX_LENGTH as rt, UiCommandsApi as s, DISPLAY_SYSTEM_ACTIONS as st, CohubHttpClient as t, parseDesktopCommandId as tt, UsersApi as u, BOARD_EXTENSION as ut, buildSpaceInvitePath as v, BoardPatchSchema as vt, createSessionPatchReducer as w, parseBoardItem as wt, createSessionGenerationStreamClient as x, BoardVec2Schema as xt, buildSpacePath as y, BoardSettingsSchema as yt, GenerationsApi as z };