@neta-art/cohub 8.10.2 → 8.11.0

package/dist/index.js

@@ -891,14 +891,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 +928,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 +936,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 +1172,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 +1187,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 +1207,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 +1289,17 @@ const buildAppRuntimeReady = () => ({
 	version: 1,
 	type: "ready"
 });
+const buildAppRuntimeCloseRequest = () => ({
+	protocol: APP_RUNTIME_PROTOCOL,
+	version: 1,
+	type: "close.request"
+});
 //#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 +1315,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 +1330,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 +1344,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 +2026,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 +2131,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 +2444,14 @@ 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());
+	}
 	async getAccessToken(options) {
 		await this.ensureStorageKeys();
 		if (this.token && !options?.forceRefresh) return this.token;
@@ -2442,6 +2549,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; the app never calls `POST /api/spaces` itself.
+	* `{ 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 +2755,20 @@ 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(),
+		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 +3136,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 +3339,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);
@@ -3225,6 +3458,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 +3652,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 +3661,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 +3753,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 +3817,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 {
@@ -3758,4 +4087,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, 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 };

package/docs/app-runtime-guide.md

@@ -61,13 +61,14 @@ requiring the viewer to paste an API key.
 └─────────────────────────────────────────┘
 ```
 
-Five runtime-only APIs form the foundation; everything else is standard SDK:
+These runtime-only APIs form the foundation; everything else is standard SDK:
 
 | API | What it does | Returns |
 |---|---|---|
 | `client.context()` | Asks the host for the App's identity | `{ app, space, viewer?, invocation?, permissions }` or `null` |
 | `client.auth.request({ scopes, reason, spaceId?, alwaysAsk? })` | Ensures the app holds these scopes; silent when a grant already covers them, consent dialog otherwise | `true` / `false` |
 | `client.auth.requestSpace({ scopes, reason, alwaysAsk? })` | One consent: the viewer picks a Space and grants the scopes on it | `{ granted, space }` |
+| `client.auth.requestCreateSpace({ scopes, space, reason })` | One consent: create a viewer-owned Space (`CreateSpaceInput`) and grant the scopes on it | `{ granted, space }` |
 | `client.context().permissions.viewerGrants` | Render the viewer's current per-space grants | `{ spaceId, scopes }[]` |
 | `client.app.commerce.*` / `client.app.realtime.*` | Commerce and realtime, bound to the app's runtime identity | (see below) |
 
@@ -206,7 +207,7 @@ command.execute          — run sandbox shell commands
 ### Viewer grants (consent-required, any permission, per Space)
 
 A viewer grants these through a consent dialog triggered by
-`client.auth.request()` / `client.auth.requestSpace()`. A viewer may grant
+`client.auth.request()` / `client.auth.requestSpace()` / `client.auth.requestCreateSpace()`. A viewer may grant
 **any** permission they currently hold on the target Space — including scopes
 outside the eight app scopes, such as `generation.create` or the account-level
 `user.*` scopes. Two hard rules are enforced by the server:
@@ -260,10 +261,29 @@ const { granted, space } = await client.auth.requestSpace({
 if (granted && space) {
   const picked = client.space(space.id);
 }
+
+// Create a viewer-owned Space and grant on it — never silent. `space` is the
+// same `CreateSpaceInput` as `client.spaces.create()` (blank, git, or checkpoint).
+const created = await client.auth.requestCreateSpace({
+  scopes: ["file.view", "session.view", "session.prompt.fullaccess"],
+  space: {
+    name: "Whale Shrine",
+    bootstrapSource: { type: "checkpoint", checkpointId },
+  },
+  reason: "Create a workspace from this template.",
+});
+if (created.granted && created.space) {
+  const next = client.space(created.space.id);
+}
+// `granted: false` with a `space` means the Space was created but bootstrap
+// did not finish — no grant was issued. A deny is `{ granted: false, space: null }`.
 ```
 
 Pass `alwaysAsk: true` to skip silent reuse and force a fresh dialog — for
 re-confirming a grant or letting the viewer switch to another Space.
+`requestCreateSpace` always opens the dialog; each confirm mints a new Space.
+The host creates it with the viewer's account token — the app never calls
+`POST /api/spaces` itself.
 
 ### Checking grant state at runtime
 
@@ -318,6 +338,7 @@ dialog can.
 | Read task run detail | `client.tasks.get(taskRunId)` | `taskrun.view` | app or viewer |
 | List tasks in a Space | `client.tasks.list({ spaceId })` | `taskrun.view` on that Space | app or viewer |
 | List all owned task runs | `client.tasks.list()` | `user.taskrun.list` | **viewer only** |
+| Create a Space for the viewer | `client.auth.requestCreateSpace({ space, scopes })` | requested scopes on the new Space | **viewer consent** |
 | List viewer's spaces | `client.spaces.list()` | `user.space.list` | **viewer only** |
 | List viewer's sessions | `client.user.listSessions()` | `user.session.list` | **viewer only** |
 | Read viewer's activity | `client.user.getActivity()` | `user.usage.read` | **viewer only** |
@@ -1204,7 +1225,8 @@ Before publishing your App, verify each item:
   on page load. It is safe to call repeatedly — covered scopes renew silently.
 - [ ] **Cross-Space access targets the right Space** — viewer grants are per
   Space. Pass `spaceId` when requesting, or use `auth.requestSpace` to let the
-  viewer pick.
+  viewer pick. Use `auth.requestCreateSpace` when the app should mint a new
+  viewer-owned Space; do not call `spaces.create()` with the App token.
 - [ ] **`subscribeGeneration` errors are not silently swallowed** — if the
   stream fails, surface it; a silent fallback to polling will also 403 if
   `session.view` is missing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neta-art/cohub",
-  "version": "8.10.2",
+  "version": "8.11.0",
   "description": "Cohub SDK for spaces, sessions, boards, and realtime agent collaboration.",
   "license": "Apache-2.0",
   "private": false,