@neta-art/cohub 11.1.0 → 11.3.0

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

@@ -36,7 +36,7 @@ const colorString = z.string().max(120).refine(isBoardColorString, "expected a p
 const BoardColorSchema = z.union([colorString, z.object({
 	light: colorString,
 	dark: colorString
-}).strict()]);
+}).strict()]).describe("Palette token (follows the theme), CSS color, or { light, dark }.");
 const BOARD_DASHES = [
 	"solid",
 	"dashed",
@@ -44,12 +44,12 @@ const BOARD_DASHES = [
 ];
 const BoardStyleSchema = z.object({
 	fill: BoardColorSchema.optional(),
-	fillOpacity: ratio.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(BOARD_DASHES).optional(),
-	radius: nonNegative.optional(),
-	trim: ratio.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 !== "..");
@@ -65,18 +65,18 @@ function parseBoardMediaSource(src) {
 		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 stable public HTTP(S) URL; relative Space file paths remain supported.");
+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"),
-	params: z.record(z.string(), z.json()).default({}),
-	targets: z.record(z.string().min(1).max(80), BoardIdSchema).default({}),
-	seed: z.string().min(1).max(160).optional(),
+	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();
+}).strict().describe("A JavaScript module attached to the item; `cohub boards schema script` lists its API.");
 const itemEnvelope = {
 	script: BoardScriptSchema.optional(),
-	parent: BoardIdSchema.optional(),
-	z: finite.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
@@ -86,7 +86,7 @@ const itemEnvelope = {
 	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(),
@@ -119,8 +119,8 @@ const BoardFrameItemSchema = z.object({
 	type: z.literal("frame"),
 	props: z.object({
 		label: z.string().max(280).default(""),
-		decoration: z.enum(["frame", "none"]).optional(),
-		clip: z.boolean().default(true)
+		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({
@@ -130,12 +130,12 @@ const BoardTextItemSchema = 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"),
+		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(),
-		reveal: ratio.default(1),
-		caret: z.boolean().default(false)
+		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({
@@ -143,7 +143,7 @@ const BoardShapeItemSchema = z.object({
 	type: z.literal("shape"),
 	props: z.object({
 		geometry: z.enum(BOARD_SHAPE_GEOMETRIES).default("rectangle"),
-		path: z.string().min(1).max(2e5).optional(),
+		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")
@@ -155,12 +155,12 @@ const BoardShapeItemSchema = z.object({
 const BoardDrawPointSchema = z.object({
 	x: finite,
 	y: finite,
-	p: ratio.default(.5)
+	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) }).strict()
+	props: z.object({ points: z.array(BoardDrawPointSchema).min(1).max(1e5).describe("Stroke points relative to position; the size follows them.") }).strict()
 }).strict();
 const BOARD_ANCHOR_SIDES = [
 	"top",
@@ -181,10 +181,10 @@ const BoardArrowAnchorSchema = z.union([
 ]);
 const BoardArrowBindingSchema = z.object({
 	item: BoardIdSchema,
-	anchor: BoardArrowAnchorSchema.default("auto"),
+	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]);
+const BoardArrowEndSchema = z.union([BoardVec2Schema, BoardArrowBindingSchema]).describe("A point relative to position, or { item } to follow that item.");
 const BOARD_ARROW_ROUTES = [
 	"straight",
 	"curve",
@@ -197,13 +197,13 @@ const BoardArrowItemSchema = z.object({
 		start: BoardArrowEndSchema,
 		end: BoardArrowEndSchema,
 		route: z.enum(BOARD_ARROW_ROUTES).default("straight"),
-		bend: finite.min(-.85).max(.85).default(0),
-		waypoints: z.array(BoardVec2Schema).max(64).default([]),
+		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()
+		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 BoardMediaSnapshotSchema = z.object({
@@ -217,7 +217,7 @@ const BoardMediaSnapshotSchema = z.object({
 	excerpt: z.string().optional(),
 	coverPath: z.string().optional(),
 	coverUrl: z.string().optional()
-}).strict();
+}).strict().describe("Cached facts for an instant preview; filled in when the media loads.");
 const fileProps = {
 	src: BoardMediaSourceSchema,
 	snapshot: BoardMediaSnapshotSchema.optional()
@@ -225,21 +225,21 @@ const fileProps = {
 const BoardMediaOriginSchema = z.object({
 	taskRunId: z.string().min(1).max(160),
 	artifactId: z.string().min(1).max(240)
-}).strict();
+}).strict().describe("The generation run and result this media came from.");
 const mediaProps = {
 	...fileProps,
 	origin: BoardMediaOriginSchema.optional()
 };
 const timedFileProps = {
 	...mediaProps,
-	time: nonNegative.optional()
+	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();
+}).strict().describe("Region shown, as fractions of the image. Without it the whole image fits inside size.");
 const BoardImageItemSchema = z.object({
 	...boxed(640, 360),
 	type: z.literal("image"),
@@ -320,8 +320,8 @@ const BoardTaskItemSchema = z.object({
 	...boxed(420, 240),
 	type: z.literal("task"),
 	props: z.object({
-		taskRunId: z.string().min(1).max(160),
-		snapshot: BoardTaskSnapshotSchema.describe("Maintained by the server for tasks in the Board's Space; writers may omit it.")
+		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 = [
@@ -397,8 +397,8 @@ const BoardEffectItemSchema = z.object({
 		spread: finite.min(0).max(360).default(360),
 		gravity: finite.default(0),
 		intensity: nonNegative.max(10).default(1),
-		follow: BoardIdSchema.optional(),
-		seed: z.string().min(1).max(160).optional()
+		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({
@@ -517,21 +517,21 @@ function isBoardEase(value) {
 }
 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,
+	at: nonNegative.describe("Time in milliseconds."),
 	value: z.unknown(),
-	ease: BoardEaseSchema.optional()
+	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),
-	property: z.string().min(1).max(200),
-	keyframes: z.array(BoardKeyframeSchema).min(1).max(1e5),
-	composite: z.enum(["replace", "add"]).default("replace"),
+	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"),
-	orient: z.boolean().optional()
+	]).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",
@@ -546,7 +546,7 @@ const BoardTrackSchema = z.object({
 const BoardMarkerSchema = z.object({
 	at: nonNegative,
 	label: z.string().max(280).optional(),
-	pause: z.boolean().optional()
+	pause: z.boolean().optional().describe("Hold shared playback here until next.")
 }).strict();
 const BOARD_PLAY_MODES = [
 	"manual",
@@ -555,12 +555,12 @@ const BOARD_PLAY_MODES = [
 ];
 const BoardAnimationHeaderSchema = z.object({
 	name: z.string().max(280).optional(),
-	duration: finite.positive().max(864e5),
-	play: z.enum(BOARD_PLAY_MODES).default("manual"),
+	duration: finite.positive().max(864e5).describe("Milliseconds; a new animation without it ends at its last keyframe."),
+	play: z.enum(BOARD_PLAY_MODES).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"),
-	markers: z.array(BoardMarkerSchema).max(1e4).default([])
+	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 = [
@@ -578,7 +578,7 @@ const BoardBackgroundSchema = z.object({
 		"image"
 	]).default("dots"),
 	color: BoardColorSchema.optional(),
-	imageUrl: z.string().url().max(4096).optional(),
+	imageUrl: z.string().url().max(4096).optional().describe("Background image for kind image."),
 	fit: z.enum([
 		"cover",
 		"contain",
@@ -593,13 +593,13 @@ 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),
+		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()
+	}).strict().optional().describe("Motion for items as they are added.")
 }).strict();
 function emptyBoardDocument() {
 	return {

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

@@ -1,6 +1,6 @@
 //#region ../protocol/dist/board-schema.d.ts
 type JsonSchema = Record<string, unknown>;
-declare const BOARD_SCHEMA_TARGETS: readonly ["board", "animation", "track", "camera", ...("arrow" | "audio" | "custom" | "draw" | "effect" | "file" | "frame" | "image" | "shape" | "task" | "text" | "video")[]];
+declare const BOARD_SCHEMA_TARGETS: readonly ["board", "animation", "track", "script", "camera", ...("arrow" | "audio" | "custom" | "draw" | "effect" | "file" | "frame" | "image" | "shape" | "task" | "text" | "video")[]];
 type BoardJsonSchemaResult = {
   schema?: JsonSchema;
   properties?: Array<{
@@ -11,7 +11,6 @@ type BoardJsonSchemaResult = {
     description: string;
     parameters: Record<string, string>;
   }>;
-  semantics?: Record<string, string>;
 };
 declare function boardJsonSchema(target: string): BoardJsonSchemaResult | null;
 declare function boardSchemaOverview(): {

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

@@ -1,4 +1,4 @@
-import { BOARD_CAMERA_TARGET, BOARD_COLOR_TOKENS, BOARD_EFFECT_KINDS, BOARD_EFFECT_KIND_INFO, BOARD_ITEM_SCHEMAS, BOARD_ITEM_TYPES, BoardAnimationHeaderSchema, BoardKeySchema, BoardSettingsSchema, BoardTrackSchema, isBuiltinItemType } from "./board-model.js";
+import { BOARD_CAMERA_TARGET, BOARD_COLOR_TOKENS, BOARD_EFFECT_KINDS, BOARD_EFFECT_KIND_INFO, BOARD_ITEM_SCHEMAS, BOARD_ITEM_TYPES, BoardAnimationHeaderSchema, BoardKeySchema, BoardScriptSchema, BoardSettingsSchema, BoardTrackSchema, isBuiltinItemType } from "./board-model.js";
 import { listBoardProperties } from "./board-patch.js";
 import { z } from "zod";
 //#region ../protocol/dist/board-schema.js
@@ -13,6 +13,7 @@ const BOARD_SCHEMA_TARGETS = [
 	"board",
 	"animation",
 	"track",
+	"script",
 	BOARD_CAMERA_TARGET,
 	...BOARD_ITEM_TYPES
 ];
@@ -20,32 +21,16 @@ function boardJsonSchema(target) {
 	if (target === "board") return { schema: toJsonSchema(BoardSettingsSchema) };
 	if (target === "animation") return {
 		schema: toJsonSchema(BoardAnimationHeaderSchema.extend({ tracks: z.record(BoardKeySchema, BoardTrackSchema).optional() })),
-		properties: listBoardProperties("animation"),
-		semantics: { composition: "Target another animation's time property to drive its local clock. Parent markers control pauses; child markers are not automatically promoted." }
-	};
-	if (target === "track") return {
-		schema: toJsonSchema(BoardTrackSchema),
-		semantics: {
-			boundary: "Before the first keyframe and after the last, the value is held. Use opacity tracks to control visibility.",
-			easing: "Defaults to linear. The destination keyframe controls the incoming segment. Supports CSS easing keywords, cubic-bezier() and steps().",
-			composition: "replace: the most recently started track wins; ties use the lexicographically larger track ID. Before any start, the nearest upcoming track wins. add: numbers and positions add; opacity and scale multiply.",
-			interpolation: "auto interpolates numbers, colors and vectors; other values step. spline smooths vector motion. orient follows the position tangent."
-		}
-	};
-	if (target === "effect") return {
-		schema: toJsonSchema(BOARD_ITEM_SCHEMAS.effect),
-		properties: listBoardProperties("effect"),
-		semantics: {
-			follow: "follow is used by trail only. Parent a particle effect to a decoration:none frame to move it with other items.",
-			time: "Effects use animation time in milliseconds. trail samples target history; seed makes procedural particles repeatable."
-		},
-		kinds: Object.fromEntries(BOARD_EFFECT_KINDS.map((kind) => [kind, BOARD_EFFECT_KIND_INFO[kind]]))
+		properties: listBoardProperties("animation")
 	};
+	if (target === "track") return { schema: toJsonSchema(BoardTrackSchema) };
+	if (target === "script") return { schema: toJsonSchema(BoardScriptSchema) };
 	if (target === "camera") return { properties: listBoardProperties(BOARD_CAMERA_TARGET) };
 	if (!isBuiltinItemType(target)) return null;
 	return {
 		schema: toJsonSchema(BOARD_ITEM_SCHEMAS[target]),
-		properties: listBoardProperties(target)
+		properties: listBoardProperties(target),
+		...target === "effect" ? { kinds: Object.fromEntries(BOARD_EFFECT_KINDS.map((kind) => [kind, BOARD_EFFECT_KIND_INFO[kind]])) } : {}
 	};
 }
 function boardSchemaOverview() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neta-art/cohub",
-  "version": "11.1.0",
+  "version": "11.3.0",
   "description": "Cohub SDK for spaces, sessions, boards, and realtime agent collaboration.",
   "license": "Apache-2.0",
   "private": false,
@@ -129,6 +129,7 @@
     "lint": "biome lint .",
     "lint:fix": "biome lint --write .",
     "test": "node ./scripts/test.mjs",
+    "bench:board": "tsx ./scripts/board-bench.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   }
 }