@neta-art/cohub-cli 10.2.0 → 10.4.1

package/dist/board-kernel.js

@@ -1,4 +1,4 @@
-import { $ as groupD8, A as bgr2rgb, B as Bounds, C as Sprite, D as TexturePool, E as RenderGroup, G as TextureStyle, H as Texture, I as BigPool, J as deprecation, K as definedProps, L as GlobalResourceRegistry, M as multiplyHexColors, N as getGlobalBounds, O as InstructionSet, P as FilterEffect, Q as Rectangle, R as warn, S as DOMAdapter, T as Container, U as TextureMatrix, V as updateQuadBounds, W as TextureSource, X as v8_3_4, Y as v8_0_0, Z as uid$1, _ as Cache, a as Geometry, at as extensions, b as ImageSource, c as Filter, d as RendererType, et as Matrix, f as BindGroup, g as getTestContext, h as GlProgram, i as canUseNewCanvasBlendModes, it as ExtensionType, j as multiplyColors, k as getLocalBounds, l as State, m as GpuProgram, n as CanvasPool, nt as eventemitter3_default, o as Buffer$1, p as UniformGroup, q as nextPow2, r as canvasUtils, rt as ObservablePoint, s as BufferUsage, t as getPo2TextureFromSource, tt as Point, u as Shader, v as Ticker, w as ViewContainer, x as CanvasSource, z as Color } from "./board-kernel/getPo2TextureFromSource.js";
+import { $ as groupD8, A as bgr2rgb, B as Bounds, C as Sprite, D as TexturePool, E as RenderGroup, G as TextureStyle, H as Texture, I as BigPool, J as deprecation, K as definedProps, L as GlobalResourceRegistry, M as multiplyHexColors, N as getGlobalBounds, O as InstructionSet, P as FilterEffect, Q as Rectangle, R as warn, S as DOMAdapter, T as Container, U as TextureMatrix, V as updateQuadBounds, W as TextureSource, X as v8_3_4, Y as v8_0_0, Z as uid$1, _ as Cache, a as Geometry, at as extensions, b as ImageSource, c as Filter, d as RendererType, et as Matrix, f as BindGroup, g as getTestContext, h as GlProgram, i as canUseNewCanvasBlendModes, it as ExtensionType, j as multiplyColors, k as getLocalBounds, l as State, m as GpuProgram, n as CanvasPool, nt as eventemitter3_default, o as Buffer, p as UniformGroup, q as nextPow2, r as canvasUtils, rt as ObservablePoint, s as BufferUsage, t as getPo2TextureFromSource, tt as Point, u as Shader, v as Ticker, w as ViewContainer, x as CanvasSource, z as Color } from "./board-kernel/getPo2TextureFromSource.js";
 import { Worker } from "node:worker_threads";
 import { fileURLToPath } from "node:url";
 //#region ../../node_modules/.pnpm/zod@4.6.5/node_modules/zod/v4/core/util.js
@@ -5772,10 +5772,10 @@ const colorString$1 = string().max(120).refine(isBoardColorString$1, "expected a
 const BoardColorSchema$1 = union([colorString$1, object({
 	light: colorString$1,
 	dark: colorString$1
-}).strict()]);
+}).strict()]).describe("Palette token (follows the theme), CSS color, or { light, dark }.");
 const BoardStyleSchema$1 = object({
 	fill: BoardColorSchema$1.optional(),
-	fillOpacity: ratio$1.optional(),
+	fillOpacity: ratio$1.optional().describe("Fill opacity, independent of the item's opacity."),
 	stroke: BoardColorSchema$1.optional(),
 	strokeWidth: finite$1.min(0).max(64).optional(),
 	dash: _enum([
@@ -5783,8 +5783,8 @@ const BoardStyleSchema$1 = object({
 		"dashed",
 		"dotted"
 	]).optional(),
-	radius: nonNegative$1.optional(),
-	trim: ratio$1.optional()
+	radius: nonNegative$1.optional().describe("Corner radius in board units."),
+	trim: ratio$1.optional().describe("Fraction of the outline drawn; animate 0 → 1 to draw it in.")
 }).strict();
 function isSafeBoardSourcePath$1(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 !== "..");
@@ -5800,18 +5800,18 @@ function parseBoardMediaSource$1(src) {
 		value: src
 	} : null;
 }
-const BoardMediaSourceSchema$1 = string().max(4096).refine((src) => parseBoardMediaSource$1(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$1 = string().max(4096).refine((src) => parseBoardMediaSource$1(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$1 = object({
-	src: srcSchema$1.refine((path) => /\.m?js$/.test(path), "script src must be a .js or .mjs module"),
-	params: record(string(), json()).default({}),
-	targets: record(string().min(1).max(80), BoardIdSchema$1).default({}),
-	seed: string().min(1).max(160).optional(),
+	src: srcSchema$1.refine((path) => /\.m?js$/.test(path), "script src must be a .js or .mjs module").describe("A .js or .mjs Space file."),
+	params: record(string(), json()).default({}).describe("Values the module reads as params."),
+	targets: record(string().min(1).max(80), BoardIdSchema$1).default({}).describe("Named items the module can reach, as ctx.targets."),
+	seed: string().min(1).max(160).optional().describe("Seed for ctx.random(); defaults to the item id."),
 	enabled: boolean().default(true)
-}).strict();
+}).strict().describe("A JavaScript module attached to the item; `cohub boards schema script` lists its API.");
 const itemEnvelope$1 = {
 	script: BoardScriptSchema$1.optional(),
-	parent: BoardIdSchema$1.optional(),
-	z: finite$1.optional(),
+	parent: BoardIdSchema$1.optional().describe("A frame id; position becomes relative to the frame, and the item moves with it."),
+	z: finite$1.optional().describe("Order among siblings; new items go on top."),
 	position: BoardVec2Schema$1.default({
 		x: 0,
 		y: 0
@@ -5821,7 +5821,7 @@ const itemEnvelope$1 = {
 	origin: BoardVec2Schema$1.default({
 		x: .5,
 		y: .5
-	}),
+	}).describe("Rotation and scale origin as fractions of the size."),
 	opacity: ratio$1.default(1),
 	style: BoardStyleSchema$1.default({}),
 	locked: boolean().optional(),
@@ -5854,8 +5854,8 @@ const BoardFrameItemSchema$1 = object({
 	type: literal("frame"),
 	props: object({
 		label: string().max(280).default(""),
-		decoration: _enum(["frame", "none"]).optional(),
-		clip: boolean().default(true)
+		decoration: _enum(["frame", "none"]).optional().describe("none hides the title, border and background: an invisible group whose tracks move every child."),
+		clip: boolean().default(true).describe("Hide children outside the frame.")
 	}).strict().prefault({})
 }).strict();
 const BoardTextItemSchema$1 = object({
@@ -5865,12 +5865,12 @@ const BoardTextItemSchema$1 = object({
 		text: string().default(""),
 		fontSize: fontSize$1.default(24),
 		fontWeight: finite$1.min(100).max(900).default(500),
-		font: string().min(1).max(120).default("sans"),
+		font: string().min(1).max(120).default("sans").describe("sans, serif, mono, or a font family name."),
 		align: _enum(BOARD_TEXT_ALIGNS$1).default("left"),
 		lineHeight: finite$1.min(.5).max(4).default(4 / 3),
-		width: finite$1.positive().optional(),
-		reveal: ratio$1.default(1),
-		caret: boolean().default(false)
+		width: finite$1.positive().optional().describe("Wrap width; the height follows the text."),
+		reveal: ratio$1.default(1).describe("Fraction of the text shown; animate 0 → 1 to type it."),
+		caret: boolean().default(false).describe("Blink a caret while the text is being revealed.")
 	}).strict().prefault({})
 }).strict();
 const BoardShapeItemSchema$1 = object({
@@ -5878,7 +5878,7 @@ const BoardShapeItemSchema$1 = object({
 	type: literal("shape"),
 	props: object({
 		geometry: _enum(BOARD_SHAPE_GEOMETRIES$1).default("rectangle"),
-		path: string().min(1).max(2e5).optional(),
+		path: string().min(1).max(2e5).optional().describe("SVG path data for path geometry, fitted to the item size."),
 		text: string().default(""),
 		fontSize: fontSize$1.default(20),
 		align: _enum(BOARD_TEXT_ALIGNS$1).default("center")
@@ -5890,12 +5890,12 @@ const BoardShapeItemSchema$1 = object({
 const BoardDrawPointSchema$1 = object({
 	x: finite$1,
 	y: finite$1,
-	p: ratio$1.default(.5)
+	p: ratio$1.default(.5).describe("Pen pressure.")
 }).strict();
 const BoardDrawItemSchema$1 = object({
 	...unsized$1,
 	type: literal("draw"),
-	props: object({ points: array(BoardDrawPointSchema$1).min(1).max(1e5) }).strict()
+	props: object({ points: array(BoardDrawPointSchema$1).min(1).max(1e5).describe("Stroke points relative to position; the size follows them.") }).strict()
 }).strict();
 const BoardArrowEndSchema$1 = union([BoardVec2Schema$1, object({
 	item: BoardIdSchema$1,
@@ -5914,9 +5914,9 @@ const BoardArrowEndSchema$1 = union([BoardVec2Schema$1, object({
 			x: ratio$1,
 			y: ratio$1
 		}).strict()
-	]).default("auto"),
+	]).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: string().min(1).max(120).optional()
-}).strict()]);
+}).strict()]).describe("A point relative to position, or { item } to follow that item.");
 const BOARD_ARROW_ROUTES$1 = [
 	"straight",
 	"curve",
@@ -5929,13 +5929,13 @@ const BoardArrowItemSchema$1 = object({
 		start: BoardArrowEndSchema$1,
 		end: BoardArrowEndSchema$1,
 		route: _enum(BOARD_ARROW_ROUTES$1).default("straight"),
-		bend: finite$1.min(-.85).max(.85).default(0),
-		waypoints: array(BoardVec2Schema$1).max(64).default([]),
+		bend: finite$1.min(-.85).max(.85).default(0).describe("Sideways curve as a fraction of the length; the sign picks the side."),
+		waypoints: array(BoardVec2Schema$1).max(64).default([]).describe("Points the route passes through."),
 		arrowStart: boolean().default(false),
 		arrowEnd: boolean().default(true),
 		label: string().max(280).default(""),
 		fontSize: fontSize$1.default(14),
-		relation: string().max(64).regex(/^[a-z0-9]+(?:[.-][a-z0-9]+)*$/, "relation must be a lowercase slug").optional()
+		relation: 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$1 = {
@@ -5951,26 +5951,26 @@ const fileProps$1 = {
 		excerpt: string().optional(),
 		coverPath: string().optional(),
 		coverUrl: string().optional()
-	}).strict().optional()
+	}).strict().describe("Cached facts for an instant preview; filled in when the media loads.").optional()
 };
 const BoardMediaOriginSchema$1 = object({
 	taskRunId: string().min(1).max(160),
 	artifactId: string().min(1).max(240)
-}).strict();
+}).strict().describe("The generation run and result this media came from.");
 const mediaProps$1 = {
 	...fileProps$1,
 	origin: BoardMediaOriginSchema$1.optional()
 };
 const timedFileProps$1 = {
 	...mediaProps$1,
-	time: nonNegative$1.optional()
+	time: nonNegative$1.optional().describe("Playback position in milliseconds; animate props.time to play it on a timeline.")
 };
 const BoardCropSchema$1 = object({
 	x: ratio$1,
 	y: ratio$1,
 	w: ratio$1,
 	h: ratio$1
-}).strict();
+}).strict().describe("Region shown, as fractions of the image. Without it the whole image fits inside size.");
 const BoardImageItemSchema$1 = object({
 	...boxed$1(640, 360),
 	type: literal("image"),
@@ -6050,8 +6050,8 @@ const BoardTaskItemSchema$1 = object({
 	...boxed$1(420, 240),
 	type: literal("task"),
 	props: object({
-		taskRunId: string().min(1).max(160),
-		snapshot: BoardTaskSnapshotSchema$1.describe("Maintained by the server for tasks in the Board's Space; writers may omit it.")
+		taskRunId: string().min(1).max(160).describe("The generation run shown; the server keeps the card's status and results up to date."),
+		snapshot: BoardTaskSnapshotSchema$1.describe("Maintained by the server; omit it.")
 	}).strict()
 }).strict();
 const BOARD_EFFECT_KINDS$1 = [
@@ -6074,8 +6074,8 @@ const BoardEffectItemSchema$1 = object({
 		spread: finite$1.min(0).max(360).default(360),
 		gravity: finite$1.default(0),
 		intensity: nonNegative$1.max(10).default(1),
-		follow: BoardIdSchema$1.optional(),
-		seed: string().min(1).max(160).optional()
+		follow: BoardIdSchema$1.optional().describe("trail: the item to follow."),
+		seed: string().min(1).max(160).optional().describe("Makes procedural motion repeatable.")
 	}).strict()
 }).strict();
 const BoardCustomItemSchema$1 = object({
@@ -6177,21 +6177,21 @@ function isBoardEase$1(value) {
 }
 const BoardEaseSchema$1 = string().max(120).refine(isBoardEase$1, "expected a CSS easing: linear, ease-in-out, cubic-bezier(…) or steps(…)");
 const BoardKeyframeSchema$1 = object({
-	at: nonNegative$1,
+	at: nonNegative$1.describe("Time in milliseconds."),
 	value: unknown(),
-	ease: BoardEaseSchema$1.optional()
+	ease: BoardEaseSchema$1.optional().describe("Easing into this keyframe: a CSS keyword, cubic-bezier() or steps(); defaults to linear.")
 }).strict();
 const BoardTrackSchema$1 = object({
-	target: string().min(1).max(160),
-	property: string().min(1).max(200),
-	keyframes: array(BoardKeyframeSchema$1).min(1).max(1e5),
-	composite: _enum(["replace", "add"]).default("replace"),
+	target: string().min(1).max(160).describe("An item id, camera, or another animation id (its time property nests that timeline)."),
+	property: string().min(1).max(200).describe("JSON path in the target, e.g. position, opacity, style.fill, props.text."),
+	keyframes: array(BoardKeyframeSchema$1).min(1).max(1e5).describe("Ordered by at. The value holds before the first and after the last keyframe."),
+	composite: _enum(["replace", "add"]).default("replace").describe("replace: the latest-started track wins. add: positions and rotations add; scale and opacity multiply."),
 	interpolation: _enum([
 		"auto",
 		"step",
 		"spline"
-	]).default("auto"),
-	orient: boolean().optional()
+	]).default("auto").describe("auto blends numbers, vectors and colors and steps other values; spline smooths position paths."),
+	orient: 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",
@@ -6206,20 +6206,20 @@ const BoardTrackSchema$1 = object({
 const BoardMarkerSchema$1 = object({
 	at: nonNegative$1,
 	label: string().max(280).optional(),
-	pause: boolean().optional()
+	pause: boolean().optional().describe("Hold shared playback here until next.")
 }).strict();
 const BoardAnimationHeaderSchema$1 = object({
 	name: string().max(280).optional(),
-	duration: finite$1.positive().max(864e5),
+	duration: finite$1.positive().max(864e5).describe("Milliseconds; a new animation without it ends at its last keyframe."),
 	play: _enum([
 		"manual",
 		"auto",
 		"always"
-	]).default("manual"),
+	]).default("manual").describe("manual: only shared playback starts it. auto: plays when the Board opens. always: loops continuously."),
 	delay: nonNegative$1.default(0),
 	loop: boolean().default(false),
-	end: _enum(["hold", "reset"]).default("hold"),
-	markers: array(BoardMarkerSchema$1).max(1e4).default([])
+	end: _enum(["hold", "reset"]).default("hold").describe("hold keeps the last frame; reset returns to the start."),
+	markers: array(BoardMarkerSchema$1).max(1e4).default([]).describe("Labeled points on this timeline; a nested animation's markers do not carry over.")
 }).strict();
 BoardAnimationHeaderSchema$1.extend({ tracks: record(BoardKeySchema$1, BoardTrackSchema$1).default({}) }).strict();
 const BOARD_ENTER_PRESETS$1 = [
@@ -6237,7 +6237,7 @@ const BoardBackgroundSchema$1 = object({
 		"image"
 	]).default("dots"),
 	color: BoardColorSchema$1.optional(),
-	imageUrl: string().url().max(4096).optional(),
+	imageUrl: string().url().max(4096).optional().describe("Background image for kind image."),
 	fit: _enum([
 		"cover",
 		"contain",
@@ -6249,13 +6249,13 @@ const BoardSettingsSchema$1 = object({
 	title: string().min(1).max(255).optional(),
 	background: BoardBackgroundSchema$1.default({ kind: "dots" }),
 	grid: object({
-		visible: boolean().default(false),
+		visible: boolean().default(false).describe("Show the grid overlay."),
 		size: finite$1.min(4).max(512).default(24)
 	}).strict().optional(),
 	enter: object({
 		preset: _enum(BOARD_ENTER_PRESETS$1),
 		duration: finite$1.positive().max(1e4).optional()
-	}).strict().optional()
+	}).strict().optional().describe("Motion for items as they are added.")
 }).strict();
 const patchObject$1 = record(string(), unknown());
 const BoardPatchSchema$1 = object({
@@ -12305,13 +12305,13 @@ const placeHolderBufferData = /* @__PURE__ */ new Float32Array(1);
 const placeHolderIndexData = /* @__PURE__ */ new Uint32Array(1);
 var BatchGeometry = class extends Geometry {
 	constructor() {
-		const attributeBuffer = new Buffer$1({
+		const attributeBuffer = new Buffer({
 			data: placeHolderBufferData,
 			label: "attribute-batch-buffer",
 			usage: BufferUsage.VERTEX | BufferUsage.COPY_DST,
 			shrinkToFit: false
 		});
-		const indexBuffer = new Buffer$1({
+		const indexBuffer = new Buffer({
 			data: placeHolderIndexData,
 			label: "index-batch-buffer",
 			usage: BufferUsage.INDEX | BufferUsage.COPY_DST,
@@ -18288,19 +18288,19 @@ const _MeshGeometry = class _MeshGeometry extends Geometry {
 			3
 		]);
 		const shrinkToFit = options.shrinkBuffersToFit;
-		const positionBuffer = new Buffer$1({
+		const positionBuffer = new Buffer({
 			data: positions,
 			label: "attribute-mesh-positions",
 			shrinkToFit,
 			usage: BufferUsage.VERTEX | BufferUsage.COPY_DST
 		});
-		const uvBuffer = new Buffer$1({
+		const uvBuffer = new Buffer({
 			data: uvs,
 			label: "attribute-mesh-uvs",
 			shrinkToFit,
 			usage: BufferUsage.VERTEX | BufferUsage.COPY_DST
 		});
-		const indexBuffer = new Buffer$1({
+		const indexBuffer = new Buffer({
 			data: indices,
 			label: "index-mesh-buffer",
 			shrinkToFit,
@@ -27161,12 +27161,24 @@ function measureBoardText(props) {
 		missingCharacters: characters
 	};
 }
-function inspectBoardScene(scene, limit = 100) {
+function inspectBoardItems(scene, ids) {
+	return {
+		diagnostics: inspectBoardScene(scene, 100, ids),
+		items: scene.items.filter((item) => !ids || ids.has(item.id)).map((item) => ({
+			id: item.id,
+			bounds: item.frame,
+			worldBounds: itemBounds(item.frame),
+			opacity: scene.opacity(item.id),
+			...item.type === "text" ? { text: measureBoardText(item.props) } : {}
+		}))
+	};
+}
+function inspectBoardScene(scene, limit = 100, ids) {
 	ensureBoardTextMeasurement();
 	const diagnostics = [];
 	const texts = scene.items.filter((item) => item.type === "text" && scene.opacity(item.id) > .01);
 	const push = (entry) => {
-		if (diagnostics.length < limit) diagnostics.push(entry);
+		if (diagnostics.length < limit && (!ids || ids.has(entry.item) || Boolean(entry.related && ids.has(entry.related)))) diagnostics.push(entry);
 	};
 	for (const item of scene.items) {
 		if (diagnostics.length >= limit) break;
@@ -27178,7 +27190,7 @@ function inspectBoardScene(scene, limit = 100) {
 	let glyphBudget = 256;
 	for (const item of texts) {
 		if (diagnostics.length >= limit || item.type !== "text") break;
-		if (glyphBudget-- > 0) {
+		if ((!ids || ids.has(item.id)) && glyphBudget-- > 0) {
 			const measured = measureBoardText(item.props);
 			if (measured.missingCharacters) push({
 				code: "glyph-unavailable",
@@ -27217,6 +27229,7 @@ function inspectBoardScene(scene, limit = 100) {
 			const b = sorted[j];
 			if (!b) continue;
 			if (b.rect.x >= a.rect.x + a.rect.width) break;
+			if (ids && !ids.has(a.item.id) && !ids.has(b.item.id)) continue;
 			if (++comparisons > 1e4) return diagnostics;
 			if (a.item.parent === b.item.parent && rectsIntersect(a.rect, b.rect)) push({
 				code: "text-overlap",
@@ -30341,10 +30354,10 @@ const colorString = string().max(120).refine(isBoardColorString, "expected a pal
 const BoardColorSchema = union([colorString, object({
 	light: colorString,
 	dark: colorString
-}).strict()]);
+}).strict()]).describe("Palette token (follows the theme), CSS color, or { light, dark }.");
 const BoardStyleSchema = 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: _enum([
@@ -30352,8 +30365,8 @@ const BoardStyleSchema = object({
 		"dashed",
 		"dotted"
 	]).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 !== "..");
@@ -30369,18 +30382,18 @@ function parseBoardMediaSource(src) {
 		value: src
 	} : null;
 }
-const BoardMediaSourceSchema = 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 = 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 = object({
-	src: srcSchema.refine((path) => /\.m?js$/.test(path), "script src must be a .js or .mjs module"),
-	params: record(string(), json()).default({}),
-	targets: record(string().min(1).max(80), BoardIdSchema).default({}),
-	seed: 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: record(string(), json()).default({}).describe("Values the module reads as params."),
+	targets: record(string().min(1).max(80), BoardIdSchema).default({}).describe("Named items the module can reach, as ctx.targets."),
+	seed: string().min(1).max(160).optional().describe("Seed for ctx.random(); defaults to the item id."),
 	enabled: 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
@@ -30390,7 +30403,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: boolean().optional(),
@@ -30423,8 +30436,8 @@ object({
 	type: literal("frame"),
 	props: object({
 		label: string().max(280).default(""),
-		decoration: _enum(["frame", "none"]).optional(),
-		clip: boolean().default(true)
+		decoration: _enum(["frame", "none"]).optional().describe("none hides the title, border and background: an invisible group whose tracks move every child."),
+		clip: boolean().default(true).describe("Hide children outside the frame.")
 	}).strict().prefault({})
 }).strict();
 object({
@@ -30434,12 +30447,12 @@ object({
 		text: string().default(""),
 		fontSize: fontSize.default(24),
 		fontWeight: finite.min(100).max(900).default(500),
-		font: string().min(1).max(120).default("sans"),
+		font: string().min(1).max(120).default("sans").describe("sans, serif, mono, or a font family name."),
 		align: _enum(BOARD_TEXT_ALIGNS).default("left"),
 		lineHeight: finite.min(.5).max(4).default(4 / 3),
-		width: finite.positive().optional(),
-		reveal: ratio.default(1),
-		caret: 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: boolean().default(false).describe("Blink a caret while the text is being revealed.")
 	}).strict().prefault({})
 }).strict();
 object({
@@ -30447,7 +30460,7 @@ object({
 	type: literal("shape"),
 	props: object({
 		geometry: _enum(BOARD_SHAPE_GEOMETRIES).default("rectangle"),
-		path: string().min(1).max(2e5).optional(),
+		path: string().min(1).max(2e5).optional().describe("SVG path data for path geometry, fitted to the item size."),
 		text: string().default(""),
 		fontSize: fontSize.default(20),
 		align: _enum(BOARD_TEXT_ALIGNS).default("center")
@@ -30459,12 +30472,12 @@ object({
 const BoardDrawPointSchema = object({
 	x: finite,
 	y: finite,
-	p: ratio.default(.5)
+	p: ratio.default(.5).describe("Pen pressure.")
 }).strict();
 object({
 	...unsized,
 	type: literal("draw"),
-	props: object({ points: array(BoardDrawPointSchema).min(1).max(1e5) }).strict()
+	props: object({ points: array(BoardDrawPointSchema).min(1).max(1e5).describe("Stroke points relative to position; the size follows them.") }).strict()
 }).strict();
 const BoardArrowEndSchema = union([BoardVec2Schema, object({
 	item: BoardIdSchema,
@@ -30483,9 +30496,9 @@ const BoardArrowEndSchema = union([BoardVec2Schema, object({
 			x: ratio,
 			y: ratio
 		}).strict()
-	]).default("auto"),
+	]).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: string().min(1).max(120).optional()
-}).strict()]);
+}).strict()]).describe("A point relative to position, or { item } to follow that item.");
 const BOARD_ARROW_ROUTES = [
 	"straight",
 	"curve",
@@ -30498,13 +30511,13 @@ object({
 		start: BoardArrowEndSchema,
 		end: BoardArrowEndSchema,
 		route: _enum(BOARD_ARROW_ROUTES).default("straight"),
-		bend: finite.min(-.85).max(.85).default(0),
-		waypoints: 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: array(BoardVec2Schema).max(64).default([]).describe("Points the route passes through."),
 		arrowStart: boolean().default(false),
 		arrowEnd: boolean().default(true),
 		label: string().max(280).default(""),
 		fontSize: fontSize.default(14),
-		relation: string().max(64).regex(/^[a-z0-9]+(?:[.-][a-z0-9]+)*$/, "relation must be a lowercase slug").optional()
+		relation: 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 = {
@@ -30520,26 +30533,26 @@ const fileProps = {
 		excerpt: string().optional(),
 		coverPath: string().optional(),
 		coverUrl: string().optional()
-	}).strict().optional()
+	}).strict().describe("Cached facts for an instant preview; filled in when the media loads.").optional()
 };
 const BoardMediaOriginSchema = object({
 	taskRunId: string().min(1).max(160),
 	artifactId: 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 = 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.");
 object({
 	...boxed(640, 360),
 	type: literal("image"),
@@ -30619,8 +30632,8 @@ object({
 	...boxed(420, 240),
 	type: literal("task"),
 	props: object({
-		taskRunId: string().min(1).max(160),
-		snapshot: BoardTaskSnapshotSchema.describe("Maintained by the server for tasks in the Board's Space; writers may omit it.")
+		taskRunId: 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 = [
@@ -30643,8 +30656,8 @@ object({
 		spread: finite.min(0).max(360).default(360),
 		gravity: finite.default(0),
 		intensity: nonNegative.max(10).default(1),
-		follow: BoardIdSchema.optional(),
-		seed: string().min(1).max(160).optional()
+		follow: BoardIdSchema.optional().describe("trail: the item to follow."),
+		seed: string().min(1).max(160).optional().describe("Makes procedural motion repeatable.")
 	}).strict()
 }).strict();
 object({
@@ -30684,21 +30697,21 @@ function isBoardEase(value) {
 }
 const BoardEaseSchema = string().max(120).refine(isBoardEase, "expected a CSS easing: linear, ease-in-out, cubic-bezier(…) or steps(…)");
 const BoardKeyframeSchema = object({
-	at: nonNegative,
+	at: nonNegative.describe("Time in milliseconds."),
 	value: 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 = object({
-	target: string().min(1).max(160),
-	property: string().min(1).max(200),
-	keyframes: array(BoardKeyframeSchema).min(1).max(1e5),
-	composite: _enum(["replace", "add"]).default("replace"),
+	target: string().min(1).max(160).describe("An item id, camera, or another animation id (its time property nests that timeline)."),
+	property: string().min(1).max(200).describe("JSON path in the target, e.g. position, opacity, style.fill, props.text."),
+	keyframes: array(BoardKeyframeSchema).min(1).max(1e5).describe("Ordered by at. The value holds before the first and after the last keyframe."),
+	composite: _enum(["replace", "add"]).default("replace").describe("replace: the latest-started track wins. add: positions and rotations add; scale and opacity multiply."),
 	interpolation: _enum([
 		"auto",
 		"step",
 		"spline"
-	]).default("auto"),
-	orient: boolean().optional()
+	]).default("auto").describe("auto blends numbers, vectors and colors and steps other values; spline smooths position paths."),
+	orient: 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",
@@ -30713,20 +30726,20 @@ const BoardTrackSchema = object({
 const BoardMarkerSchema = object({
 	at: nonNegative,
 	label: string().max(280).optional(),
-	pause: boolean().optional()
+	pause: boolean().optional().describe("Hold shared playback here until next.")
 }).strict();
 object({
 	name: string().max(280).optional(),
-	duration: finite.positive().max(864e5),
+	duration: finite.positive().max(864e5).describe("Milliseconds; a new animation without it ends at its last keyframe."),
 	play: _enum([
 		"manual",
 		"auto",
 		"always"
-	]).default("manual"),
+	]).default("manual").describe("manual: only shared playback starts it. auto: plays when the Board opens. always: loops continuously."),
 	delay: nonNegative.default(0),
 	loop: boolean().default(false),
-	end: _enum(["hold", "reset"]).default("hold"),
-	markers: array(BoardMarkerSchema).max(1e4).default([])
+	end: _enum(["hold", "reset"]).default("hold").describe("hold keeps the last frame; reset returns to the start."),
+	markers: array(BoardMarkerSchema).max(1e4).default([]).describe("Labeled points on this timeline; a nested animation's markers do not carry over.")
 }).strict().extend({ tracks: record(BoardKeySchema, BoardTrackSchema).default({}) }).strict();
 const BOARD_ENTER_PRESETS = [
 	"fade-in",
@@ -30743,7 +30756,7 @@ const BoardBackgroundSchema = object({
 		"image"
 	]).default("dots"),
 	color: BoardColorSchema.optional(),
-	imageUrl: string().url().max(4096).optional(),
+	imageUrl: string().url().max(4096).optional().describe("Background image for kind image."),
 	fit: _enum([
 		"cover",
 		"contain",
@@ -30755,13 +30768,13 @@ object({
 	title: string().min(1).max(255).optional(),
 	background: BoardBackgroundSchema.default({ kind: "dots" }),
 	grid: object({
-		visible: boolean().default(false),
+		visible: boolean().default(false).describe("Show the grid overlay."),
 		size: finite.min(4).max(512).default(24)
 	}).strict().optional(),
 	enter: object({
 		preset: _enum(BOARD_ENTER_PRESETS),
 		duration: finite.positive().max(1e4).optional()
-	}).strict().optional()
+	}).strict().optional().describe("Motion for items as they are added.")
 }).strict();
 const patchObject = record(string(), unknown());
 object({
@@ -31338,13 +31351,24 @@ function renderBoardExport(renderer, input, options = {}) {
 		backgroundImage: options.backgroundImage
 	});
 	try {
-		const canvas = renderer.extract.canvas({
+		const texture = renderer.textureGenerator.generateTexture({
 			target: exportScene.root,
 			frame: new Rectangle(0, 0, plan.width, plan.height),
 			resolution: 1,
 			antialias: true,
 			clearColor: options.background === "transparent" ? void 0 : palette.bg
 		});
+		let canvas;
+		const surface = renderer.type === RendererType.CANVAS ? texture.source.resource : void 0;
+		try {
+			canvas = renderer.texture.generateCanvas(texture);
+		} finally {
+			texture.destroy(true);
+			if (surface) {
+				surface.width = 1;
+				surface.height = 1;
+			}
+		}
 		const warnings = [];
 		if (plan.clamped) warnings.push({
 			kind: "scale-clamped",
@@ -31369,11 +31393,55 @@ function renderBoardExport(renderer, input, options = {}) {
 	}
 }
 //#endregion
+//#region ../sdk/src/board/export/node/fonts.ts
+function initializeBoardFonts(registry, fonts) {
+	for (const font of fonts) registry.registerFromPath(font.path, font.family);
+	if (!registry.setAlias) return;
+	for (const [alias, candidates] of Object.entries({
+		"system-ui": [
+			"Noto Sans",
+			"DejaVu Sans",
+			"Liberation Sans",
+			"FreeSans",
+			"Helvetica Neue",
+			"Arial",
+			"Segoe UI"
+		],
+		"sans-serif": [
+			"Geist",
+			"Noto Sans",
+			"DejaVu Sans",
+			"Liberation Sans",
+			"FreeSans",
+			"Arial"
+		],
+		serif: [
+			"Noto Serif",
+			"DejaVu Serif",
+			"Liberation Serif",
+			"FreeSerif",
+			"Times New Roman"
+		],
+		monospace: [
+			"Geist Mono",
+			"DejaVu Sans Mono",
+			"Liberation Mono",
+			"FreeMono",
+			"Courier New"
+		]
+	})) {
+		if (registry.has(alias)) continue;
+		const family = candidates.find((name) => registry.has(name));
+		if (family) registry.setAlias(family, alias);
+	}
+}
+//#endregion
 //#region ../sdk/src/board/export/node/scripts.ts
 const WORKER = `
 const {parentPort, workerData} = require('node:worker_threads');
 const {createContext, Script, SourceTextModule} = require('node:vm');
-const {createCanvas} = require(workerData.canvasModule);
+const {createCanvas, GlobalFonts} = require(workerData.canvasModule);
+(${initializeBoardFonts.toString()})(GlobalFonts, workerData.fonts);
 const instances = new Map();
 const graphs = new Map();
 const update = new Script('__runtime.update(JSON.parse(__inputJson)); __runtime.step(__time)');
@@ -31382,7 +31450,10 @@ const output = new Script('JSON.stringify(__runtime.output())');
 const dispose = new Script('__runtime.destroy()');
 function release(id) {
  const entry=instances.get(id);instances.delete(id);
- if(entry) {try {dispose.runInContext(entry.context,{timeout:workerData.timeout});} catch {}}
+ if(entry) {
+  try {dispose.runInContext(entry.context,{timeout:workerData.timeout});} catch {}
+  if(entry.canvas) {entry.canvas.width=1;entry.canvas.height=1;}
+ }
 }
 async function create(data) {
  const context = createContext({console:{log(){},warn(){},error(){}},structuredClone},{codeGeneration:{strings:false,wasm:false}});
@@ -31432,22 +31503,29 @@ parentPort.on('message',async data=>{
    const width=Math.max(1,Math.round(data.input.width*data.scale));
    const height=Math.max(1,Math.round(data.input.height*data.scale));
    const canvas=entry.canvas??=createCanvas(width,height);
-   canvas.width=width;canvas.height=height;
-   const drawing=canvas.getContext('2d');drawing.scale(data.scale,data.scale);
-   context.__drawing=drawing;draw.runInContext(context,{timeout:workerData.timeout});
-   png=canvas.toBuffer('image/png');delete context.__drawing;
+   if(canvas.width!==width || canvas.height!==height) {canvas.width=width;canvas.height=height;}
+   const drawing=canvas.getContext('2d');drawing.reset();drawing.scale(data.scale,data.scale);
+   context.__drawing=drawing;
+   try {
+    draw.runInContext(context,{timeout:workerData.timeout});
+    png=canvas.toBuffer('image/png');
+   } finally {
+    delete context.__drawing;canvas.width=1;canvas.height=1;
+   }
   }
   parentPort.postMessage({png,output:JSON.parse(output.runInContext(context,{timeout:workerData.timeout}))});
- } catch(error) { instances.delete(data.input?.id);parentPort.postMessage({error:String(error.stack||error)}); }
+ } catch(error) { release(data.input?.id);parentPort.postMessage({error:String(error.stack||error)}); }
 });
 `;
 function createNodeBoardScriptHost(renderer, options) {
+	const concurrency = options.concurrency ?? 4;
+	if (!Number.isSafeInteger(concurrency) || concurrency < 1 || concurrency > 4) throw new Error("Script concurrency must be an integer between 1 and 4.");
 	const textures = /* @__PURE__ */ new Map();
 	const outputs = /* @__PURE__ */ new Map();
 	const errors = /* @__PURE__ */ new Map();
 	const sources = /* @__PURE__ */ new Map();
 	const modules = createBoardScriptModuleReader(options.readModule, options.readTimeoutMs);
-	const lanes = Array.from({ length: 4 }, () => ({
+	const lanes = Array.from({ length: concurrency }, () => ({
 		worker: null,
 		tail: Promise.resolve(),
 		graphs: /* @__PURE__ */ new Set()
@@ -31488,6 +31566,7 @@ function createNodeBoardScriptHost(renderer, options) {
 				workerData: {
 					runtime: createScriptRuntime.toString(),
 					timeout,
+					fonts: renderer.fonts ?? [],
 					canvasModule: fileURLToPath(import.meta.resolve("@napi-rs/canvas"))
 				}
 			});
@@ -31621,20 +31700,6 @@ function createNodeBoardScriptHost(renderer, options) {
 }
 //#endregion
 //#region ../sdk/src/board/export/node/index.ts
-const SYSTEM_UI_FAMILIES = [
-	"Noto Sans",
-	"DejaVu Sans",
-	"Liberation Sans",
-	"FreeSans",
-	"Helvetica Neue",
-	"Arial",
-	"Segoe UI"
-];
-function aliasSystemUi(fonts) {
-	if (!fonts.setAlias || fonts.has("system-ui")) return;
-	const family = SYSTEM_UI_FAMILIES.find((name) => fonts.has(name));
-	if (family) fonts.setAlias(family, "system-ui");
-}
 const WEBGL_PROBE_STUB = {
 	getShaderPrecisionFormat: () => ({
 		precision: 1,
@@ -31681,8 +31746,11 @@ function installAnimationFrameShim() {
 async function createNodeBoardRenderer(options = {}) {
 	const canvasModule = options.canvasModule ?? await loadCanvasModule();
 	extensions.add(CanvasGraphicsPipe, GraphicsPipe, CanvasGraphicsContextSystem, GraphicsContextSystem, CanvasRendererTextSystem, CanvasTextSystem, CanvasTextPipe);
-	for (const font of options.fonts ?? []) canvasModule.GlobalFonts.registerFromPath(font.path, font.family ?? "Geist");
-	aliasSystemUi(canvasModule.GlobalFonts);
+	const fonts = (options.fonts ?? []).map((font) => ({
+		...font,
+		family: font.family ?? "Geist"
+	}));
+	initializeBoardFonts(canvasModule.GlobalFonts, fonts);
 	function createCanvas(width = 1, height = 1) {
 		const canvas = canvasModule.createCanvas(Math.max(1, Math.ceil(width)), Math.max(1, Math.ceil(height)));
 		const nativeGetContext = canvas.getContext.bind(canvas);
@@ -31719,14 +31787,16 @@ async function createNodeBoardRenderer(options = {}) {
 	return {
 		renderer,
 		canvasModule,
-		decodeImage: async (bytes, mimeType = "image/png") => {
+		fonts,
+		decodeImage: async (bytes) => {
 			const image = new canvasModule.Image();
-			const base64 = Buffer.from(bytes).toString("base64");
 			await new Promise((resolve, reject) => {
 				image.onload = () => resolve();
 				image.onerror = (error) => reject(error);
-				image.src = `data:${mimeType};base64,${base64}`;
+				image.src = bytes;
 			});
+			image.onload = void 0;
+			image.onerror = void 0;
 			return new Texture({ source: new ImageSource({
 				resource: image,
 				width: image.width,
@@ -31760,7 +31830,7 @@ function exportBoardImageBytes(renderer, document, options = {}) {
 	try {
 		const bytes = format === "png" ? canvas.toBuffer(MIME.png) : canvas.toBuffer(MIME[format], Math.round(quality * 100));
 		return {
-			bytes: new Uint8Array(bytes),
+			bytes: new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength),
 			plan: result.plan,
 			warnings: result.warnings,
 			format
@@ -31771,4 +31841,4 @@ function exportBoardImageBytes(renderer, document, options = {}) {
 	}
 }
 //#endregion
-export { BOARD_SCRIPT_DRAWING_EXAMPLE, boardDocumentAt, boardImageKeySource, boardPathTrack, boardSequence, boardSequencePatch, buildBoardScene, createBoardAnimationSampler, createBoardRenderSampler, createNodeBoardRenderer, createNodeBoardScriptHost, exportBoardImageBytes, hasBoardScripts, imageAssetKey, inspectBoardScene, measureBoardText, parseBoardDocument, planBoardExport, prepareBoardExport, selectBoardExportAssets };
+export { BOARD_SCRIPT_DRAWING_EXAMPLE, boardDocumentAt, boardImageKeySource, boardPathTrack, boardSequence, boardSequencePatch, buildBoardScene, createBoardAnimationSampler, createBoardRenderSampler, createNodeBoardRenderer, createNodeBoardScriptHost, exportBoardImageBytes, hasBoardScripts, imageAssetKey, inspectBoardItems, inspectBoardScene, measureBoardText, parseBoardDocument, planBoardExport, prepareBoardExport, selectBoardExportAssets };