@neta-art/cohub 8.11.0 → 8.12.0

package/dist/index.js

@@ -8,8 +8,8 @@ import { z } from "zod";
 const BOARD_DOCUMENT_KIND = "cohub.board";
 const BOARD_MANIFEST_KIND = "cohub.board.manifest";
 const idSchema = z.string().min(1).max(160);
-const jsonObjectSchema = z.record(z.string(), z.unknown());
-const finiteSchema = z.number().finite();
+const jsonObjectSchema$1 = z.record(z.string(), z.unknown());
+const finiteSchema$1 = z.number().finite();
 z.object({
 	kind: z.literal(BOARD_MANIFEST_KIND),
 	version: z.literal(1),
@@ -17,18 +17,18 @@ z.object({
 	title: z.string().min(1).max(255)
 });
 z.object({
-	centerX: finiteSchema,
-	centerY: finiteSchema,
-	zoom: finiteSchema.positive()
+	centerX: finiteSchema$1,
+	centerY: finiteSchema$1,
+	zoom: finiteSchema$1.positive()
 });
 const BoardCameraFocusSchema = z.discriminatedUnion("type", [
 	z.object({
 		type: z.literal("rect"),
 		rect: z.object({
-			x: finiteSchema,
-			y: finiteSchema,
-			width: finiteSchema.positive(),
-			height: finiteSchema.positive()
+			x: finiteSchema$1,
+			y: finiteSchema$1,
+			width: finiteSchema$1.positive(),
+			height: finiteSchema$1.positive()
 		})
 	}),
 	z.object({
@@ -47,9 +47,9 @@ const BoardCameraFocusSchema = z.discriminatedUnion("type", [
 const BoardCameraFocusParamsSchema = z.object({
 	focus: BoardCameraFocusSchema,
 	fit: z.enum(["contain", "cover"]).default("contain"),
-	padding: finiteSchema.nonnegative().default(32),
-	minZoom: finiteSchema.positive().optional(),
-	maxZoom: finiteSchema.positive().optional()
+	padding: finiteSchema$1.nonnegative().default(32),
+	minZoom: finiteSchema$1.positive().optional(),
+	maxZoom: finiteSchema$1.positive().optional()
 }).superRefine((value, context) => {
 	if (value.minZoom !== void 0 && value.maxZoom !== void 0 && value.minZoom > value.maxZoom) context.addIssue({
 		code: "custom",
@@ -62,17 +62,17 @@ z.object({
 	type: z.string().min(1).max(40),
 	parentId: idSchema.nullable(),
 	orderKey: z.string().max(4096).nullable(),
-	x: finiteSchema,
-	y: finiteSchema,
-	width: finiteSchema.positive(),
-	height: finiteSchema.positive(),
-	rotation: finiteSchema,
+	x: finiteSchema$1,
+	y: finiteSchema$1,
+	width: finiteSchema$1.positive(),
+	height: finiteSchema$1.positive(),
+	rotation: finiteSchema$1,
 	refKind: z.string().max(40).nullable(),
 	refPath: z.string().max(4096).nullable(),
 	refUrl: z.string().max(4096).nullable(),
-	view: jsonObjectSchema,
-	style: jsonObjectSchema,
-	data: jsonObjectSchema
+	view: jsonObjectSchema$1,
+	style: jsonObjectSchema$1,
+	data: jsonObjectSchema$1
 });
 const stripBoardServerFields = (value) => {
 	if (!value || typeof value !== "object" || Array.isArray(value)) return value;
@@ -86,7 +86,7 @@ const BoardCreateInputSchema = z.object({
 	/** Reused by clients when board creation is interrupted and retried. */
 	mutationId: z.string().max(128).optional(),
 	title: z.string().min(1).max(255).optional(),
-	metadata: jsonObjectSchema.optional(),
+	metadata: jsonObjectSchema$1.optional(),
 	items: z.array(BoardAuthoringItemSchema).max(5e4).optional(),
 	connections: z.array(BoardConnectionSchema).max(5e4).optional(),
 	effects: z.array(BoardCreateEffectInputSchema).max(5e4).optional(),
@@ -132,17 +132,24 @@ z.object({
 	effectIds: z.array(idSchema).max(5e4).optional(),
 	compositionIds: z.array(idSchema).max(5e4).optional(),
 	viewport: z.object({
-		x: finiteSchema,
-		y: finiteSchema,
-		width: finiteSchema.positive(),
-		height: finiteSchema.positive()
+		x: finiteSchema$1,
+		y: finiteSchema$1,
+		width: finiteSchema$1.positive(),
+		height: finiteSchema$1.positive()
 	}).optional()
 });
+z.object({
+	/** Return transactions with `version < before`. Omit for the newest page. */
+	before: z.number().int().positive().optional(),
+	limit: z.number().int().min(1).max(500).default(200),
+	/** Include the current rows on the newest page (default true). Tail refreshes turn this off. */
+	snapshot: z.boolean().default(true)
+});
 /** Persisted on `boards.metadata.playback`: how a Board plays when opened. */
 const BoardPlaybackPolicySchema = z.object({
 	compositionId: idSchema,
 	/** Delay before the first local playback after opening the Board, in milliseconds. */
-	delayMs: finiteSchema.nonnegative().default(0)
+	delayMs: finiteSchema$1.nonnegative().default(0)
 });
 function parseBoardPlaybackPolicy(metadata) {
 	const parsed = BoardPlaybackPolicySchema.safeParse(metadata.playback);
@@ -153,8 +160,8 @@ z.discriminatedUnion("type", [
 		commandId: idSchema,
 		type: z.literal("play"),
 		compositionId: idSchema,
-		position: finiteSchema.nonnegative().optional(),
-		timeScale: finiteSchema.positive().max(4).optional(),
+		position: finiteSchema$1.nonnegative().optional(),
+		timeScale: finiteSchema$1.positive().max(4).optional(),
 		shared: z.boolean().optional(),
 		seed: idSchema.optional()
 	}),
@@ -167,7 +174,7 @@ z.discriminatedUnion("type", [
 		commandId: idSchema,
 		type: z.literal("seek"),
 		playbackId: z.string().uuid(),
-		position: finiteSchema.nonnegative()
+		position: finiteSchema$1.nonnegative()
 	}),
 	z.object({
 		commandId: idSchema,
@@ -176,9 +183,49 @@ z.discriminatedUnion("type", [
 	})
 ]);
 //#endregion
+//#region ../protocol/dist/board-animation.js
+const extensionKindSchema = z.string().regex(/^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)+$/).max(160);
+const jsonObjectSchema = z.record(z.string(), z.unknown());
+const finiteSchema = z.number().finite();
+/** Parameters shared by the built-in deal entrance preset. */
+const BoardDealParamsSchema = z.object({
+	lift: finiteSchema.nonnegative().max(2e3).optional(),
+	swing: finiteSchema.nonnegative().max(2e3).optional(),
+	curve: finiteSchema.nonnegative().max(2e3).optional(),
+	tilt: finiteSchema.nonnegative().max(180).optional(),
+	scale: finiteSchema.positive().max(2).optional(),
+	duration: finiteSchema.positive().max(1e4).optional(),
+	landing: finiteSchema.nonnegative().max(1e4).optional()
+}).strict();
+/** A versioned, reusable animation preset reference. */
+const BoardAnimationSpecSchema = z.object({
+	kind: extensionKindSchema,
+	kindVersion: z.number().int().positive().default(1),
+	params: jsonObjectSchema.default({})
+}).strict().superRefine((spec, context) => {
+	if (spec.kind !== "effects.deal" || spec.kindVersion !== 1) return;
+	const parsed = BoardDealParamsSchema.safeParse(spec.params);
+	if (parsed.success) return;
+	context.addIssue({
+		code: "custom",
+		message: parsed.error.issues[0]?.message ?? "invalid effects.deal parameters",
+		path: ["params", ...parsed.error.issues[0]?.path ?? []]
+	});
+});
+/** Board-wide default motion policies. Omitted policies mean no motion. */
+const BoardMotionSchema = z.object({ enter: BoardAnimationSpecSchema.optional() }).strict();
+//#endregion
 //#region ../protocol/dist/board-capability-registry.js
 const CLIPS = new Set(BOARD_BUILTIN_CLIP_KINDS);
-new Set(BOARD_BUILTIN_EFFECT_KINDS);
+const EFFECTS = new Set(BOARD_BUILTIN_EFFECT_KINDS);
+const BUILTIN_VERSIONS = new Set(BOARD_BUILTIN_CAPABILITIES.map((c) => `${c.kind}:${c.id}@${c.version}`));
+/**
+* True when a built-in renderer exists for exactly this kind@version. A known
+* kind at an unknown version is not built-in: it must not pass as one.
+*/
+function isBuiltinBoardCapability(kind, id, version) {
+	return BUILTIN_VERSIONS.has(`${kind}:${id}@${version}`);
+}
 const record = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
 const finite = (value) => typeof value === "number" && Number.isFinite(value);
 function validateBuiltinBoardClip(clip, path = "clip") {
@@ -212,6 +259,47 @@ function validateBuiltinBoardClip(clip, path = "clip") {
 	}
 	return errors;
 }
+function validateBuiltinBoardEffect(effect, path = "effect") {
+	const diagnostics = [];
+	if (effect.lifecycle === "on-enter") {
+		if (effect.target.type !== "item") diagnostics.push({
+			severity: "error",
+			code: "INVALID_BOARD_EFFECT",
+			message: "on-enter effects must target an item",
+			path: `${path}.target`
+		});
+		if (effect.timeOrigin !== "activation") diagnostics.push({
+			severity: "error",
+			code: "INVALID_BOARD_EFFECT",
+			message: "on-enter effects must use activation time",
+			path: `${path}.timeOrigin`
+		});
+	} else if (EFFECTS.has(effect.kind) && effect.target.type !== "item") diagnostics.push({
+		severity: "error",
+		code: "INVALID_BOARD_EFFECT",
+		message: `${effect.kind} must target an item`,
+		path: `${path}.target`
+	});
+	if (effect.kind === "effects.deal" && effect.kindVersion === 1) {
+		if (effect.lifecycle !== "on-enter") diagnostics.push({
+			severity: "error",
+			code: "INVALID_BOARD_EFFECT",
+			message: "effects.deal must use the on-enter lifecycle",
+			path: `${path}.lifecycle`
+		});
+		const parsed = BoardDealParamsSchema.safeParse(effect.params);
+		if (!parsed.success) diagnostics.push({
+			severity: "error",
+			code: "INVALID_BOARD_EFFECT",
+			message: parsed.error.issues[0]?.message ?? "invalid effects.deal parameters",
+			path: `${path}.params`
+		});
+	}
+	return diagnostics;
+}
+function estimateBuiltinBoardEffectCost(effect) {
+	return isBuiltinBoardCapability("effect", effect.kind, effect.kindVersion) ? { drawCalls: 1 } : {};
+}
 function estimateBuiltinBoardClipCost(clip) {
 	switch (clip.kind) {
 		case "effects.particles": {
@@ -352,7 +440,18 @@ const BoardViewportSchema = z.object({
 	zoom: z.number().finite().min(.05).max(8)
 });
 const BoardAppearanceSchema = z.object({
-	theme: z.string().min(1).default("clean"),
+	/** Legacy field retained when reading older Board documents; not used for rendering. */
+	theme: z.string().min(1).optional(),
+	/** Board-wide motion policies. Omitted policies mean no motion. */
+	motion: BoardMotionSchema.optional(),
+	/** Legacy field retained when reading older Board documents; not used for rendering. */
+	mood: z.enum([
+		"clean",
+		"playful",
+		"arcane",
+		"cyber",
+		"natural"
+	]).optional(),
 	background: z.object({
 		kind: z.enum([
 			"solid",
@@ -386,14 +485,7 @@ const BoardAppearanceSchema = z.object({
 		visible: false,
 		size: 24,
 		opacity: .12
-	}),
-	mood: z.enum([
-		"clean",
-		"playful",
-		"arcane",
-		"cyber",
-		"natural"
-	]).default("clean")
+	})
 });
 /** Optional visual chrome still carried by a few older shapes. */
 const BoardItemStyleSchema = z.object({
@@ -695,14 +787,12 @@ z.object({
 	kind: z.literal(BOARD_DOCUMENT_KIND),
 	version: z.literal(1),
 	appearance: BoardAppearanceSchema.default({
-		theme: "clean",
 		background: { kind: "solid" },
 		grid: {
 			visible: false,
 			size: 24,
 			opacity: .12
-		},
-		mood: "clean"
+		}
 	}),
 	viewport: BoardViewportSchema,
 	items: z.array(BoardItemSchema),
@@ -1294,6 +1384,12 @@ const buildAppRuntimeCloseRequest = () => ({
 	version: 1,
 	type: "close.request"
 });
+const buildAppRuntimeConfigureRequest = (input) => ({
+	protocol: APP_RUNTIME_PROTOCOL,
+	version: 1,
+	type: "configure.request",
+	...input
+});
 //#endregion
 //#region ../protocol/dist/app-navigation.js
 const APP_NAVIGATION_PROTOCOL = "cohub.app.navigation";
@@ -2452,6 +2548,14 @@ var AppRuntimeApi = class {
 	requestClose() {
 		this.transport.notify?.(buildAppRuntimeCloseRequest());
 	}
+	/**
+	* Requests the host to update the overlay's geometry or pointer hit regions.
+	* Only meaningful when the App was opened as an `overlay` surface; the host
+	* is free to clamp or ignore values that violate its layout policy.
+	*/
+	requestConfigure(input) {
+		this.transport.notify?.(buildAppRuntimeConfigureRequest(input));
+	}
 	async getAccessToken(options) {
 		await this.ensureStorageKeys();
 		if (this.token && !options?.forceRefresh) return this.token;
@@ -2553,7 +2657,7 @@ var AppRuntimeApi = class {
 	* One consent: create a viewer-owned Space (full `CreateSpaceInput`, same
 	* as `spaces.create`) and grant the scopes on it. Never silent — each
 	* confirm mints a new Space. The host creates with the viewer's account
-	* token; the app never calls `POST /api/spaces` itself.
+	* token.
 	* `{ granted: false, space }` means the Space was created but not provisioned;
 	* no grant was issued. A viewer deny is `{ granted: false, space: null }`.
 	*/
@@ -2766,6 +2870,11 @@ var CohubClient = class {
 		onContextChanged: (listener) => this.appRuntime.onContextChanged(listener),
 		/** Ask the host to close this App's surface. */
 		requestClose: () => this.appRuntime.requestClose(),
+		/**
+		* Request that the host update this overlay's geometry or pointer hit
+		* regions.  Only meaningful for `overlay` surfaces; ignored otherwise.
+		*/
+		requestConfigure: (input) => this.appRuntime.requestConfigure(input),
 		embed: { 
 		/** Host another App's public page in an iframe and forward the shell location to it. */
 attach: attachAppEmbed },
@@ -3352,7 +3461,7 @@ function createAppBridgeCore(config) {
 		return Array.from(bySpace.values());
 	}
 	function allowsOwnerAutoAuthorization() {
-		return authorizationContext.surface === "background" || authorizationContext.surface === "app";
+		return authorizationContext.surface === "background" || authorizationContext.surface === "app" || authorizationContext.surface === "overlay";
 	}
 	async function ensureBaseToken(forceRefresh = false) {
 		if (appToken && !forceRefresh) return appToken;
@@ -4033,6 +4142,15 @@ var BoardExtensionRegistry = class {
 		const diagnostics = [];
 		const composition = parsed.data;
 		const cost = { ...ZERO_COST };
+		for (const effect of input.effects ?? []) {
+			diagnostics.push(...validateBuiltinBoardEffect(effect, `effects.${effect.id}`));
+			if (!this.#extensions.has(`effect:${effect.kind}@${effect.kindVersion}`)) diagnostics.push({
+				severity: "warning",
+				code: "UNKNOWN_EFFECT",
+				message: `No renderer is registered for ${effect.kind}@${effect.kindVersion}`,
+				path: `effects.${effect.id}`
+			});
+		}
 		const events = [];
 		for (const clip of composition.timeline.clips) {
 			const definition = this.#extensions.get(`clip:${clip.kind}@${clip.kindVersion}`);
@@ -4066,7 +4184,10 @@ var BoardExtensionRegistry = class {
 			active[key] += event.cost[key] * event.direction;
 			cost[key] = Math.max(cost[key], active[key]);
 		}
-		for (const effect of input.effects ?? []) if (effect.kind === "effects.pulse" || effect.kind === "effects.float") cost.drawCalls += 1;
+		for (const effect of input.effects ?? []) {
+			const estimate = estimateBuiltinBoardEffectCost(effect);
+			for (const key of Object.keys(cost)) cost[key] += estimate[key] ?? 0;
+		}
 		const limits = input.limits ?? DEFAULT_BOARD_LIMITS;
 		for (const key of Object.keys(cost)) if (cost[key] > limits[key]) diagnostics.push({
 			severity: "warning",
@@ -4087,4 +4208,4 @@ function createBoardExtensionRegistry() {
 }
 const BOARD_CHANNELS = BOARD_ANIMATION_CHANNELS;
 //#endregion
-export { APP_COMPOSER_CHIP_CONTENT_MAX_BYTES, APP_COMPOSER_CHIP_KEY_MAX_LENGTH, APP_COMPOSER_CHIP_LABEL_MAX_LENGTH, APP_SURFACE_READY_TIMEOUT_MS, APP_SURFACE_REQUEST_TIMEOUT_MS, AppCommerceApi, AppRealtimeApi, AppRefParseError, AppRoom, AppRuntimeApi, AppRuntimeApi as WorkRuntimeApi, AppSurfaceApi, AppsApi, BILLING_ACCESS_BLOCKED_ERROR_CODE, BOARD_ANIMATION_CHANNEL_CAPABILITIES, BOARD_CHANNELS, BOARD_COLOR_IDS, BOARD_GEO_KINDS, BillingApi, BoardAuthoringItemSchema, BoardClient, BoardCompositionInputSchema, BoardCompositionSchema, BoardEffectInputSchema, BoardEffectSchema, BoardExtensionRegistry, BoardItemPatchSchema, BoardPlaybackPolicySchema, BoardSemanticCommandSchema, COHUB_ENVIRONMENTS, COHUB_SOURCE_HEADER, COHUB_SOURCE_HEADER_NAMES, CohubClient, CohubHttpClient, DEFAULT_BOARD_LIMITS, DESKTOP_COMMAND_DEFAULT_TIMEOUT_MS, DESKTOP_COMMAND_MAX_TIMEOUT_MS, DESKTOP_COMMAND_PAYLOAD_MAX_BYTES, DESKTOP_COMMAND_PENDING_TTL_SECONDS, DESKTOP_COMMAND_SETTLEMENT_GRACE_SECONDS, DESKTOP_COMMAND_TERMINAL_TTL_SECONDS, DESKTOP_COMMAND_VERSION, DesktopCommandsApi, FEATURE_NOT_ENTITLED_ERROR_CODE, GenerationPolicyError, HttpError, PERMISSIONS, ParentBridgeTransport, PopupBrokerTransport, REQUEST_SOURCE_VIA_MAX_LENGTH, ReferencesApi, ReferralsApi, SessionGenerationStreamClient, SessionPatchReducer, SpacePublicFilesApi, UiCommandsApi, UsersApi, VoiceApi, VoiceInputClient, WebsocketClient, WorkCommerceApi, WorkRealtimeApi, WorkRefParseError, WorkRoom, WorkSurfaceApi, assertGenerationRequestAllowedByPolicy, attachAppEmbed, buildAppSurfaceRequest, buildSpaceInvitePath, buildSpacePath, clearGrantedAppScopes, compileComposition, composition, createAppBridgeCore, createAppBridgeCore as createWorkBridgeCore, createAppRuntime, createAppRuntime as createWorkRuntime, createBoardExtensionRegistry, createCohubClient, createHttpClient, createSessionGenerationStreamClient, createSessionPatchReducer, createSlugAppIdResolver, createSlugAppIdResolver as createSlugWorkIdResolver, createVoiceInputClient, createWebsocketClient, decodeGenerationPolicy, encodeGenerationPolicy, extractBillingPayload, filterDiscoverableGenerationModels, filterGenerationDeclarationsByPolicy, findGenerationModelPolicy, formatAppRef, formatWorkRef, getAllowedGenerationModelIds, getCohubContext, hasGrantedAppScopes, hasRequestSourceIdentity, isAppId, isBillingAccessBlockedCode, isBillingAccessBlockedError, isDesktopCallMethod, isFeatureNotEntitledError, isGenerationModelHidden, isHttpErrorCode, isRequestSourceClientId, isRequestSourceEmpty, isRequestSourceUuid, isTerminalDesktopCommandStatus, isUuid, isWorkId, joinApiUrl, matchesUnauthorizedErrorToken, mergeRequestSourceIntoMeta, normalizeBaseUrl, normalizeGenerationPolicy, normalizeRequestSource, normalizeVoiceInputWebsocketUrl, normalizeWebsocketUrl, parseAppRef, parseAppSurfaceReady, parseAppSurfaceResponse, parseAssistantMessageCommit, parseBoardCompositionInput, parseBoardEffectInput, parseBoardPlaybackPolicy, parseDesktopCommand, parseGenerationPolicyFromEnv, parseRequestSourceFromHeaders, parseWorkRef, proceduralClip, readRequestSourceFromEnv, requestSourceToHeaders, resolveApiBaseUrl, resolveAppTransport, resolveAppTransport as resolveWorkTransport, resolveCohubEnvironment, resolveExecutionAppId, resolveExecutionToken, resolveRequestSourceChannel, resolveVoiceInputWebsocketUrl, resolveWebsocketUrl, sampleCompositionTracks, sampleEasing, sampleTrack, sanitizeAccessToken, scopeListHasPermission, setGrantedAppScopes, track };
+export { APP_COMPOSER_CHIP_CONTENT_MAX_BYTES, APP_COMPOSER_CHIP_KEY_MAX_LENGTH, APP_COMPOSER_CHIP_LABEL_MAX_LENGTH, APP_SURFACE_READY_TIMEOUT_MS, APP_SURFACE_REQUEST_TIMEOUT_MS, AppCommerceApi, AppRealtimeApi, AppRefParseError, AppRoom, AppRuntimeApi, AppRuntimeApi as WorkRuntimeApi, AppSurfaceApi, AppsApi, BILLING_ACCESS_BLOCKED_ERROR_CODE, BOARD_ANIMATION_CHANNEL_CAPABILITIES, BOARD_CHANNELS, BOARD_COLOR_IDS, BOARD_GEO_KINDS, BillingApi, BoardAnimationSpecSchema, BoardAuthoringItemSchema, BoardClient, BoardCompositionInputSchema, BoardCompositionSchema, BoardDealParamsSchema, BoardEffectInputSchema, BoardEffectSchema, BoardExtensionRegistry, BoardItemPatchSchema, BoardPlaybackPolicySchema, BoardSemanticCommandSchema, COHUB_ENVIRONMENTS, COHUB_SOURCE_HEADER, COHUB_SOURCE_HEADER_NAMES, CohubClient, CohubHttpClient, DEFAULT_BOARD_LIMITS, DESKTOP_COMMAND_DEFAULT_TIMEOUT_MS, DESKTOP_COMMAND_MAX_TIMEOUT_MS, DESKTOP_COMMAND_PAYLOAD_MAX_BYTES, DESKTOP_COMMAND_PENDING_TTL_SECONDS, DESKTOP_COMMAND_SETTLEMENT_GRACE_SECONDS, DESKTOP_COMMAND_TERMINAL_TTL_SECONDS, DESKTOP_COMMAND_VERSION, DesktopCommandsApi, FEATURE_NOT_ENTITLED_ERROR_CODE, GenerationPolicyError, HttpError, PERMISSIONS, ParentBridgeTransport, PopupBrokerTransport, REQUEST_SOURCE_VIA_MAX_LENGTH, ReferencesApi, ReferralsApi, SessionGenerationStreamClient, SessionPatchReducer, SpacePublicFilesApi, UiCommandsApi, UsersApi, VoiceApi, VoiceInputClient, WebsocketClient, WorkCommerceApi, WorkRealtimeApi, WorkRefParseError, WorkRoom, WorkSurfaceApi, assertGenerationRequestAllowedByPolicy, attachAppEmbed, buildAppSurfaceRequest, buildSpaceInvitePath, buildSpacePath, clearGrantedAppScopes, compileComposition, composition, createAppBridgeCore, createAppBridgeCore as createWorkBridgeCore, createAppRuntime, createAppRuntime as createWorkRuntime, createBoardExtensionRegistry, createCohubClient, createHttpClient, createSessionGenerationStreamClient, createSessionPatchReducer, createSlugAppIdResolver, createSlugAppIdResolver as createSlugWorkIdResolver, createVoiceInputClient, createWebsocketClient, decodeGenerationPolicy, encodeGenerationPolicy, extractBillingPayload, filterDiscoverableGenerationModels, filterGenerationDeclarationsByPolicy, findGenerationModelPolicy, formatAppRef, formatWorkRef, getAllowedGenerationModelIds, getCohubContext, hasGrantedAppScopes, hasRequestSourceIdentity, isAppId, isBillingAccessBlockedCode, isBillingAccessBlockedError, isDesktopCallMethod, isFeatureNotEntitledError, isGenerationModelHidden, isHttpErrorCode, isRequestSourceClientId, isRequestSourceEmpty, isRequestSourceUuid, isTerminalDesktopCommandStatus, isUuid, isWorkId, joinApiUrl, matchesUnauthorizedErrorToken, mergeRequestSourceIntoMeta, normalizeBaseUrl, normalizeGenerationPolicy, normalizeRequestSource, normalizeVoiceInputWebsocketUrl, normalizeWebsocketUrl, parseAppRef, parseAppSurfaceReady, parseAppSurfaceResponse, parseAssistantMessageCommit, parseBoardCompositionInput, parseBoardEffectInput, parseBoardPlaybackPolicy, parseDesktopCommand, parseGenerationPolicyFromEnv, parseRequestSourceFromHeaders, parseWorkRef, proceduralClip, readRequestSourceFromEnv, requestSourceToHeaders, resolveApiBaseUrl, resolveAppTransport, resolveAppTransport as resolveWorkTransport, resolveCohubEnvironment, resolveExecutionAppId, resolveExecutionToken, resolveRequestSourceChannel, resolveVoiceInputWebsocketUrl, resolveWebsocketUrl, sampleCompositionTracks, sampleEasing, sampleTrack, sanitizeAccessToken, scopeListHasPermission, setGrantedAppScopes, track };

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

@@ -0,0 +1 @@
+import { z } from "zod";

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

@@ -0,0 +1,34 @@
+import { z } from "zod";
+//#region ../protocol/dist/board-animation.js
+const extensionKindSchema = z.string().regex(/^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)+$/).max(160);
+const jsonObjectSchema = z.record(z.string(), z.unknown());
+const finiteSchema = z.number().finite();
+/** Parameters shared by the built-in deal entrance preset. */
+const BoardDealParamsSchema = z.object({
+	lift: finiteSchema.nonnegative().max(2e3).optional(),
+	swing: finiteSchema.nonnegative().max(2e3).optional(),
+	curve: finiteSchema.nonnegative().max(2e3).optional(),
+	tilt: finiteSchema.nonnegative().max(180).optional(),
+	scale: finiteSchema.positive().max(2).optional(),
+	duration: finiteSchema.positive().max(1e4).optional(),
+	landing: finiteSchema.nonnegative().max(1e4).optional()
+}).strict();
+/** A versioned, reusable animation preset reference. */
+const BoardAnimationSpecSchema = z.object({
+	kind: extensionKindSchema,
+	kindVersion: z.number().int().positive().default(1),
+	params: jsonObjectSchema.default({})
+}).strict().superRefine((spec, context) => {
+	if (spec.kind !== "effects.deal" || spec.kindVersion !== 1) return;
+	const parsed = BoardDealParamsSchema.safeParse(spec.params);
+	if (parsed.success) return;
+	context.addIssue({
+		code: "custom",
+		message: parsed.error.issues[0]?.message ?? "invalid effects.deal parameters",
+		path: ["params", ...parsed.error.issues[0]?.path ?? []]
+	});
+});
+/** Board-wide default motion policies. Omitted policies mean no motion. */
+const BoardMotionSchema = z.object({ enter: BoardAnimationSpecSchema.optional() }).strict();
+//#endregion
+export { BoardAnimationSpecSchema, BoardDealParamsSchema, BoardMotionSchema };

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

@@ -1140,10 +1140,11 @@ declare const BoardSemanticCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
       type: z.ZodLiteral<"board">;
     }, z.core.$strict>], "type">;
     kind: z.ZodString;
-    kindVersion: z.ZodNumber;
+    kindVersion: z.ZodDefault<z.ZodNumber>;
     enabled: z.ZodDefault<z.ZodBoolean>;
     lifecycle: z.ZodEnum<{
       manual: "manual";
+      "on-enter": "on-enter";
       persistent: "persistent";
       "when-visible": "when-visible";
     }>;

package/dist/protocol/dist/board-capability-registry.js

@@ -1,8 +1,17 @@
-import { BOARD_BUILTIN_CLIP_KINDS, BOARD_BUILTIN_EFFECT_KINDS, DEFAULT_BOARD_RENDER_LIMITS } from "./board-constants.js";
+import { BOARD_BUILTIN_CAPABILITIES, BOARD_BUILTIN_CLIP_KINDS, BOARD_BUILTIN_EFFECT_KINDS, DEFAULT_BOARD_RENDER_LIMITS } from "./board-constants.js";
 import { BoardCameraFocusParamsSchema } from "./board.js";
+import { BoardDealParamsSchema } from "./board-animation.js";
 //#region ../protocol/dist/board-capability-registry.js
 const CLIPS = new Set(BOARD_BUILTIN_CLIP_KINDS);
-new Set(BOARD_BUILTIN_EFFECT_KINDS);
+const EFFECTS = new Set(BOARD_BUILTIN_EFFECT_KINDS);
+const BUILTIN_VERSIONS = new Set(BOARD_BUILTIN_CAPABILITIES.map((c) => `${c.kind}:${c.id}@${c.version}`));
+/**
+* True when a built-in renderer exists for exactly this kind@version. A known
+* kind at an unknown version is not built-in: it must not pass as one.
+*/
+function isBuiltinBoardCapability(kind, id, version) {
+	return BUILTIN_VERSIONS.has(`${kind}:${id}@${version}`);
+}
 const record = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
 const finite = (value) => typeof value === "number" && Number.isFinite(value);
 function validateBuiltinBoardClip(clip, path = "clip") {
@@ -36,6 +45,47 @@ function validateBuiltinBoardClip(clip, path = "clip") {
 	}
 	return errors;
 }
+function validateBuiltinBoardEffect(effect, path = "effect") {
+	const diagnostics = [];
+	if (effect.lifecycle === "on-enter") {
+		if (effect.target.type !== "item") diagnostics.push({
+			severity: "error",
+			code: "INVALID_BOARD_EFFECT",
+			message: "on-enter effects must target an item",
+			path: `${path}.target`
+		});
+		if (effect.timeOrigin !== "activation") diagnostics.push({
+			severity: "error",
+			code: "INVALID_BOARD_EFFECT",
+			message: "on-enter effects must use activation time",
+			path: `${path}.timeOrigin`
+		});
+	} else if (EFFECTS.has(effect.kind) && effect.target.type !== "item") diagnostics.push({
+		severity: "error",
+		code: "INVALID_BOARD_EFFECT",
+		message: `${effect.kind} must target an item`,
+		path: `${path}.target`
+	});
+	if (effect.kind === "effects.deal" && effect.kindVersion === 1) {
+		if (effect.lifecycle !== "on-enter") diagnostics.push({
+			severity: "error",
+			code: "INVALID_BOARD_EFFECT",
+			message: "effects.deal must use the on-enter lifecycle",
+			path: `${path}.lifecycle`
+		});
+		const parsed = BoardDealParamsSchema.safeParse(effect.params);
+		if (!parsed.success) diagnostics.push({
+			severity: "error",
+			code: "INVALID_BOARD_EFFECT",
+			message: parsed.error.issues[0]?.message ?? "invalid effects.deal parameters",
+			path: `${path}.params`
+		});
+	}
+	return diagnostics;
+}
+function estimateBuiltinBoardEffectCost(effect) {
+	return isBuiltinBoardCapability("effect", effect.kind, effect.kindVersion) ? { drawCalls: 1 } : {};
+}
 function estimateBuiltinBoardClipCost(clip) {
 	switch (clip.kind) {
 		case "effects.particles": {
@@ -70,4 +120,4 @@ function estimateBuiltinBoardClipCost(clip) {
 	}
 }
 //#endregion
-export { estimateBuiltinBoardClipCost, validateBuiltinBoardClip };
+export { estimateBuiltinBoardClipCost, estimateBuiltinBoardEffectCost, isBuiltinBoardCapability, validateBuiltinBoardClip, validateBuiltinBoardEffect };

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

@@ -1,6 +1,6 @@
 import { BoardAuthoringItemSchema, BoardItemPatchSchema } from "./board-authoring.js";
 import { BoardNodeInputSchema } from "./board.js";
-import { boardArrowFrame, boardDrawBounds, boardDrawPointsToLocal } from "./board-geometry.js";
+import { boardArrowFrame, boardDrawBounds, boardDrawPointsToLocal, boardDrawPointsToWorld } from "./board-geometry.js";
 import { BOARD_NATIVE_NODE_TYPES, validateBoardNodeInput } from "./board-node.js";
 //#region ../protocol/dist/board-codec.js
 var BoardItemValidationError = class extends Error {
@@ -30,6 +30,153 @@ function authoringDiagnostic(diagnostic, path) {
 	};
 }
 const isRecord = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
+function baseItem(node) {
+	return {
+		id: node.nodeId,
+		position: {
+			x: node.x,
+			y: node.y
+		},
+		size: {
+			width: node.width,
+			height: node.height
+		},
+		rotation: node.rotation,
+		...node.parentId ? { parentId: node.parentId } : {},
+		...node.data.locked === true ? { locked: true } : {},
+		...isRecord(node.data.metadata) ? { metadata: node.data.metadata } : {}
+	};
+}
+function filePath(node) {
+	if (!node.refPath) throw new Error(`Board item ${node.nodeId} is missing its source path`);
+	return node.refPath;
+}
+function style(node) {
+	const value = {};
+	if (typeof node.data.color === "string") value.color = node.data.color;
+	if (typeof node.data.size === "number") value.strokeWidth = node.data.size;
+	if (typeof node.data.fillOpacity === "number") value.fillOpacity = node.data.fillOpacity;
+	return Object.keys(value).length ? value : void 0;
+}
+function boardNodeToAuthoringItem(node) {
+	const base = baseItem(node);
+	if (node.type === "draw" || node.type === "arrow") {
+		delete base.size;
+		delete base.position;
+	}
+	const visual = style(node);
+	let candidate;
+	switch (node.type) {
+		case "text":
+			candidate = {
+				...base,
+				type: "text",
+				props: {
+					text: node.data.text ?? "",
+					fontSize: node.data.fontSize ?? 24
+				},
+				...visual ? { style: visual } : {}
+			};
+			break;
+		case "geo":
+			candidate = {
+				...base,
+				type: "geo",
+				props: {
+					shape: node.data.geo ?? "rectangle",
+					text: node.data.text ?? ""
+				},
+				...visual ? { style: visual } : {}
+			};
+			break;
+		case "draw":
+			candidate = {
+				...base,
+				type: "draw",
+				props: { points: Array.isArray(node.data.points) ? boardDrawPointsToWorld(node.data.points, node.x, node.y) : [] },
+				...visual ? { style: visual } : {}
+			};
+			break;
+		case "arrow":
+			candidate = {
+				...base,
+				type: "arrow",
+				props: {
+					start: node.data.start,
+					end: node.data.end,
+					bend: node.data.bend ?? 0,
+					arrowStart: node.data.arrowStart ?? false,
+					arrowEnd: node.data.arrowEnd ?? true,
+					label: node.data.label ?? ""
+				},
+				...visual ? { style: visual } : {}
+			};
+			break;
+		case "frame":
+			candidate = {
+				...base,
+				type: "frame",
+				props: { label: node.data.label ?? "Frame" },
+				...visual ? { style: visual } : {}
+			};
+			break;
+		case "image":
+			candidate = {
+				...base,
+				type: "image",
+				props: isRecord(node.data.crop) ? { crop: node.data.crop } : {},
+				source: {
+					kind: "space-file",
+					path: filePath(node),
+					...Object.keys(node.view).length ? { snapshot: node.view } : {}
+				}
+			};
+			break;
+		case "video":
+		case "audio":
+		case "file":
+			candidate = {
+				...base,
+				type: node.type,
+				props: {},
+				source: {
+					kind: "space-file",
+					path: filePath(node),
+					...Object.keys(node.view).length ? { snapshot: node.view } : {}
+				}
+			};
+			break;
+		case "task":
+			candidate = {
+				...base,
+				type: "task",
+				props: {
+					taskRunId: node.data.taskRunId,
+					snapshot: node.view
+				}
+			};
+			break;
+		default: {
+			const props = { ...node.data };
+			delete props.locked;
+			delete props.metadata;
+			delete props.kindVersion;
+			candidate = {
+				...base,
+				type: node.type,
+				kindVersion: typeof node.data.kindVersion === "number" ? node.data.kindVersion : 1,
+				props,
+				...Object.keys(node.style).length ? { style: node.style } : {},
+				...node.refPath ? { source: {
+					kind: node.refKind ?? "space-file",
+					ref: node.refPath,
+					...Object.keys(node.view).length ? { snapshot: node.view } : {}
+				} } : {}
+			};
+		}
+	}
+	return BoardAuthoringItemSchema.parse(candidate);
+}
 function commonData(item) {
 	return {
 		...item.locked ? { locked: true } : {},
@@ -233,4 +380,4 @@ function mergePatch(current, patch) {
 	return result;
 }
 //#endregion
-export { BoardItemValidationError, applyBoardItemPatch, authoringSchemaDiagnostics, boardAuthoringItemToNode };
+export { BoardItemValidationError, applyBoardItemPatch, authoringSchemaDiagnostics, boardAuthoringItemToNode, boardNodeToAuthoringItem };