@btst/stack 2.5.6 → 2.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btst/stack",
-  "version": "2.5.6",
+  "version": "2.6.1",
   "description": "A composable, plugin-based library for building full-stack applications.",
   "repository": {
     "type": "git",
@@ -21,11 +21,15 @@
     "access": "public"
   },
   "scripts": {
-    "build": "unbuild --clean && node ./scripts/postbuild.cjs",
-    "build:analyze": "ANALYZE=1 unbuild --clean && node ./scripts/postbuild.cjs",
+    "build": "NODE_OPTIONS='--max-old-space-size=8192' unbuild --clean && node ./scripts/postbuild.cjs",
+    "build:analyze": "NODE_OPTIONS='--max-old-space-size=8192' ANALYZE=1 unbuild --clean && node ./scripts/postbuild.cjs",
     "stub": "unbuild --stub",
     "test": "vitest",
-    "typecheck": "tsc --project tsconfig.json"
+    "typecheck": "tsc --project tsconfig.json",
+    "knip": "knip --strict",
+    "build-registry": "tsx scripts/build-registry.ts",
+    "test-registry": "bash scripts/test-registry.sh",
+    "host-registry": "npx http-server registry -p 8766 -c-1"
   },
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -123,6 +127,16 @@
         "default": "./dist/plugins/blog/client/index.cjs"
       }
     },
+    "./plugins/blog/client/hooks": {
+      "import": {
+        "types": "./dist/plugins/blog/client/hooks/index.d.ts",
+        "default": "./dist/plugins/blog/client/hooks/index.mjs"
+      },
+      "require": {
+        "types": "./dist/plugins/blog/client/hooks/index.d.cts",
+        "default": "./dist/plugins/blog/client/hooks/index.cjs"
+      }
+    },
     "./plugins/ai-chat/api": {
       "import": {
         "types": "./dist/plugins/ai-chat/api/index.d.ts",
@@ -360,6 +374,77 @@
       }
     },
     "./plugins/route-docs/css": "./dist/plugins/route-docs/style.css",
+    "./components/markdown": {
+      "import": {
+        "types": "./dist/components/markdown/index.d.ts",
+        "default": "./dist/components/markdown/index.mjs"
+      },
+      "require": {
+        "types": "./dist/components/markdown/index.d.cts",
+        "default": "./dist/components/markdown/index.cjs"
+      }
+    },
+    "./components/markdown/css": "./dist/components/markdown/style.css",
+    "./components/auto-form": {
+      "import": {
+        "types": "./dist/components/auto-form/index.d.ts",
+        "default": "./dist/components/auto-form/index.mjs"
+      },
+      "require": {
+        "types": "./dist/components/auto-form/index.d.cts",
+        "default": "./dist/components/auto-form/index.cjs"
+      }
+    },
+    "./components/stepped-auto-form": {
+      "import": {
+        "types": "./dist/components/stepped-auto-form/index.d.ts",
+        "default": "./dist/components/stepped-auto-form/index.mjs"
+      },
+      "require": {
+        "types": "./dist/components/stepped-auto-form/index.d.cts",
+        "default": "./dist/components/stepped-auto-form/index.cjs"
+      }
+    },
+    "./components/form-builder": {
+      "import": {
+        "types": "./dist/components/form-builder/index.d.ts",
+        "default": "./dist/components/form-builder/index.mjs"
+      },
+      "require": {
+        "types": "./dist/components/form-builder/index.d.cts",
+        "default": "./dist/components/form-builder/index.cjs"
+      }
+    },
+    "./components/multi-select": {
+      "import": {
+        "types": "./dist/components/multi-select/index.d.ts",
+        "default": "./dist/components/multi-select/index.mjs"
+      },
+      "require": {
+        "types": "./dist/components/multi-select/index.d.cts",
+        "default": "./dist/components/multi-select/index.cjs"
+      }
+    },
+    "./components/search-select": {
+      "import": {
+        "types": "./dist/components/search-select/index.d.ts",
+        "default": "./dist/components/search-select/index.mjs"
+      },
+      "require": {
+        "types": "./dist/components/search-select/index.d.cts",
+        "default": "./dist/components/search-select/index.cjs"
+      }
+    },
+    "./components/empty": {
+      "import": {
+        "types": "./dist/components/empty/index.d.ts",
+        "default": "./dist/components/empty/index.mjs"
+      },
+      "require": {
+        "types": "./dist/components/empty/index.d.cts",
+        "default": "./dist/components/empty/index.cjs"
+      }
+    },
     "./dist/*": "./dist/*",
     "./ui/css": "./dist/ui/components.css",
     "./package.json": "./package.json"
@@ -390,6 +475,9 @@
       "plugins/blog/client": [
         "./dist/plugins/blog/client/index.d.ts"
       ],
+      "plugins/blog/client/hooks": [
+        "./dist/plugins/blog/client/hooks/index.d.ts"
+      ],
       "plugins/ai-chat/api": [
         "./dist/plugins/ai-chat/api/index.d.ts"
       ],
@@ -458,6 +546,27 @@
       ],
       "plugins/route-docs/client": [
         "./dist/plugins/route-docs/client/index.d.ts"
+      ],
+      "components/markdown": [
+        "./dist/components/markdown/index.d.ts"
+      ],
+      "components/auto-form": [
+        "./dist/components/auto-form/index.d.ts"
+      ],
+      "components/stepped-auto-form": [
+        "./dist/components/stepped-auto-form/index.d.ts"
+      ],
+      "components/form-builder": [
+        "./dist/components/form-builder/index.d.ts"
+      ],
+      "components/multi-select": [
+        "./dist/components/multi-select/index.d.ts"
+      ],
+      "components/search-select": [
+        "./dist/components/search-select/index.d.ts"
+      ],
+      "components/empty": [
+        "./dist/components/empty/index.d.ts"
       ]
     }
   },
@@ -505,6 +614,7 @@
     "zod": ">=4.2.0"
   },
   "devDependencies": {
+    "tsx": "catalog:",
     "@ai-sdk/react": "^2.0.94",
     "@btst/adapter-memory": "2.0.3",
     "@btst/yar": "1.2.0",
@@ -516,6 +626,7 @@
     "react": "^19.1.1",
     "react-dom": "^19.1.1",
     "react-error-boundary": "^4.1.2",
+    "knip": "^5.61.2",
     "rollup-plugin-preserve-directives": "0.4.0",
     "rollup-plugin-visualizer": "^5.12.0",
     "typescript": "catalog:",

package/src/__tests__/page-component-overrides.test.tsx

@@ -0,0 +1,147 @@
+import { describe, it, expect } from "vitest";
+import { defineClientPlugin } from "../plugins/client";
+import type { ComponentType } from "react";
+import { createRoute } from "@btst/yar";
+
+/**
+ * Default page components used by the mock plugin factory.
+ * These stand in for the real plugin page components (e.g. HomePageComponent).
+ */
+const DefaultListComponent: ComponentType = () => <div>Default List</div>;
+const DefaultDetailComponent: ComponentType<{ id: string }> = ({ id }) => (
+	<div>Default Detail {id}</div>
+);
+
+/**
+ * Lightweight mock plugin factory that mirrors the real plugin pattern:
+ * - Accepts a config with an optional `pageComponents` field
+ * - Falls back to built-in components when no override is provided
+ * - For param routes, extracts the override before the handler closure
+ */
+function createTestPlugin(config: {
+	pageComponents?: {
+		list?: ComponentType;
+		detail?: ComponentType<{ id: string }>;
+	};
+}) {
+	return defineClientPlugin({
+		name: "test",
+		routes: () => ({
+			list: createRoute("/items", () => {
+				const CustomList = config.pageComponents?.list;
+				return {
+					PageComponent: CustomList ?? DefaultListComponent,
+				};
+			}),
+			detail: createRoute("/items/:id", ({ params }) => {
+				const CustomDetail = config.pageComponents?.detail;
+				return {
+					PageComponent: CustomDetail
+						? () => <CustomDetail id={params.id} />
+						: () => <DefaultDetailComponent id={params.id} />,
+				};
+			}),
+		}),
+	});
+}
+
+describe("pageComponents overrides", () => {
+	describe("default components used when no override provided", () => {
+		it("uses the default component for a no-param route", () => {
+			const plugin = createTestPlugin({});
+			const routes = plugin.routes();
+			const routeData = routes.list();
+
+			expect(routeData.PageComponent).toBe(DefaultListComponent);
+		});
+
+		it("uses the default component wrapper for a param route", () => {
+			const plugin = createTestPlugin({});
+			const routes = plugin.routes();
+			const routeData = routes.detail({ params: { id: "42" } });
+
+			// Should be an inline wrapper, not the custom component
+			expect(routeData.PageComponent).toBeDefined();
+			expect(typeof routeData.PageComponent).toBe("function");
+			// Verify it is NOT the custom component (no override was given)
+			const CustomDetail: ComponentType<{ id: string }> = () => (
+				<div>Custom</div>
+			);
+			expect(routeData.PageComponent).not.toBe(CustomDetail);
+		});
+	});
+
+	describe("custom component replaces default (no-param route)", () => {
+		it("uses the provided override instead of the default", () => {
+			const CustomList: ComponentType = () => <div>Custom List</div>;
+
+			const plugin = createTestPlugin({
+				pageComponents: { list: CustomList },
+			});
+			const routes = plugin.routes();
+			const routeData = routes.list();
+
+			expect(routeData.PageComponent).toBe(CustomList);
+			expect(routeData.PageComponent).not.toBe(DefaultListComponent);
+		});
+
+		it("leaves other routes using their defaults when only one is overridden", () => {
+			const CustomList: ComponentType = () => <div>Custom List</div>;
+
+			const plugin = createTestPlugin({
+				pageComponents: { list: CustomList },
+			});
+			const routes = plugin.routes();
+
+			// list uses custom
+			expect(routes.list().PageComponent).toBe(CustomList);
+
+			// detail still uses a wrapper (no override)
+			const detailData = routes.detail({ params: { id: "1" } });
+			expect(detailData.PageComponent).not.toBe(CustomList);
+		});
+	});
+
+	describe("custom component replaces default (param route)", () => {
+		it("uses the override wrapper for a param route", () => {
+			const CustomDetail: ComponentType<{ id: string }> = ({ id }) => (
+				<div>Custom Detail {id}</div>
+			);
+
+			const plugin = createTestPlugin({
+				pageComponents: { detail: CustomDetail },
+			});
+			const routes = plugin.routes();
+			const routeData = routes.detail({ params: { id: "42" } });
+
+			// Should be an inline wrapper (not the raw CustomDetail directly)
+			expect(routeData.PageComponent).toBeDefined();
+			expect(typeof routeData.PageComponent).toBe("function");
+			// Should NOT be the default
+			expect(routeData.PageComponent).not.toBe(DefaultDetailComponent);
+		});
+
+		it("produces a different PageComponent than when no override is given", () => {
+			const CustomDetail: ComponentType<{ id: string }> = ({ id }) => (
+				<div>Custom Detail {id}</div>
+			);
+
+			const defaultPlugin = createTestPlugin({});
+			const overridePlugin = createTestPlugin({
+				pageComponents: { detail: CustomDetail },
+			});
+
+			const defaultRouteData = defaultPlugin
+				.routes()
+				.detail({ params: { id: "1" } });
+			const overrideRouteData = overridePlugin
+				.routes()
+				.detail({ params: { id: "1" } });
+
+			// The wrapped component should be a different function reference
+			expect(overrideRouteData.PageComponent).not.toBe(
+				defaultRouteData.PageComponent,
+			);
+		});
+	});
+});

package/src/components/auto-form/index.ts

@@ -0,0 +1,12 @@
+export {
+	default as AutoForm,
+	AutoFormSubmit,
+} from "@workspace/ui/components/auto-form";
+export type {
+	FieldConfig,
+	FieldConfigItem,
+	Dependency,
+	DependencyType,
+	AutoFormInputComponentProps,
+} from "@workspace/ui/components/auto-form/types";
+export type { ZodObjectOrWrapped } from "@workspace/ui/components/auto-form/helpers";

package/src/components/empty/index.ts

@@ -0,0 +1,8 @@
+export {
+	Empty,
+	EmptyHeader,
+	EmptyTitle,
+	EmptyDescription,
+	EmptyContent,
+	EmptyMedia,
+} from "@workspace/ui/components/empty";

package/src/components/form-builder/index.ts

@@ -0,0 +1,23 @@
+export {
+	FormBuilder,
+	defaultComponents,
+	objectFieldDefinition,
+	arrayFieldDefinition,
+	defineComponent,
+	baseMetaSchema,
+	baseMetaSchemaWithPlaceholder,
+} from "@workspace/ui/components/form-builder";
+export type {
+	FormBuilderComponentDefinition,
+	FormBuilderField,
+	FormBuilderFieldProps,
+	JSONSchema,
+	JSONSchemaProperty,
+	StringFieldProps,
+} from "@workspace/ui/components/form-builder";
+export type {
+	FormStep,
+	BackingType,
+	ComponentType,
+	TypedFieldProps,
+} from "@workspace/ui/components/form-builder/types";

package/src/components/kanban/index.ts

@@ -0,0 +1,9 @@
+export {
+	Kanban,
+	KanbanBoard,
+	KanbanColumn,
+	KanbanColumnHandle,
+	KanbanItem,
+	KanbanItemHandle,
+	KanbanOverlay,
+} from "@workspace/ui/components/kanban";

package/src/components/markdown/index.ts

@@ -0,0 +1,5 @@
+export { MarkdownContent } from "@workspace/ui/components/markdown-content";
+export type { MarkdownContentProps } from "@workspace/ui/components/markdown-content";
+
+export { MarkdownEditor } from "../../plugins/blog/client/components/forms/markdown-editor";
+export type { MarkdownEditorProps } from "../../plugins/blog/client/components/forms/markdown-editor";

package/src/components/markdown/style.css

@@ -0,0 +1,3 @@
+@import "@workspace/ui/markdown-content.css";
+@import "@milkdown/crepe/theme/common/style.css";
+@import "../../plugins/blog/client/components/forms/markdown-editor-styles.css";

package/src/components/minimal-tiptap/index.ts

@@ -0,0 +1,5 @@
+export {
+	MinimalTiptapEditor,
+	MainMinimalTiptapEditor,
+} from "@workspace/ui/components/minimal-tiptap";
+export type { MinimalTiptapProps } from "@workspace/ui/components/minimal-tiptap";

package/src/components/minimal-tiptap/style.css

@@ -0,0 +1 @@
+@import "@workspace/ui/components/minimal-tiptap/styles.css";

package/src/components/multi-select/index.ts

@@ -0,0 +1,5 @@
+export { default as MultipleSelector } from "@workspace/ui/components/multi-select";
+export type {
+	Option,
+	MultipleSelectorRef,
+} from "@workspace/ui/components/multi-select";

package/src/components/search-select/index.ts

@@ -0,0 +1 @@
+export { default as SearchSelect } from "@workspace/ui/components/search-select";

package/src/components/stepped-auto-form/index.ts

@@ -0,0 +1,5 @@
+export { SteppedAutoForm } from "@workspace/ui/components/auto-form/stepped-auto-form";
+export type {
+	SteppedAutoFormProps,
+	StepperComponentProps,
+} from "@workspace/ui/components/auto-form/stepped-auto-form";

package/src/components/ui-builder/index.ts

@@ -0,0 +1,50 @@
+// Editor component
+export {
+	default as UIBuilder,
+	PageConfigPanel,
+	defaultConfigTabsContent,
+	LoadingSkeleton,
+	getDefaultPanelConfigValues,
+} from "@workspace/ui/components/ui-builder";
+export type { TabsContentConfig } from "@workspace/ui/components/ui-builder";
+
+// Page renderers
+export { default as LayerRenderer } from "@workspace/ui/components/ui-builder/layer-renderer";
+export { ServerLayerRenderer } from "@workspace/ui/components/ui-builder/server-layer-renderer";
+export type { ServerLayerRendererProps } from "@workspace/ui/components/ui-builder/server-layer-renderer";
+
+// Types
+export type {
+	ComponentLayer,
+	ComponentRegistry,
+	Variable,
+	VariableReference,
+	FunctionRegistry,
+	BlockRegistry,
+	LayerChangeHandler,
+	VariableChangeHandler,
+	RegistryEntry,
+	PropValue,
+	BlockDefinition,
+	FunctionDefinition,
+} from "@workspace/ui/components/ui-builder/types";
+export {
+	isVariableReference,
+	createVariable,
+} from "@workspace/ui/components/ui-builder/types";
+
+// Registry utilities and field override helpers
+export {
+	createComponentRegistry,
+	defaultComponentRegistry,
+	primitiveComponentDefinitions,
+	complexComponentDefinitions,
+} from "../../plugins/ui-builder/client/registry";
+export {
+	classNameFieldOverrides,
+	childrenFieldOverrides,
+	iconNameFieldOverrides,
+	commonFieldOverrides,
+	childrenAsTipTapFieldOverrides,
+	childrenAsTextareaFieldOverrides,
+} from "@workspace/ui/lib/ui-builder/registry/form-field-overrides";

package/src/components/ui-builder/style.css

@@ -0,0 +1,5 @@
+/* Import minimal-tiptap styles for rich text editor in form field overrides */
+@import "@workspace/ui/components/minimal-tiptap/styles.css";
+
+/* Load Tailwind Typography plugin for prose classes used by Markdown component */
+@plugin "@tailwindcss/typography";

package/src/plugins/ai-chat/client/components/shared/default-error.tsx

@@ -21,7 +21,7 @@ export function DefaultError({ error }: FallbackProps) {
 		process.env.NODE_ENV === "production"
 			? (localization?.CHAT_GENERIC_ERROR_MESSAGE ??
 				AI_CHAT_LOCALIZATION.CHAT_GENERIC_ERROR_MESSAGE)
-			: (error?.message ??
+			: ((error instanceof Error ? error.message : undefined) ??
 				localization?.CHAT_GENERIC_ERROR_MESSAGE ??
 				AI_CHAT_LOCALIZATION.CHAT_GENERIC_ERROR_MESSAGE);
 	return <ErrorPlaceholder title={title} message={message} />;

package/src/plugins/ai-chat/client/plugin.tsx

@@ -4,6 +4,7 @@ import {
 	runClientHookWithShim,
 } from "@btst/stack/plugins/client";
 import { createRoute } from "@btst/yar";
+import type { ComponentType } from "react";
 import type { QueryClient } from "@tanstack/react-query";
 import type { AiChatApiRouter } from "../api";
 import { createAiChatQueryKeys } from "../query-keys";
@@ -85,6 +86,18 @@ export interface AiChatClientConfig {
 
 	/** Optional headers for SSR (e.g., forwarding cookies) */
 	headers?: Headers;
+
+	/**
+	 * Optional page component overrides.
+	 * Replace any plugin page with a custom React component.
+	 * The built-in component is used as the fallback when not provided.
+	 */
+	pageComponents?: {
+		/** Replaces the chat home page */
+		chat?: ComponentType;
+		/** Replaces the conversation page (authenticated mode only) */
+		chatConversation?: ComponentType<{ conversationId: string }>;
+	};
 }
 
 /**
@@ -381,17 +394,22 @@ export const aiChatClientPlugin = (config: AiChatClientConfig) => {
 
 			routes: () => ({
 				// Chat home - simple chat interface without history
-				chat: createRoute("/chat", () => ({
-					PageComponent: () => (
-						<ChatLayout
-							apiBaseURL={config.apiBaseURL}
-							apiBasePath={config.apiBasePath}
-							showSidebar={false}
-						/>
-					),
-					loader: createConversationsLoader(config),
-					meta: createChatHomeMeta(config),
-				})),
+				chat: createRoute("/chat", () => {
+					const CustomChat = config.pageComponents?.chat;
+					return {
+						PageComponent:
+							CustomChat ??
+							(() => (
+								<ChatLayout
+									apiBaseURL={config.apiBaseURL}
+									apiBasePath={config.apiBasePath}
+									showSidebar={false}
+								/>
+							)),
+						loader: createConversationsLoader(config),
+						meta: createChatHomeMeta(config),
+					};
+				}),
 			}),
 
 			sitemap: async () => [],
@@ -404,29 +422,39 @@ export const aiChatClientPlugin = (config: AiChatClientConfig) => {
 
 		routes: () => ({
 			// Chat home - new conversation or list
-			chat: createRoute("/chat", () => ({
-				PageComponent: () => (
-					<ChatLayout
-						apiBaseURL={config.apiBaseURL}
-						apiBasePath={config.apiBasePath}
-					/>
-				),
-				loader: createConversationsLoader(config),
-				meta: createChatHomeMeta(config),
-			})),
+			chat: createRoute("/chat", () => {
+				const CustomChat = config.pageComponents?.chat;
+				return {
+					PageComponent:
+						CustomChat ??
+						(() => (
+							<ChatLayout
+								apiBaseURL={config.apiBaseURL}
+								apiBasePath={config.apiBasePath}
+							/>
+						)),
+					loader: createConversationsLoader(config),
+					meta: createChatHomeMeta(config),
+				};
+			}),
 
 			// Existing conversation
-			chatConversation: createRoute("/chat/:id", ({ params }) => ({
-				PageComponent: () => (
-					<ChatLayout
-						apiBaseURL={config.apiBaseURL}
-						apiBasePath={config.apiBasePath}
-						conversationId={params.id}
-					/>
-				),
-				loader: createConversationLoader(params.id, config),
-				meta: createConversationMeta(params.id, config),
-			})),
+			chatConversation: createRoute("/chat/:id", ({ params }) => {
+				const CustomConversation = config.pageComponents?.chatConversation;
+				return {
+					PageComponent: CustomConversation
+						? () => <CustomConversation conversationId={params.id} />
+						: () => (
+								<ChatLayout
+									apiBaseURL={config.apiBaseURL}
+									apiBasePath={config.apiBasePath}
+									conversationId={params.id}
+								/>
+							),
+					loader: createConversationLoader(params.id, config),
+					meta: createConversationMeta(params.id, config),
+				};
+			}),
 		}),
 
 		// Chat pages typically shouldn't be in sitemap, but we provide the option

package/src/plugins/blog/client/components/forms/markdown-editor-with-overrides.tsx

@@ -0,0 +1,29 @@
+"use client";
+import { usePluginOverrides } from "@btst/stack/context";
+import type { BlogPluginOverrides } from "../../overrides";
+import { BLOG_LOCALIZATION } from "../../localization";
+import { MarkdownEditor, type MarkdownEditorProps } from "./markdown-editor";
+
+type MarkdownEditorWithOverridesProps = Omit<
+	MarkdownEditorProps,
+	"uploadImage" | "placeholder"
+>;
+
+export function MarkdownEditorWithOverrides(
+	props: MarkdownEditorWithOverridesProps,
+) {
+	const { uploadImage, localization } = usePluginOverrides<
+		BlogPluginOverrides,
+		Partial<BlogPluginOverrides>
+	>("blog", {
+		localization: BLOG_LOCALIZATION,
+	});
+
+	return (
+		<MarkdownEditor
+			{...props}
+			uploadImage={uploadImage}
+			placeholder={localization?.BLOG_FORMS_EDITOR_PLACEHOLDER}
+		/>
+	);
+}