@btst/stack 2.3.0 → 2.5.0

package/src/plugins/ui-builder/client/components/pages/page-builder-page.internal.tsx

@@ -22,9 +22,12 @@ import { toast } from "sonner";
 import UIBuilder from "@workspace/ui/components/ui-builder";
 import type {
 	ComponentLayer,
+	ComponentRegistry,
 	Variable,
 } from "@workspace/ui/components/ui-builder/types";
 
+import { useLayerStore } from "@workspace/ui/lib/ui-builder/store/layer-store";
+import { useRegisterPageAIContext } from "@btst/stack/plugins/ai-chat/client/context";
 import {
 	useSuspenseUIBuilderPage,
 	useCreateUIBuilderPage,
@@ -39,6 +42,104 @@ export interface PageBuilderPageProps {
 	id?: string;
 }
 
+/**
+ * Generate a concise AI-readable description of the available components
+ * in the component registry, including their prop names.
+ */
+function buildRegistryDescription(registry: ComponentRegistry): string {
+	const lines: string[] = [];
+	for (const [name, entry] of Object.entries(registry) as [
+		string,
+		{ schema?: unknown },
+	][]) {
+		let propsLine = "";
+		try {
+			const shape = (entry.schema as any)?.shape as
+				| Record<string, unknown>
+				| undefined;
+			if (shape) {
+				const fields = Object.keys(shape).join(", ");
+				propsLine = ` — props: ${fields}`;
+			}
+		} catch {
+			// ignore schema introspection errors
+		}
+		lines.push(`- ${name}${propsLine}`);
+	}
+	return lines.join("\n");
+}
+
+/**
+ * Build the full page description string for the AI context.
+ * Stays within the 8,000-character pageContext limit.
+ */
+function buildPageDescription(
+	id: string | undefined,
+	slug: string,
+	layers: ComponentLayer[],
+	registry: ComponentRegistry,
+): string {
+	const header = id
+		? `UI Builder — editing page (slug: "${slug}")`
+		: "UI Builder — creating new page";
+
+	const layersJson = JSON.stringify(layers, null, 2);
+
+	const registryDesc = buildRegistryDescription(registry);
+
+	const layerFormat = `Each layer: { id: string, type: string, name: string, props: Record<string,any>, children?: ComponentLayer[] | string }`;
+
+	const full = [
+		header,
+		"",
+		`## Current Layers (${layers.length})`,
+		layersJson,
+		"",
+		`## Available Component Types`,
+		registryDesc,
+		"",
+		`## ComponentLayer format`,
+		layerFormat,
+	].join("\n");
+
+	// Trim to fit the 16,000-char server-side limit, cutting the layers JSON if needed
+	if (full.length <= 16000) return full;
+
+	// Re-build with truncated layers JSON
+	const overhead =
+		[
+			header,
+			"",
+			`## Current Layers (${layers.length})`,
+			"",
+			"",
+			`## Available Component Types`,
+			registryDesc,
+			"",
+			`## ComponentLayer format`,
+			layerFormat,
+		].join("\n").length + 30; // 30-char buffer for "...(truncated)"
+
+	const budget = Math.max(0, 16000 - overhead);
+	const truncatedLayers =
+		layersJson.length > budget
+			? layersJson.slice(0, budget) + "\n...(truncated)"
+			: layersJson;
+
+	return [
+		header,
+		"",
+		`## Current Layers (${layers.length})`,
+		truncatedLayers,
+		"",
+		`## Available Component Types`,
+		registryDesc,
+		"",
+		`## ComponentLayer format`,
+		layerFormat,
+	].join("\n");
+}
+
 /**
  * Slugify a string for URL-friendly slugs
  */
@@ -139,6 +240,37 @@ function PageBuilderPageContent({
 	// Auto-generate slug from first page name
 	const [autoSlug, setAutoSlug] = useState(!id);
 
+	// Register AI context so the chat can update the page layout
+	useRegisterPageAIContext({
+		routeName: id ? "ui-builder-edit-page" : "ui-builder-new-page",
+		pageDescription: buildPageDescription(id, slug, layers, componentRegistry),
+		suggestions: [
+			"Add a hero section",
+			"Add a 3-column feature grid",
+			"Make the layout full-width",
+			"Add a card with a title, description, and button",
+			"Replace the layout with a centered single-column design",
+		],
+		clientTools: {
+			updatePageLayers: async ({ layers: newLayers }) => {
+				// Drive the UIBuilder's Zustand store directly so the editor
+				// and layers panel update immediately. The store's onChange
+				// callback will propagate back to the parent's `layers` state.
+				const store = useLayerStore.getState();
+				store.initialize(
+					newLayers,
+					store.selectedPageId || newLayers[0]?.id,
+					undefined,
+					store.variables,
+				);
+				return {
+					success: true,
+					message: `Applied ${newLayers.length} layer(s) to the page`,
+				};
+			},
+		},
+	});
+
 	// Handle layers change from UIBuilder
 	const handleLayersChange = useCallback(
 		(newLayers: ComponentLayer[]) => {

package/src/plugins/ui-builder/client/plugin.tsx

@@ -3,6 +3,7 @@ import { lazy } from "react";
 import {
 	defineClientPlugin,
 	createApiClient,
+	runClientHookWithShim,
 } from "@btst/stack/plugins/client";
 import { createRoute } from "@btst/yar";
 import type { QueryClient } from "@tanstack/react-query";
@@ -69,10 +70,10 @@ function createPageListLoader(config: UIBuilderClientConfig) {
 			try {
 				// Before hook - authorization check
 				if (hooks?.beforeLoadPageList) {
-					const canLoad = await hooks.beforeLoadPageList(context);
-					if (!canLoad) {
-						throw new Error("Load prevented by beforeLoadPageList hook");
-					}
+					await runClientHookWithShim(
+						() => hooks.beforeLoadPageList!(context),
+						"Load prevented by beforeLoadPageList hook",
+					);
 				}
 
 				const client = createApiClient<CMSApiRouter>({
@@ -161,10 +162,10 @@ function createPageBuilderLoader(
 			try {
 				// Before hook - authorization check
 				if (hooks?.beforeLoadPageBuilder) {
-					const canLoad = await hooks.beforeLoadPageBuilder(id, context);
-					if (!canLoad) {
-						throw new Error("Load prevented by beforeLoadPageBuilder hook");
-					}
+					await runClientHookWithShim(
+						() => hooks.beforeLoadPageBuilder!(id, context),
+						"Load prevented by beforeLoadPageBuilder hook",
+					);
 				}
 
 				const client = createApiClient<CMSApiRouter>({
@@ -273,11 +274,11 @@ function createPageBuilderMeta(
  *   hooks: {
  *     beforeLoadPageList: async (ctx) => {
  *       const session = await getSession(ctx.headers)
- *       return session?.user?.isAdmin === true
+ *       if (!session?.user?.isAdmin) throw new Error("Admin access required")
  *     },
  *     beforeLoadPageBuilder: async (pageId, ctx) => {
  *       const session = await getSession(ctx.headers)
- *       return session?.user?.isAdmin === true
+ *       if (!session?.user?.isAdmin) throw new Error("Admin access required")
  *     },
  *     onLoadError: () => redirect("/auth/sign-in"),
  *   },

package/src/plugins/ui-builder/types.ts

@@ -92,24 +92,24 @@ export interface LoaderContext {
  */
 export interface UIBuilderClientHooks {
 	/**
-	 * Called before loading the page list. Return false to cancel loading.
+	 * Called before loading the page list. Throw an error to cancel loading.
 	 * @param context - Loader context with path, params, etc.
 	 */
-	beforeLoadPageList?: (context: LoaderContext) => Promise<boolean> | boolean;
+	beforeLoadPageList?: (context: LoaderContext) => Promise<void> | void;
 	/**
 	 * Called after the page list is loaded.
 	 * @param context - Loader context
 	 */
 	afterLoadPageList?: (context: LoaderContext) => Promise<void> | void;
 	/**
-	 * Called before loading the page builder. Return false to cancel loading.
+	 * Called before loading the page builder. Throw an error to cancel loading.
 	 * @param pageId - The page ID (undefined for new pages)
 	 * @param context - Loader context
 	 */
 	beforeLoadPageBuilder?: (
 		pageId: string | undefined,
 		context: LoaderContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 	/**
 	 * Called after the page builder is loaded.
 	 * @param pageId - The page ID (undefined for new pages)

package/src/plugins/utils.ts

@@ -1,5 +1,96 @@
 import { createClient } from "better-call/client";
 
+/**
+ * Runs a hook with backward-compatible denial handling.
+ * Hooks may deny by returning a falsy value (old) or throwing (new).
+ * Both are normalized to an HTTP error via `createError` (`ctx.error`).
+ * Returns the hook's result so transform hooks can apply mutations.
+ *
+ * ## Migration note (v2.4 → v2.5)
+ *
+ * Old-style hooks signalled denial by returning `false` and allowance by returning `true`.
+ * Pre-shim call sites used `if (!result)` which treated `undefined` (fall-through) as deny.
+ * New-style hooks throw an Error to deny and return void/undefined to allow.
+ *
+ * The shim detects old-style boolean returns at runtime and emits a deprecation warning so
+ * that any hook with a code path returning a boolean is surfaced immediately. Hooks that fall
+ * through to `undefined` on **every** code path (no boolean return anywhere) cannot be
+ * distinguished from new-style void hooks — those hooks must be audited manually and updated
+ * to throw explicitly when they intend to deny access.
+ */
+export async function runHookWithShim<T>(
+	hookFn: () => Promise<T> | T,
+	createError: (
+		status: keyof typeof statusCodes | Status,
+		body: { message: string },
+	) => any,
+	defaultMessage: string,
+	errorStatus = 403 as keyof typeof statusCodes | Status,
+): Promise<Exclude<Awaited<T>, false>> {
+	let result: Awaited<T>;
+	try {
+		result = await hookFn();
+	} catch (e) {
+		throw createError(errorStatus, {
+			message: e instanceof Error ? e.message : defaultMessage,
+		});
+	}
+	// Detect old-style boolean returns (pre-v2.5 pattern).
+	// Emitting a warning here is the only reliable way to surface hooks that still rely on
+	// boolean returns — including hooks where one branch returns `false` and another falls
+	// through to `undefined`, which was previously denied by `if (!result)` at the call site
+	// but would now silently allow if the warning is not acted on.
+	if (typeof result === "boolean") {
+		if (process.env.NODE_ENV !== "production") {
+			console.warn(
+				`[btst] A lifecycle hook returned a boolean (${result}). ` +
+					`Boolean returns are deprecated — throw an Error to deny access instead. ` +
+					`IMPORTANT: any code path in this hook that falls through to undefined ` +
+					`now ALLOWS access (previously denied). ` +
+					`Update the hook to throw new Error("Unauthorized") to deny.`,
+			);
+		}
+		if (!result) {
+			throw createError(errorStatus, { message: defaultMessage });
+		}
+	}
+	return result as Exclude<Awaited<T>, false>;
+}
+
+/**
+ * Client-side equivalent of runHookWithShim — throws a plain Error instead of an HTTP error.
+ * Hooks may deny by returning false (old) or throwing (new); both normalize to an Error.
+ *
+ * See `runHookWithShim` for the full migration note on boolean-vs-void semantics.
+ */
+export async function runClientHookWithShim<T>(
+	hookFn: () => Promise<T> | T,
+	defaultMessage: string,
+): Promise<Exclude<Awaited<T>, false>> {
+	let result: Awaited<T>;
+	try {
+		result = await hookFn();
+	} catch (e) {
+		throw e instanceof Error ? e : new Error(defaultMessage);
+	}
+	// Detect old-style boolean returns and warn; see runHookWithShim for rationale.
+	if (typeof result === "boolean") {
+		if (process.env.NODE_ENV !== "production") {
+			console.warn(
+				`[btst] A lifecycle hook returned a boolean (${result}). ` +
+					`Boolean returns are deprecated — throw an Error to deny access instead. ` +
+					`IMPORTANT: any code path in this hook that falls through to undefined ` +
+					`now ALLOWS access (previously denied). ` +
+					`Update the hook to throw new Error("Unauthorized") to deny.`,
+			);
+		}
+		if (!result) {
+			throw new Error(defaultMessage);
+		}
+	}
+	return result as Exclude<Awaited<T>, false>;
+}
+
 /**
  * Returns true when a fetch error is a connection-refused / no-server error.
  * Used in SSR loaders to emit an actionable build-time warning when
@@ -18,7 +109,7 @@ export function isConnectionError(err: unknown): boolean {
 		code === "ERR_CONNECTION_REFUSED"
 	);
 }
-import type { Router, Endpoint } from "better-call";
+import type { Router, Endpoint, Status, statusCodes } from "better-call";
 
 interface CreateApiClientOptions {
 	baseURL?: string;

package/dist/shared/{stack.CBON0dWL.d.mts → stack.BQmuNl5p.d.cts}

@@ -42,11 +42,11 @@ declare const createPostSchema: z.ZodObject<{
         name: z.ZodString;
         slug: z.ZodString;
     }, z.core.$strip>]>>>>;
+    title: z.ZodString;
     slug: z.ZodOptional<z.ZodString>;
-    publishedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
     createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
     updatedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
-    title: z.ZodString;
+    publishedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
     content: z.ZodString;
     excerpt: z.ZodString;
     image: z.ZodOptional<z.ZodString>;

package/dist/shared/{stack.CBON0dWL.d.ts → stack.BQmuNl5p.d.mts}

@@ -42,11 +42,11 @@ declare const createPostSchema: z.ZodObject<{
         name: z.ZodString;
         slug: z.ZodString;
     }, z.core.$strip>]>>>>;
+    title: z.ZodString;
     slug: z.ZodOptional<z.ZodString>;
-    publishedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
     createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
     updatedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
-    title: z.ZodString;
+    publishedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
     content: z.ZodString;
     excerpt: z.ZodString;
     image: z.ZodOptional<z.ZodString>;

package/dist/shared/{stack.CBON0dWL.d.cts → stack.BQmuNl5p.d.ts}

@@ -42,11 +42,11 @@ declare const createPostSchema: z.ZodObject<{
         name: z.ZodString;
         slug: z.ZodString;
     }, z.core.$strip>]>>>>;
+    title: z.ZodString;
     slug: z.ZodOptional<z.ZodString>;
-    publishedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
     createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
     updatedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
-    title: z.ZodString;
+    publishedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
     content: z.ZodString;
     excerpt: z.ZodString;
     image: z.ZodOptional<z.ZodString>;