@neta-art/cohub 8.10.2 → 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),
@@ -891,14 +981,14 @@ var GenerationPolicyError = class extends Error {
 		this.name = "GenerationPolicyError";
 	}
 };
-function isRecord$2(value) {
+function isRecord$4(value) {
 	return !!value && typeof value === "object" && !Array.isArray(value);
 }
 function isPrimitiveEnumValue(value) {
 	return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
 }
 function normalizeConstraint(value) {
-	if (!isRecord$2(value) || typeof value.kind !== "string") return null;
+	if (!isRecord$4(value) || typeof value.kind !== "string") return null;
 	if (value.kind === "enum") {
 		if (!Array.isArray(value.values) || value.values.length === 0 || !value.values.every(isPrimitiveEnumValue)) return null;
 		return {
@@ -928,7 +1018,7 @@ function normalizeConstraint(value) {
 	return null;
 }
 function normalizeGenerationPolicy(value) {
-	if (!isRecord$2(value) || value.version !== 1) return null;
+	if (!isRecord$4(value) || value.version !== 1) return null;
 	if (value.mode === "auto") return {
 		version: 1,
 		mode: "auto"
@@ -936,10 +1026,10 @@ function normalizeGenerationPolicy(value) {
 	if (value.mode !== "limited" || !Array.isArray(value.models) || value.models.length === 0) return null;
 	const models = [];
 	for (const item of value.models) {
-		if (!isRecord$2(item) || typeof item.model !== "string" || !item.model.trim()) return null;
+		if (!isRecord$4(item) || typeof item.model !== "string" || !item.model.trim()) return null;
 		const modelPolicy = { model: item.model.trim() };
 		if (item.parameters !== void 0) {
-			if (!isRecord$2(item.parameters)) return null;
+			if (!isRecord$4(item.parameters)) return null;
 			const parameters = {};
 			for (const [key, rawConstraint] of Object.entries(item.parameters)) {
 				if (!key.trim()) return null;
@@ -1172,8 +1262,8 @@ const APP_SURFACE_REQUEST_TIMEOUT_MS = 15e3;
 const APP_COMPOSER_CHIP_KEY_MAX_LENGTH = 80;
 const APP_COMPOSER_CHIP_LABEL_MAX_LENGTH = 120;
 const APP_COMPOSER_CHIP_CONTENT_MAX_BYTES = 32768;
-const isRecord$1 = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
-const isSurfaceEnvelope = (value) => isRecord$1(value) && value.protocol === "cohub.app.surface" && value.version === 1;
+const isRecord$3 = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
+const isSurfaceEnvelope = (value) => isRecord$3(value) && value.protocol === "cohub.app.surface" && value.version === 1;
 const parseAppSurfaceReady = (value) => {
 	if (!isSurfaceEnvelope(value) || value.type !== "ready") return null;
 	const methods = Array.isArray(value.methods) ? value.methods.filter((method) => typeof method === "string" && Boolean(method)) : [];
@@ -1187,7 +1277,7 @@ const parseAppSurfaceReady = (value) => {
 const parseAppSurfaceResponse = (value) => {
 	if (!isSurfaceEnvelope(value) || value.type !== "response") return null;
 	if (typeof value.requestId !== "string" || !value.requestId) return null;
-	const error = isRecord$1(value.error) ? {
+	const error = isRecord$3(value.error) ? {
 		code: typeof value.error.code === "string" && value.error.code ? value.error.code : "surface_error",
 		message: typeof value.error.message === "string" ? value.error.message : "App surface call failed"
 	} : void 0;
@@ -1207,7 +1297,7 @@ const parseComposerChipKey = (value) => {
 	return key;
 };
 const parseAppComposerChipSet = (value) => {
-	if (!isSurfaceEnvelope(value) || value.type !== "composer.chip.set" || !isRecord$1(value.chip)) return null;
+	if (!isSurfaceEnvelope(value) || value.type !== "composer.chip.set" || !isRecord$3(value.chip)) return null;
 	const key = parseComposerChipKey(value.chip.key);
 	if (!key || typeof value.chip.label !== "string" || typeof value.chip.content !== "string") return null;
 	const label = value.chip.label.trim();
@@ -1289,12 +1379,23 @@ const buildAppRuntimeReady = () => ({
 	version: 1,
 	type: "ready"
 });
+const buildAppRuntimeCloseRequest = () => ({
+	protocol: APP_RUNTIME_PROTOCOL,
+	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";
 const APP_NAVIGATION_MAX_ERROR_CODE_LENGTH = 64;
 const APP_NAVIGATION_MAX_ERROR_MESSAGE_LENGTH = NAVIGATION_ERROR_MESSAGE_MAX_LENGTH;
-const isRecord = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
+const isRecord$2 = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
 const text = (value, max) => typeof value === "string" && value.trim() && value.length <= max ? value : null;
 const buildAppNavigationOpenMessage = (input) => ({
 	protocol: APP_NAVIGATION_PROTOCOL,
@@ -1310,7 +1411,7 @@ const NAVIGATION_REASONS = /* @__PURE__ */ new Set([
 ]);
 function parseNavigationCall(value) {
 	if (value === void 0) return void 0;
-	if (!isRecord(value) || typeof value.ok !== "boolean") return null;
+	if (!isRecord$2(value) || typeof value.ok !== "boolean") return null;
 	if (value.ok) return {
 		ok: true,
 		...value.result === void 0 ? {} : { result: value.result }
@@ -1325,7 +1426,7 @@ function parseNavigationCall(value) {
 	};
 }
 const parseAppNavigationOpenResponse = (value) => {
-	if (!isRecord(value)) return null;
+	if (!isRecord$2(value)) return null;
 	if (value.protocol !== "cohub.app.navigation" || value.version !== 1 || value.type !== "open.result" || !text(value.requestId, 128) || typeof value.handled !== "boolean" || value.reason !== void 0 && !NAVIGATION_REASONS.has(value.reason)) return null;
 	const call = parseNavigationCall(value.call);
 	if (call === null) return null;
@@ -1339,6 +1440,39 @@ const parseAppNavigationOpenResponse = (value) => {
 		...call === void 0 ? {} : { call }
 	};
 };
+const envelope = {
+	protocol: "cohub.app.embed",
+	version: 1
+};
+const isRecord$1 = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
+const isEnvelope = (value) => isRecord$1(value) && value.protocol === "cohub.app.embed" && value.version === 1;
+const parseEmbedId = (value) => typeof value === "string" && value.trim() && value.length <= 128 ? value : null;
+function parseAppEmbedAttachRequest(value) {
+	if (!isEnvelope(value) || value.type !== "attach.request") return null;
+	return {
+		...envelope,
+		type: "attach.request"
+	};
+}
+function parseAppEmbedCloseRequest(value) {
+	if (!isEnvelope(value) || value.type !== "close.request") return null;
+	const embedId = parseEmbedId(value.embedId);
+	return embedId ? {
+		...envelope,
+		type: "close.request",
+		embedId
+	} : null;
+}
+const buildAppEmbedAttach = (input) => ({
+	...envelope,
+	type: "attach",
+	...input
+});
+const buildAppEmbedShellChanged = (input) => ({
+	...envelope,
+	type: "shell.changed",
+	...input
+});
 //#endregion
 //#region src/apis/billing.ts
 var BillingApi = class {
@@ -1988,6 +2122,61 @@ var AppSurfaceApi = class {
 /** @deprecated Use `AppSurfaceApi`. */
 var WorkSurfaceApi = class extends AppSurfaceApi {};
 //#endregion
+//#region src/app-embed.ts
+const generateEmbedId = () => globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+const frameOrigin = (frame) => {
+	try {
+		return new URL(frame.src, window.location.href).origin;
+	} catch {
+		return null;
+	}
+};
+/**
+* Attaches to an iframe that renders a Cohub public App page. The page keeps
+* owning the embedded App's runtime; this only forwards navigation hints and
+* relays the App's close intent back to the embedder. Either side may come up
+* first: the page asks to be attached, and the embedder also announces itself
+* on attach and on every frame load.
+*/
+function attachAppEmbed(frame, options) {
+	const embedId = generateEmbedId();
+	let shell = options.shell ?? null;
+	const post = (message) => {
+		const origin = frameOrigin(frame);
+		if (!origin) return;
+		try {
+			frame.contentWindow?.postMessage(message, origin);
+		} catch {}
+	};
+	const attach = () => post(buildAppEmbedAttach({
+		embedId,
+		embedder: { appId: options.appId },
+		shell
+	}));
+	const onMessage = (event) => {
+		if (event.source !== frame.contentWindow || event.origin !== frameOrigin(frame)) return;
+		if (parseAppEmbedAttachRequest(event.data)) return attach();
+		if (parseAppEmbedCloseRequest(event.data)?.embedId === embedId) options.onCloseRequest?.();
+	};
+	window.addEventListener("message", onMessage);
+	frame.addEventListener("load", attach);
+	attach();
+	return {
+		embedId,
+		setShell(next) {
+			shell = next;
+			post(buildAppEmbedShellChanged({
+				embedId,
+				shell
+			}));
+		},
+		dispose() {
+			window.removeEventListener("message", onMessage);
+			frame.removeEventListener("load", attach);
+		}
+	};
+}
+//#endregion
 //#region src/app-runtime.ts
 const isBrowser$1 = () => typeof window !== "undefined" && typeof window.parent !== "undefined";
 const hasParent = () => isBrowser$1() && window.parent !== window;
@@ -2038,6 +2227,12 @@ var ParentBridgeTransport = class {
 			}
 		};
 	}
+	notify(message) {
+		if (!hasParent()) return;
+		try {
+			window.parent.postMessage(message, this.trustedParentOrigin ?? getParentOrigin() ?? "*");
+		} catch {}
+	}
 	request(message, options) {
 		const timeoutMs = options?.timeoutMs ?? 1200;
 		const retryIntervalMs = options?.retryIntervalMs;
@@ -2345,6 +2540,22 @@ var AppRuntimeApi = class {
 			reason: response === null ? "timeout" : "unsupported"
 		};
 	}
+	/**
+	* Asks the host to close this App: a workspace tab closes, an embedded page
+	* forwards the request to its embedder, a standalone page closes the tab.
+	* No-op in broker mode, where the App owns its own window.
+	*/
+	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;
@@ -2442,6 +2653,41 @@ var AppRuntimeApi = class {
 			} : null
 		};
 	}
+	/**
+	* 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.
+	* `{ granted: false, space }` means the Space was created but not provisioned;
+	* no grant was issued. A viewer deny is `{ granted: false, space: null }`.
+	*/
+	async requestCreateSpaceAuthorization(input) {
+		await this.ensureStorageKeys();
+		const response = await this.transport.request({
+			type: "cohub.app.authorize",
+			scopes: input.scopes,
+			reason: input.reason,
+			createSpace: input.space
+		}, { timeoutMs: 12e4 });
+		const token = response?.token ?? null;
+		const spaceId = typeof response?.space?.id === "string" ? response.space.id : null;
+		const spaceName = typeof response?.space?.name === "string" ? response.space.name : null;
+		if (token) {
+			this.token = token;
+			this.writeStoredToken(token);
+		}
+		if (token && spaceId) {
+			this.authorizedGrants = recordConsent(this.authorizedGrants, spaceId, input.scopes);
+			this.writeStoredGrants(this.authorizedGrants);
+		}
+		return {
+			granted: Boolean(token),
+			space: spaceId ? {
+				id: spaceId,
+				name: spaceName
+			} : null
+		};
+	}
 	async purchase(input) {
 		const purchaseAttemptId = input.purchaseAttemptId?.trim() || generateRequestId();
 		return (await this.transport.request({
@@ -2613,13 +2859,25 @@ var CohubClient = class {
 		/** Ensure the app holds these scopes. Silent when a grant already covers them; `alwaysAsk` forces the dialog. */
 		request: (input) => this.appRuntime.requestAuthorization(input),
 		/** One consent: the viewer picks a Space and grants the scopes on it. `alwaysAsk` re-opens the picker. */
-		requestSpace: (input) => this.appRuntime.requestSpaceAuthorization(input)
+		requestSpace: (input) => this.appRuntime.requestSpaceAuthorization(input),
+		/** One consent: create a viewer-owned Space and grant the scopes on it. `space` is `CreateSpaceInput`. */
+		requestCreateSpace: (input) => this.appRuntime.requestCreateSpaceAuthorization(input)
 	};
 	app = {
 		realtime: null,
 		/** Expose callable methods from inside a published app. */
 		surface: new AppSurfaceApi(),
 		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 },
 		composer: {
 			/** Attach or update context from this app in the Cohub composer. */
 			setChip: (chip) => this.app.surface.setComposerChip(chip),
@@ -2987,6 +3245,88 @@ function sanitizeReason(value) {
 	if (!trimmed) return void 0;
 	return trimmed.length > MAX_REASON_LENGTH ? trimmed.slice(0, MAX_REASON_LENGTH) : trimmed;
 }
+function isRecord(value) {
+	return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function sanitizeBootstrapSource(value) {
+	if (!isRecord(value) || typeof value.type !== "string") return null;
+	if (value.type === "blank") return { type: "blank" };
+	if (value.type === "checkpoint") {
+		const checkpointId = typeof value.checkpointId === "string" ? value.checkpointId.trim() : "";
+		return checkpointId ? {
+			type: "checkpoint",
+			checkpointId
+		} : null;
+	}
+	if (value.type === "git_repo") {
+		const repoUrl = typeof value.repoUrl === "string" ? value.repoUrl.trim() : "";
+		if (!repoUrl) return null;
+		const ref = typeof value.ref === "string" ? value.ref.trim() || null : value.ref === null ? null : void 0;
+		return ref === void 0 ? {
+			type: "git_repo",
+			repoUrl
+		} : {
+			type: "git_repo",
+			repoUrl,
+			ref
+		};
+	}
+	return null;
+}
+/**
+* Untrusted postMessage payload → `CreateSpaceInput`. Unknown keys are
+* dropped; the create API still validates the rest.
+*/
+function sanitizeCreateSpaceInput(value) {
+	if (!isRecord(value)) return null;
+	const name = typeof value.name === "string" ? value.name.trim() : "";
+	if (!name) return null;
+	const input = { name };
+	if (value.slug !== void 0) {
+		if (value.slug !== null && typeof value.slug !== "string") return null;
+		input.slug = value.slug;
+	}
+	if (value.description !== void 0) {
+		if (value.description !== null && typeof value.description !== "string") return null;
+		input.description = value.description;
+	}
+	if (value.source !== void 0) {
+		if (typeof value.source !== "string") return null;
+		input.source = value.source;
+	}
+	if (value.bootstrapSource !== void 0) {
+		const bootstrap = sanitizeBootstrapSource(value.bootstrapSource);
+		if (!bootstrap) return null;
+		input.bootstrapSource = bootstrap;
+	}
+	if (value.extraEnv !== void 0) {
+		if (!Array.isArray(value.extraEnv)) return null;
+		input.extraEnv = value.extraEnv;
+	}
+	if (value.channelBindings !== void 0) {
+		if (!Array.isArray(value.channelBindings)) return null;
+		input.channelBindings = value.channelBindings;
+	}
+	if (value.mods !== void 0) {
+		if (!Array.isArray(value.mods)) return null;
+		input.mods = value.mods;
+	}
+	if (value.config !== void 0) {
+		if (!isRecord(value.config)) return null;
+		input.config = value.config;
+	}
+	return input;
+}
+function readCreatedSpace(payload) {
+	if (!isRecord(payload) || !isRecord(payload.space)) return null;
+	const id = payload.space.id;
+	if (typeof id !== "string" || !id) return null;
+	const name = payload.space.name;
+	return {
+		id,
+		name: typeof name === "string" && name ? name : null
+	};
+}
 function normalizePermissionScopes(scopes) {
 	return Array.from(new Set(clonePermissionScopes(scopes)));
 }
@@ -3108,6 +3448,8 @@ function createAppBridgeCore(config) {
 	const pendingPurchaseStorageKey = `cohub-app-purchase:${app.id}`;
 	const purchaseInFlight = /* @__PURE__ */ new Map();
 	let activePurchase = null;
+	/** Space minted during the current create-space consent; retries skip create. */
+	let mintedSpace = null;
 	async function isCurrentViewerAppOwner() {
 		const viewerUuid = await getViewerUuid();
 		return Boolean(viewerUuid && viewerUuid === app.userUuid);
@@ -3119,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;
@@ -3225,6 +3567,45 @@ function createAppBridgeCore(config) {
 		} catch {}
 	}
 	/**
+	* Creates the Space with the viewer's own token — the same `POST /api/spaces`
+	* path as the web New Space flow and the CLI. The app never holds this token.
+	*/
+	async function createViewerSpace(input) {
+		const request = async (forceRefresh = false) => {
+			const userToken = await getAccessToken({ forceRefresh });
+			if (!userToken) {
+				await config.requestSignIn(typeof location !== "undefined" ? location.pathname : "/");
+				throw new Error("Sign in is required to create a Space.");
+			}
+			return fetch(`${apiOrigin}/api/spaces`, {
+				method: "POST",
+				headers: {
+					Authorization: `Bearer ${userToken}`,
+					"Content-Type": "application/json"
+				},
+				body: JSON.stringify(input)
+			});
+		};
+		let response = await request();
+		if (response.status === 401) response = await request(true);
+		const payload = await response.json().catch(() => null);
+		const space = readCreatedSpace(payload);
+		if (response.ok) {
+			if (!space) throw new Error("Invalid space create response.");
+			return {
+				...space,
+				provisioned: true
+			};
+		}
+		const message = isRecord(payload) && typeof payload.message === "string" ? payload.message : "Failed to create Space.";
+		if (space) return {
+			...space,
+			provisioned: false,
+			error: message
+		};
+		throw new Error(message);
+	}
+	/**
 	* Resolves the target space's name for the consent dialog. The host — not
 	* the app — resolves it, so the dialog cannot be tricked into labeling a
 	* grant with the wrong space.
@@ -3380,6 +3761,7 @@ function createAppBridgeCore(config) {
 				const scopes = sanitizeRequestedScopes(data.scopes);
 				const spaceId = typeof data.spaceId === "string" && data.spaceId ? data.spaceId : void 0;
 				const selectSpace = data.selectSpace === true && !spaceId;
+				const createSpace = data.createSpace === void 0 ? void 0 : sanitizeCreateSpaceInput(data.createSpace);
 				const alwaysAsk = data.alwaysAsk === true;
 				if (scopes.length === 0) {
 					replyForRequest(data.requestId, {
@@ -3388,6 +3770,43 @@ function createAppBridgeCore(config) {
 					}, true);
 					return;
 				}
+				if (data.createSpace !== void 0 && !createSpace) {
+					const named = isRecord(data.createSpace) && typeof data.createSpace.name === "string" && Boolean(data.createSpace.name.trim());
+					replyForRequest(data.requestId, {
+						type: "cohub.app.error",
+						message: named ? "Invalid space create input." : "Space name is required."
+					}, true);
+					return;
+				}
+				if (createSpace && (selectSpace || spaceId)) {
+					replyForRequest(data.requestId, {
+						type: "cohub.app.error",
+						message: "createSpace cannot be combined with spaceId or selectSpace."
+					}, true);
+					return;
+				}
+				if (state.authSaving) {
+					replyForRequest(data.requestId, {
+						type: "cohub.app.error",
+						message: "Another authorization is already in progress."
+					}, true);
+					return;
+				}
+				if (state.pendingAuth) dismissPendingAuth();
+				if (createSpace) {
+					mintedSpace = null;
+					state.pendingAuth = {
+						requestId: data.requestId,
+						scopes,
+						reason: sanitizeReason(data.reason),
+						homeSpaceName: app.spaceName ?? null,
+						createSpace
+					};
+					state.authError = null;
+					state.authOpen = true;
+					notify();
+					return;
+				}
 				if (!selectSpace && !alwaysAsk && allowsOwnerAutoAuthorization() && await isCurrentViewerAppOwner()) try {
 					const result = await authorize(scopes, spaceId, { silent: true });
 					replyForRequest(data.requestId, authorizeResult(result.token, result.spaceId, result.spaceId === app.spaceId ? app.spaceName ?? null : null), true);
@@ -3443,16 +3862,22 @@ function createAppBridgeCore(config) {
 			}, true);
 		}
 	}
-	function cancelAuth() {
-		if (state.authSaving) return;
+	function dismissPendingAuth() {
 		if (!state.pendingAuth) return;
 		replyForRequest(state.pendingAuth.requestId, {
 			type: "cohub.app.authorize.result",
 			token: null
 		}, true);
-		state.authOpen = false;
 		state.pendingAuth = null;
+		state.authOpen = false;
 		state.authError = null;
+		mintedSpace = null;
+		notify();
+	}
+	function cancelAuth() {
+		if (state.authSaving) return;
+		if (!state.pendingAuth) return;
+		dismissPendingAuth();
 		state.authSaving = false;
 		notify();
 	}
@@ -3501,14 +3926,27 @@ function createAppBridgeCore(config) {
 		state.authSaving = true;
 		notify();
 		try {
-			const requestedSpaceId = pending.selectSpace ? pickedSpaceId : pending.spaceId;
+			let requestedSpaceId = pending.selectSpace ? pickedSpaceId : pending.spaceId;
+			let spaceName = pending.selectSpace ? pending.spaces?.find((space) => space.id === requestedSpaceId)?.name ?? null : pending.spaceName ?? app.spaceName ?? null;
+			if (pending.createSpace) {
+				mintedSpace ??= await createViewerSpace(pending.createSpace);
+				if (!mintedSpace.provisioned) {
+					replyForRequest(pending.requestId, authorizeResult(null, mintedSpace.id, mintedSpace.name ?? pending.createSpace.name), true);
+					state.authOpen = false;
+					state.pendingAuth = null;
+					mintedSpace = null;
+					return;
+				}
+				requestedSpaceId = mintedSpace.id;
+				spaceName = mintedSpace.name ?? pending.createSpace.name;
+			}
 			const result = await authorize(pending.scopes, requestedSpaceId);
 			setGrantedAppScopes(await getViewerUuid(), app.id, result.scopes, result.spaceId);
-			if (pending.selectSpace) writeLastPickedSpace(result.spaceId);
-			const spaceName = pending.selectSpace ? pending.spaces?.find((space) => space.id === result.spaceId)?.name ?? null : pending.spaceName ?? app.spaceName ?? null;
+			if (pending.selectSpace || pending.createSpace) writeLastPickedSpace(result.spaceId);
 			replyForRequest(pending.requestId, authorizeResult(result.token, result.spaceId, spaceName), true);
 			state.authOpen = false;
 			state.pendingAuth = null;
+			mintedSpace = null;
 		} catch (error) {
 			state.authError = error instanceof Error ? error.message : "Authorization failed.";
 		} finally {
@@ -3704,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}`);
@@ -3737,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",
@@ -3758,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, 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 };