@neta-art/cohub-cli 10.2.0 → 10.3.0

package/README.md

@@ -452,8 +452,16 @@ cohub apps resolve <appSlug> --owner <username> --space-slug <spaceSlug>
 
 Use `--json` for machine-readable output. `apps get`, `apps stats`, and `apps download` also accept `app://<username>/<space>/<app>` mention URIs. `apps stats` reports total, 24-hour, 7-day, and 30-day views with a source breakdown. Download restores newly published file and directory artifacts directly from the CDN with checksum verification. HTML files with companion assets are restored as directory bundles; Board and port apps are not downloadable. The resolve command remains available for explicit slug-based lookup.
 
-Realtime rooms use a published App's runtime identity, so they are available
-through `client.app.realtime` in the SDK rather than as CLI commands.
+Agents can join hosted Rooms and attach realtime events or media:
+
+```bash
+cohub rooms join '<invite>'
+cohub rooms connect <room-id> --json
+cohub rooms rtc <room-id> --channel chat --data-input -
+cohub rooms rtc <room-id> --audio speech.pcm --output ./received
+```
+
+RTC uses an on-demand Go/Pion helper, with external FFmpeg only when media conversion is needed. Encoded Ogg Opus and VP8 IVF inputs avoid re-encoding. Reception defaults to framed RTP archives; `--receive-format raw` decodes PCM/I420 for models. `--output -` writes binary frames to stdout and status to stderr. Recording is explicit, files are never overwritten, and the default receive quota is 1 GiB. Disconnecting keeps the hosted seat. See [Room RTC helper](../../apps/sandbox/cmd/cohub-rtc/README.md) for local builds, formats, migration details, and release prerequisites.
 
 ## Drive the Cohub UI
 

package/dist/board-kernel.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({
@@ -30341,10 +30341,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 +30352,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 +30369,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 +30390,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 +30423,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 +30434,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 +30447,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 +30459,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 +30483,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 +30498,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 +30520,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 +30619,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 +30643,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 +30684,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 +30713,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 +30743,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 +30755,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({

package/dist/commands/boards.js

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import { mkdir } from "node:fs/promises";
 import { dirname } from "node:path";
-import { BOARD_PRESET_NAMES, BOARD_SCHEMA_TARGETS, boardJsonSchema, boardPresetTracks, boardSchemaOverview, isBoardPresetName, listBoardPresets, } from "@neta-art/cohub/board";
+import { BOARD_PRESET_NAMES, BOARD_SCHEMA_TARGETS, BOARD_SCRIPT_API, boardJsonSchema, boardPresetTracks, boardSchemaOverview, isBoardPresetName, listBoardPresets, } from "@neta-art/cohub/board";
 import { BOARD_CREATE_INPUT_MAX_BYTES, BOARD_TRANSACTION_INPUT_MAX_BYTES, parseBoardJsonObject, readBoardJsonObject, resolveBoardId, writeBoardOutput, } from "../board-command-support.js";
 import { formatBoardTime, parseBoardTime, parseBoardTimes } from "../board-time.js";
 import { createClient, createRealtimeClient } from "../client.js";
@@ -283,13 +283,18 @@ export function registerBoards(program) {
         .description("Read, write, animate and export Boards (by id or .board path)")
         .addHelpText("after", `
 A Board is one JSON document: { board, items, animations }.
-  get      read it
-  apply    write it with a JSON Merge Patch; null deletes
-  schema   the schema of any part, and what tracks can animate
-  preset   tracks for a preset motion, ready to apply
-  history  list versions, or restore one
-  export   render an image, a frame sequence or a video
-  examples starter documents
+  get       read it
+  apply     write it with a JSON Merge Patch; null deletes
+  schema    the fields of any part and what they mean; also the script API
+  examples  starter documents and a custom script module
+  preset    tracks for a preset motion, ready to apply
+  sequence  join chapter animations into one timeline
+  path      sample a polyline into a position track
+  inspect   measure items and report layout hints
+  export    render an image, a frame sequence or a video
+  play      shared playback; also pause, resume, next, seek, stop
+  watch     stream changes and playback
+  history   list versions, or restore one
 Times are milliseconds; 500ms, 12.5s and 2m also work on the command line.`);
     withJson(boards.command("create <path>")
         .description("Create a Board file, optionally with an initial document")
@@ -444,9 +449,9 @@ Times are milliseconds; 500ms, 12.5s and 2m also work on the command line.`);
     boards.command("schema [target]")
         .description("Print JSON Schema for a part of a Board")
         .addHelpText("after", `
-With a target: one item type, or animation, track, or camera.
-Targets: ${BOARD_SCHEMA_TARGETS.join(", ")}
-Without a target: units, item types, colors and every animatable property.`)
+Without a target: units, item types, colors and every animatable property.
+With a target: its fields and what they mean; script also lists the module API.
+Targets: ${BOARD_SCHEMA_TARGETS.join(", ")}`)
         .action((target) => {
         try {
             if (!target)
@@ -454,7 +459,7 @@ Without a target: units, item types, colors and every animatable property.`)
             const schema = boardJsonSchema(target);
             if (!schema)
                 throw new Error(`Unknown target ${target}; expected ${BOARD_SCHEMA_TARGETS.join(", ")}.`);
-            outJson(schema);
+            outJson(target === "script" ? { ...schema, api: BOARD_SCRIPT_API } : schema);
         }
         catch (cause) {
             handleHttp(cause);

package/dist/commands/rooms-connect.d.ts

@@ -0,0 +1,17 @@
+import type { Readable } from "node:stream";
+type Input = {
+    op: "publish" | "send";
+    type: string;
+    data: unknown;
+} | {
+    op: "presence";
+    presence: Record<string, unknown> | null;
+};
+export declare function parseRoomInput(line: string): Input;
+export declare function readRoomLines(input: Readable, maxBytes?: number): AsyncGenerator<string>;
+export declare function connectToRoom(roomId: string, options: {
+    after?: string;
+    input?: boolean;
+    json: boolean;
+}): Promise<void>;
+export {};

package/dist/commands/rooms-connect.js

@@ -0,0 +1,140 @@
+import { createRealtimeClient } from "../client.js";
+const MAX_LINE_BYTES = 20 * 1024;
+const MAX_OUTPUT_BUFFER_BYTES = 1024 * 1024;
+export function parseRoomInput(line) {
+    if (Buffer.byteLength(line) > MAX_LINE_BYTES)
+        throw new Error("Room input line is too large");
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch {
+        throw new Error("Room input must be JSON");
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Room input must be an object");
+    const input = value;
+    if (input.op === "presence" && (input.presence === null || typeof input.presence === "object" && !Array.isArray(input.presence))) {
+        return { op: "presence", presence: input.presence };
+    }
+    if ((input.op === "publish" || input.op === "send") && typeof input.type === "string" && "data" in input) {
+        return { op: input.op, type: input.type, data: input.data };
+    }
+    throw new Error("Use {\"op\":\"publish|send\",\"type\":\"name\",\"data\":...} or {\"op\":\"presence\",\"presence\":...}");
+}
+export async function* readRoomLines(input, maxBytes = MAX_LINE_BYTES) {
+    let pending = Buffer.alloc(0);
+    for await (const chunk of input) {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        let start = 0;
+        for (;;) {
+            const end = bytes.indexOf(10, start);
+            const part = bytes.subarray(start, end < 0 ? bytes.length : end);
+            if (pending.length + part.length > maxBytes)
+                throw new Error("Room input line is too large");
+            pending = pending.length ? Buffer.concat([pending, part]) : part;
+            if (end < 0)
+                break;
+            yield pending.toString("utf8").replace(/\r$/, "");
+            pending = Buffer.alloc(0);
+            start = end + 1;
+        }
+    }
+    if (pending.length)
+        yield pending.toString("utf8");
+}
+export async function connectToRoom(roomId, options) {
+    const after = options.after === undefined ? undefined : Number(options.after);
+    if (after !== undefined && (!Number.isSafeInteger(after) || after < 0))
+        throw new Error("--after must be a non-negative sequence number");
+    const client = createRealtimeClient();
+    let room = null;
+    let stopped = false;
+    let finish;
+    const done = new Promise((resolve) => { finish = resolve; });
+    const stop = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        finish();
+    };
+    const write = (kind, value) => {
+        if (stopped)
+            return;
+        if (process.stdout.writableLength > MAX_OUTPUT_BUFFER_BYTES) {
+            process.stderr.write("Room output is too slow; disconnecting.\n");
+            process.exitCode = 1;
+            stop();
+            return;
+        }
+        process.stdout.write(options.json ? `${JSON.stringify({ kind, ...value })}\n` : `${kind}: ${JSON.stringify(value)}\n`);
+    };
+    const onSignal = () => { stop(); void room?.disconnect().catch(() => undefined); void client.disconnect(); };
+    process.once("SIGINT", onSignal);
+    process.once("SIGTERM", onSignal);
+    let inputTask = null;
+    try {
+        room = await client.rooms.connect(roomId, {
+            after,
+            onRoom: (active) => {
+                room = active;
+                if (stopped) {
+                    void active.disconnect();
+                    return;
+                }
+                active.subscribeAll((event) => write("event", { event }));
+                active.onMembersChanged((members) => write("members", { members }));
+                active.onOutOfSync((from, to) => write("gap", { from, to }));
+                active.onSendError((failure) => write("error", { message: failure.message }));
+                active.onStateChange((state) => {
+                    write("state", { state });
+                    if (state === "closed" || state === "expired")
+                        stop();
+                });
+            },
+        });
+        if (!stopped)
+            write("connected", { roomId, participantId: room.participantId, sequence: room.sequence });
+        if (!stopped && options.input) {
+            const active = room;
+            inputTask = (async () => {
+                let lineNumber = 0;
+                for await (const line of readRoomLines(process.stdin)) {
+                    if (stopped)
+                        break;
+                    lineNumber++;
+                    if (!line.trim())
+                        continue;
+                    try {
+                        const input = parseRoomInput(line);
+                        if (input.op === "presence")
+                            await active.setPresence(input.presence);
+                        else if (input.op === "send")
+                            active.send(input.type, input.data);
+                        else {
+                            const result = await active.publish(input.type, input.data);
+                            write("ack", { line: lineNumber, sequence: result.sequence, eventId: result.eventId });
+                        }
+                    }
+                    catch (cause) {
+                        write("input_error", { line: lineNumber, message: cause instanceof Error ? cause.message : String(cause) });
+                    }
+                }
+            })().catch((cause) => {
+                write("input_error", { message: cause instanceof Error ? cause.message : String(cause) });
+                process.exitCode = 1;
+                stop();
+            });
+        }
+        await done;
+    }
+    finally {
+        if (options.input)
+            process.stdin.destroy();
+        await room?.disconnect().catch(() => undefined);
+        await client.disconnect();
+        await inputTask?.catch(() => undefined);
+        process.removeListener("SIGINT", onSignal);
+        process.removeListener("SIGTERM", onSignal);
+    }
+}

package/dist/commands/rooms-rtc-binary.d.ts

@@ -0,0 +1,2 @@
+export declare const RTC_HELPER_VERSION: string;
+export declare function ensureRtcBinary(local?: string): Promise<string>;

package/dist/commands/rooms-rtc-binary.js

@@ -0,0 +1,107 @@
+import { createHash } from "node:crypto";
+import { createReadStream, createWriteStream } from "node:fs";
+import { chmod, lstat, mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { createGunzip } from "node:zlib";
+// Pin a global release tag after its helper artifacts are published.
+export const RTC_HELPER_VERSION = "v2.67.0";
+const MAX_BINARY_BYTES = 128 * 1024 * 1024;
+async function digest(path) {
+    const hash = createHash("sha256");
+    await pipeline(createReadStream(path), hash);
+    return hash.digest("hex");
+}
+async function readText(response, limit) {
+    if (!response.body)
+        throw new Error("Empty RTC helper response");
+    const reader = response.body.getReader();
+    const parts = [];
+    let bytes = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            bytes += value.length;
+            if (bytes > limit)
+                throw new Error("RTC helper metadata exceeds the size limit");
+            parts.push(value);
+        }
+    }
+    finally {
+        await reader.cancel();
+    }
+    return Buffer.concat(parts).toString("utf8");
+}
+export async function ensureRtcBinary(local) {
+    const override = local || process.env.COHUB_RTC_BIN?.trim();
+    if (override) {
+        if (!(await lstat(override)).isFile())
+            throw new Error("RTC helper must be a regular file");
+        return resolve(override);
+    }
+    const platform = { linux: "linux", darwin: "darwin" }[process.platform];
+    const arch = { x64: "amd64", arm64: "arm64" }[process.arch];
+    if (!platform || !arch)
+        throw new Error("Unsupported RTC helper platform; use --helper with a local binary");
+    const version = process.env.COHUB_RTC_VERSION?.trim() || RTC_HELPER_VERSION;
+    if (!version)
+        throw new Error("No RTC helper release is pinned yet; use --helper or COHUB_RTC_VERSION with a published global release");
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/.test(version))
+        throw new Error("Invalid RTC helper version");
+    const directory = join(homedir(), ".cache", "cohub", "rtc", version, `${platform}-${arch}`);
+    const binary = join(directory, "cohub-rtc");
+    const checksum = `${binary}.sha256`;
+    const expected = await readFile(checksum, "utf8").catch(() => "");
+    if (/^[a-f0-9]{64}$/.test(expected) && (await lstat(binary).catch(() => null))?.isFile() && await digest(binary) === expected)
+        return binary;
+    await mkdir(directory, { recursive: true });
+    const temporary = await mkdtemp(join(directory, ".download-"));
+    const base = (process.env.COHUB_RTC_CDN_BASE_URL?.trim() || "https://public.cohub.live/rtc").replace(/\/+$/, "");
+    const url = `${base}/${version}/cohub-rtc_${platform}_${arch}.gz`;
+    const signal = AbortSignal.timeout(120_000);
+    try {
+        const manifest = await fetch(`${url}.sha256`, { signal });
+        if (!manifest.ok)
+            throw new Error(`RTC helper ${version} is unavailable (${manifest.status}); use --helper with a locally built cohub-rtc`);
+        const text = await readText(manifest, 1024);
+        const expectedArchive = text.trim().split(/\s+/)[0];
+        if (!expectedArchive || !/^[a-f0-9]{64}$/.test(expectedArchive))
+            throw new Error("Invalid RTC helper checksum");
+        const response = await fetch(url, { signal });
+        if (!response.ok || !response.body)
+            throw new Error(`RTC helper download failed (${response.status})`);
+        let bytes = 0;
+        const bound = () => new Transform({ transform(chunk, _encoding, done) {
+                bytes += chunk.length;
+                done(bytes > MAX_BINARY_BYTES ? new Error("RTC helper exceeds the size limit") : null, chunk);
+            } });
+        const archive = join(temporary, "archive.gz");
+        await pipeline(Readable.fromWeb(response.body), bound(), createWriteStream(archive, { flags: "wx" }), { signal });
+        if (await digest(archive) !== expectedArchive)
+            throw new Error("RTC helper checksum mismatch");
+        for (const name of ["LICENSE", "NOTICE"]) {
+            const response = await fetch(`${base}/${version}/${name}`, { signal });
+            if (!response.ok)
+                throw new Error(`RTC helper ${name} is unavailable (${response.status})`);
+            const text = await readText(response, 64 * 1024);
+            await writeFile(join(temporary, name), text, { flag: "wx" });
+            await rename(join(temporary, name), join(directory, name));
+        }
+        const extracted = join(temporary, "cohub-rtc");
+        bytes = 0;
+        await pipeline(createReadStream(archive), createGunzip(), bound(), createWriteStream(extracted, { flags: "wx", mode: 0o700 }), { signal });
+        await chmod(extracted, 0o700);
+        const hash = await digest(extracted);
+        await writeFile(join(temporary, "checksum"), hash, { flag: "wx" });
+        await rename(extracted, binary);
+        await rename(join(temporary, "checksum"), checksum);
+        return binary;
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true });
+    }
+}

package/dist/commands/rooms-rtc.d.ts

@@ -0,0 +1,21 @@
+export type RtcOptions = {
+    helper?: string;
+    audio?: string;
+    video?: string;
+    audioFormat: "pcm" | "opus";
+    videoFormat: "i420" | "vp8";
+    size?: string;
+    fps: string;
+    rate: string;
+    channels: string;
+    output?: string;
+    receiveFormat: "rtp" | "raw";
+    receiveSize: string;
+    maxBytes: string;
+    participant?: string;
+    channel?: string;
+    delivery: "reliable" | "latest";
+    dataInput?: string;
+    json?: boolean;
+};
+export declare function runRoomRtc(roomId: string, options: RtcOptions): Promise<void>;

package/dist/commands/rooms-rtc.js

@@ -0,0 +1,171 @@
+import { spawn } from "node:child_process";
+import { HttpError } from "@neta-art/cohub";
+import { createRealtimeClient } from "../client.js";
+import { readRoomLines } from "./rooms-connect.js";
+import { ensureRtcBinary } from "./rooms-rtc-binary.js";
+export async function runRoomRtc(roomId, options) {
+    if (options.delivery !== "reliable" && options.delivery !== "latest")
+        throw new Error("--delivery must be reliable or latest");
+    if (options.dataInput && !options.channel)
+        throw new Error("--data-input requires --channel");
+    if ([options.audio, options.video, options.dataInput].filter((value) => value === "-").length > 1)
+        throw new Error("Only one input can use stdin");
+    const maxBytes = Number(options.maxBytes);
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 0)
+        throw new Error("--max-bytes must be a non-negative safe integer");
+    const client = createRealtimeClient();
+    const sessions = new Set();
+    const pending = new Set();
+    let room;
+    let helper;
+    let control;
+    let exit;
+    let killTimer;
+    let stopped = false;
+    let failure;
+    const stop = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        helper?.kill("SIGTERM");
+        if (helper)
+            killTimer = setTimeout(() => helper?.kill("SIGKILL"), 5_000);
+    };
+    const fail = (cause) => { failure ??= cause; stop(); };
+    const send = (value) => {
+        if (!control || control.destroyed || stopped)
+            return;
+        const line = `${JSON.stringify(value)}\n`;
+        if (Buffer.byteLength(line) > 256 * 1024 || control.writableLength > 1024 * 1024)
+            throw new Error("RTC control input is too slow or too large");
+        control.write(line);
+    };
+    let previousMembers = "";
+    const report = (value) => {
+        const output = options.output === "-" ? process.stderr : process.stdout;
+        if (output.writableLength > 1024 * 1024)
+            throw new Error("RTC output is too slow");
+        output.write(`${JSON.stringify(value)}\n`);
+    };
+    const release = async (sessionId) => {
+        if (!sessions.has(sessionId))
+            return;
+        await client.rooms.signalRtc(roomId, { method: "DELETE", path: `/${sessionId}` });
+        sessions.delete(sessionId);
+    };
+    const request = async (message) => {
+        try {
+            if (!["GET", "POST", "PUT", "PATCH", "DELETE"].includes(message.method))
+                throw new Error("Invalid RTC signaling method");
+            const opening = message.method === "POST" && message.path === "";
+            const body = await client.rooms.signalRtc(roomId, {
+                method: message.method,
+                path: message.path,
+                body: opening ? { ticket: "hosted", participantId: room?.participantId } : message.method === "GET" ? undefined : message.body,
+            });
+            if (opening && body.sessionId)
+                sessions.add(body.sessionId);
+            if (message.method === "GET" && room) {
+                const snapshot = await client.rooms.get(roomId);
+                send({ kind: "members", body: snapshot.members.map(({ participantId, publications }) => ({ participantId, publications })) });
+                previousMembers = "";
+            }
+            send({ kind: "response", id: message.id, body });
+        }
+        catch (cause) {
+            send({ kind: "response", id: message.id, error: cause instanceof Error ? cause.message : String(cause), code: cause instanceof HttpError ? cause.code : "RTC_FAILED" });
+        }
+    };
+    const track = (task) => {
+        pending.add(task);
+        void task.catch(fail).finally(() => pending.delete(task));
+    };
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+    process.stdout.on("error", fail);
+    process.stderr.on("error", fail);
+    try {
+        const binary = await ensureRtcBinary(options.helper);
+        if (stopped)
+            return;
+        room = await client.rooms.connect(roomId);
+        if (stopped)
+            return;
+        room.onStateChange((state) => {
+            try {
+                report({ kind: "room", state });
+            }
+            catch (cause) {
+                fail(cause);
+            }
+            if (state === "closed" || state === "expired")
+                stop();
+        });
+        helper = spawn(binary, [], { stdio: ["inherit", "inherit", "inherit", "pipe", "pipe"] });
+        control = helper.stdio[3];
+        const events = helper.stdio[4];
+        control.on("error", fail);
+        exit = new Promise((resolve, reject) => {
+            helper?.once("error", reject);
+            helper?.once("close", (code, signal) => {
+                if (killTimer)
+                    clearTimeout(killTimer);
+                if (code === 0 || stopped && signal === "SIGTERM")
+                    resolve();
+                else
+                    reject(new Error(`RTC helper exited with ${signal ?? code}`));
+            });
+        });
+        void exit.catch(fail);
+        send({ protocol: 1, ...options, maxBytes, participantId: room.participantId });
+        const updateMembers = () => {
+            const body = room?.members.map(({ participantId, publications }) => ({ participantId, publications }));
+            const next = JSON.stringify(body);
+            if (next === previousMembers)
+                return;
+            send({ kind: "members", body });
+            previousMembers = next;
+        };
+        room.onMembersChanged(() => { try {
+            updateMembers();
+        }
+        catch (cause) {
+            fail(cause);
+        } });
+        updateMembers();
+        report({ kind: "connected", roomId, participantId: room.participantId });
+        for await (const line of readRoomLines(events, 256 * 1024)) {
+            const message = JSON.parse(line);
+            if (message.kind === "request") {
+                if (pending.size >= 16)
+                    throw new Error("Too many pending RTC requests");
+                track(request(message));
+            }
+            else if (message.kind === "release") {
+                await release(message.sessionId);
+            }
+            else
+                report(message);
+        }
+        await exit;
+    }
+    finally {
+        stop();
+        await exit?.catch((cause) => { failure ??= cause; });
+        if (killTimer)
+            clearTimeout(killTimer);
+        await Promise.allSettled(pending);
+        const results = await Promise.allSettled([...sessions].map(release));
+        for (const result of results)
+            if (result.status === "rejected")
+                failure ??= result.reason;
+        await room?.disconnect().catch((cause) => { failure ??= cause; });
+        await client.disconnect().catch((cause) => { failure ??= cause; });
+        process.removeListener("SIGINT", stop);
+        process.removeListener("SIGTERM", stop);
+        process.stdout.removeListener("error", fail);
+        process.stderr.removeListener("error", fail);
+    }
+    if (failure)
+        throw failure;
+}

package/dist/commands/rooms.js

@@ -136,6 +136,51 @@ An Agent waits for the room in a background command and wakes when it returns:
         printView(view);
         console.log(`\nWait for events: cohub rooms events ${view.room.id} --after ${view.sequence} --wait 10m`);
     }));
+    rooms
+        .command("connect <room>")
+        .description("Stream room events and members over realtime; disconnecting keeps your seat")
+        .option("--after <sequence>", "Replay retained events after this sequence")
+        .option("--input", "Accept NDJSON publish/send/presence commands on stdin")
+        .option("--json", "Output newline-delimited JSON")
+        .action(async (roomId, opts) => {
+        try {
+            const { connectToRoom } = await import("./rooms-connect.js");
+            await connectToRoom(roomId, { ...opts, json: jsonRequested(opts) });
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    rooms
+        .command("rtc <room>")
+        .description("Stream RTC media and data through the Go/Pion helper")
+        .option("--helper <path>", "Use a local cohub-rtc binary")
+        .option("--channel <name>", "Open a JSON/binary RTC data channel")
+        .option("--delivery <policy>", "Data channel delivery: reliable or latest", "reliable")
+        .option("--data-input <path>", "NDJSON channel input file or - for stdin")
+        .option("--audio <path>", "Audio input file or - for stdin")
+        .option("--audio-format <format>", "Audio input: pcm or opus (Ogg)", "pcm")
+        .option("--rate <hz>", "Audio sample rate", "48000")
+        .option("--channels <count>", "Audio channels", "1")
+        .option("--video <path>", "Video input file or - for stdin")
+        .option("--video-format <format>", "Video input: i420 or vp8 (IVF)", "i420")
+        .option("--size <widthxheight>", "Video frame dimensions")
+        .option("--fps <rate>", "Video frame rate", "30")
+        .option("--output <directory|->", "Receive framed media into unique .rtc files or binary stdout")
+        .option("--receive-format <format>", "Receive rtp packets or raw decoded frames", "rtp")
+        .option("--receive-size <widthxheight>", "Decoded I420 output dimensions", "640x360")
+        .option("--max-bytes <bytes>", "Stop after this many received bytes; 0 is unlimited", "1073741824")
+        .option("--participant <id>", "Only receive this participant's tracks")
+        .option("--json", "Output newline-delimited JSON")
+        .action(async (roomId, opts) => {
+        try {
+            const { runRoomRtc } = await import("./rooms-rtc.js");
+            await runRoomRtc(roomId, opts);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
     rooms
         .command("get <room>")
         .description("Show the room, its members and your seat")

package/dist/commands/sandboxd-binary.d.ts

@@ -1,4 +1,4 @@
-export declare const SANDBOXD_VERSION = "v2.61.1";
+export declare const SANDBOXD_VERSION = "v2.67.0";
 export declare class SandboxdDownloadError extends Error {
     name: string;
 }

package/dist/commands/sandboxd-binary.js

@@ -7,7 +7,7 @@ import { dirname, join } from "node:path";
 import { pipeline } from "node:stream/promises";
 import { Readable } from "node:stream";
 // Pin only after all platform artifacts are published to the public CDN.
-export const SANDBOXD_VERSION = "v2.61.1";
+export const SANDBOXD_VERSION = "v2.67.0";
 const BINARY_NAME = "cohub-sandboxd";
 // Public CDN prefix hosting the release archives (the repo is private, so the
 // GitHub Release assets are not publicly downloadable). Overridable for staging

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neta-art/cohub-cli",
-  "version": "10.2.0",
+  "version": "10.3.0",
   "description": "CLI for Cohub — spaces, sessions, and agent collaboration.",
   "type": "module",
   "engines": {
@@ -18,7 +18,7 @@
     "NOTICE"
   ],
   "dependencies": {
-    "@neta-art/cohub": "11.2.0",
+    "@neta-art/cohub": "11.3.0",
     "@neta-art/generation": "^0.1.35",
     "commander": "^15.0.0",
     "sharp": "^0.35.4",
@@ -42,6 +42,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json && tsdown",
     "verify:sandboxd": "node --import tsx scripts/verify-sandboxd-release.ts",
+    "verify:rtc": "node --import tsx scripts/verify-rtc-release.ts",
     "verify:board-kernel": "node --import tsx scripts/verify-board-kernel.ts",
     "test": "node ../../scripts/test/run.mjs 'tests/**/*.test.ts'",
     "test:runtime": "node --import tsx --test tests/runtime-*.integration.ts",