mycelia-kernel-plugin 1.0.0 → 1.2.0

package/README.md

@@ -13,11 +13,16 @@ Mycelia Plugin System is a standalone plugin architecture extracted from [Myceli
 - **Hot reloading** - Reload and extend plugins without full teardown
 - **Facet contracts** - Runtime validation of plugin interfaces
 - **Standalone mode** - Works without message system or other dependencies
+- **Built-in hooks** - Ships with `useListeners` for event-driven architectures (see [Simple Event System Example](#simple-event-system-example)), plus `useQueue` and `useSpeak`
+
+**Facets** are the concrete runtime capabilities produced by hooks and attached to the system.
 
 ## Quick Start
 
+### Using useBase (Recommended)
+
 ```javascript
-import { StandalonePluginSystem, createHook, Facet } from 'mycelia-kernel-plugin';
+import { useBase, createHook, Facet } from 'mycelia-kernel-plugin';
 
 // Create a hook
 const useDatabase = createHook({
@@ -51,6 +56,25 @@ const useDatabase = createHook({
   }
 });
 
+// Create and use the system with fluent API
+const system = await useBase('my-app')
+  .config('database', { host: 'localhost' })
+  .use(useDatabase)
+  .build();
+
+// Use the plugin
+const db = system.find('database');
+await db.query('SELECT * FROM users');
+```
+
+### Using StandalonePluginSystem Directly
+
+```javascript
+import { StandalonePluginSystem, createHook, Facet } from 'mycelia-kernel-plugin';
+
+// Create a hook (same as above)
+const useDatabase = createHook({ /* ... */ });
+
 // Create and use the system
 const system = new StandalonePluginSystem('my-app', {
   config: {
@@ -67,12 +91,71 @@ const db = system.find('database');
 await db.query('SELECT * FROM users');
 ```
 
+### Simple Event System Example
+
+Create an event-driven system with `useBase` and `useListeners`:
+
+```javascript
+import { useBase, useListeners } from 'mycelia-kernel-plugin';
+
+// Create an event system
+const eventSystem = await useBase('event-system')
+  .config('listeners', { registrationPolicy: 'multiple' })
+  .use(useListeners)
+  .build();
+
+// Enable listeners
+eventSystem.listeners.enableListeners();
+
+// Register event handlers
+eventSystem.listeners.on('user:created', (message) => {
+  console.log('User created:', message.body);
+});
+
+eventSystem.listeners.on('user:updated', (message) => {
+  console.log('User updated:', message.body);
+});
+
+// Emit events
+eventSystem.listeners.emit('user:created', {
+  type: 'user:created',
+  body: { id: 1, name: 'John Doe' }
+});
+
+eventSystem.listeners.emit('user:updated', {
+  type: 'user:updated',
+  body: { id: 1, name: 'Jane Doe' }
+});
+
+// Multiple handlers for the same event
+eventSystem.listeners.on('order:placed', (message) => {
+  console.log('Order notification:', message.body);
+});
+
+eventSystem.listeners.on('order:placed', (message) => {
+  console.log('Order logging:', message.body);
+});
+
+// Both handlers will be called
+eventSystem.listeners.emit('order:placed', {
+  type: 'order:placed',
+  body: { orderId: 123, total: 99.99 }
+});
+
+// Cleanup
+await eventSystem.dispose();
+```
+
 ## Installation
 
 ```bash
 npm install mycelia-kernel-plugin
 ```
 
+## What This System Is Not
+
+This system intentionally does not provide dependency injection containers, service locators, or global mutable state. It focuses on explicit lifecycle management and composable plugin architecture rather than implicit dependency resolution or shared global state.
+
 ## Features
 
 ### Hook System
@@ -141,6 +224,8 @@ The `reload()` method:
 - Allows adding more hooks and rebuilding
 - Perfect for development and hot-reload scenarios
 
+**Note:** Persistent external state (e.g., database contents, file system state) is not automatically reverted. The `reload()` method only manages the plugin system's internal state.
+
 ### Facet Contracts
 Validate plugin interfaces at build time:
 
@@ -156,6 +241,11 @@ const databaseContract = createFacetContract({
 // Contract is automatically enforced during build
 ```
 
+If a facet doesn't satisfy its contract, build fails with a clear error:
+```
+Error: FacetContract 'database': facet is missing required methods: close
+```
+
 ## Architecture
 
 ```
@@ -181,6 +271,7 @@ StandalonePluginSystem
 
 - **`createHook()`** - Create a plugin hook
 - **`createFacetContract()`** - Create a facet contract
+- **`useBase()`** - Fluent API builder for StandalonePluginSystem
 
 ### Utilities
 
@@ -193,6 +284,8 @@ Comprehensive documentation is available in the [`docs/`](./docs/) directory:
 
 - **[Getting Started Guide](./docs/getting-started/README.md)** - Quick start with examples
 - **[Hooks and Facets Overview](./docs/core-concepts/HOOKS-AND-FACETS-OVERVIEW.md)** - Core concepts
+- **[Built-in Hooks](./docs/hooks/README.md)** - Documentation for `useListeners`, `useQueue`, and `useSpeak`
+- **[React Bindings](./docs/react/README.md)** - React integration utilities
 - **[Standalone Plugin System](./docs/standalone/STANDALONE-PLUGIN-SYSTEM.md)** - Complete usage guide
 - **[Documentation Index](./docs/README.md)** - Full documentation index
 
@@ -204,6 +297,11 @@ See the `examples/` directory for:
 - Lifecycle management
 - Contract validation
 - Hot reloading
+- useBase fluent API
+- **React Todo App** – A real-world example showing:
+  - Domain logic as a Mycelia facet (`useTodos` hook)
+  - Event-driven state synchronization (`todos:changed` events)
+  - React bindings (`MyceliaProvider`, `useFacet`, `useListener`)
 
 ## CLI Tool
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mycelia-kernel-plugin",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "A sophisticated, dependency-aware plugin system with transaction safety and lifecycle management",
   "license": "MIT",
   "type": "module",
@@ -34,7 +34,8 @@
     "./builder": "./src/builder/index.js",
     "./system": "./src/system/index.js",
     "./contract": "./src/contract/index.js",
-    "./contract/contracts": "./src/contract/contracts/index.js"
+    "./contract/contracts": "./src/contract/contracts/index.js",
+    "./react": "./src/react/index.js"
   },
   "files": [
     "src/",
@@ -50,6 +51,9 @@
     "test:watch": "vitest watch",
     "test:coverage": "vitest run --coverage"
   },
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
   "devDependencies": {
     "@eslint/js": "^9.36.0",
     "eslint": "^9.36.0",

package/src/index.js

@@ -38,6 +38,7 @@ export { useSpeak } from './hooks/speak/use-speak.js';
 export { createLogger, createSubsystemLogger } from './utils/logger.js';
 export { getDebugFlag } from './utils/debug-flag.js';
 export { findFacet } from './utils/find-facet.js';
+export { useBase } from './utils/use-base.js';
 export { 
   parseVersion, 
   isValidSemver, 

package/src/react/README.md

@@ -0,0 +1,174 @@
+# Mycelia Plugin System - React Bindings
+
+React utilities that make the Mycelia Plugin System feel natural inside React applications.
+
+## Installation
+
+```bash
+npm install mycelia-kernel-plugin react
+```
+
+## Quick Start
+
+```tsx
+import { MyceliaProvider, useFacet, useListener } from 'mycelia-kernel-plugin/react';
+import { useBase, useListeners, useDatabase } from 'mycelia-kernel-plugin';
+
+// Create system builder
+const buildSystem = () =>
+  useBase('my-app')
+    .config('database', { host: 'localhost' })
+    .use(useDatabase)
+    .use(useListeners)
+    .build();
+
+// Bootstrap your app
+function App() {
+  return (
+    <MyceliaProvider build={buildSystem}>
+      <MyComponent />
+    </MyceliaProvider>
+  );
+}
+
+// Use in components
+function MyComponent() {
+  const db = useFacet('database');
+  const system = useMycelia();
+  
+  useListener('user:created', (msg) => {
+    console.log('User created:', msg.body);
+  });
+  
+  // Use db, system, etc.
+}
+```
+
+## API Reference
+
+### Core Bindings
+
+#### `MyceliaProvider`
+
+Provides Mycelia system to React tree.
+
+```tsx
+<MyceliaProvider 
+  build={() => useBase('app').use(useDatabase).build()}
+  fallback={<Loading />} // Optional
+>
+  <App />
+</MyceliaProvider>
+```
+
+#### `useMycelia()`
+
+Get the Mycelia system from context.
+
+```tsx
+const system = useMycelia();
+const db = system.find('database');
+```
+
+#### `useFacet(kind)`
+
+Get a facet by kind.
+
+```tsx
+const db = useFacet('database');
+```
+
+### Listener Helpers
+
+#### `useListener(eventName, handler, deps?)`
+
+Register an event listener with automatic cleanup.
+
+```tsx
+useListener('todo:created', (msg) => {
+  console.log('Todo created:', msg.body);
+}, []); // deps array
+```
+
+#### `useEventStream(eventName, options?)`
+
+Subscribe to events and keep them in React state.
+
+```tsx
+// Latest event
+const latestEvent = useEventStream('todo:created');
+
+// Accumulated events
+const allEvents = useEventStream('todo:created', { accumulate: true });
+```
+
+### Queue Helpers
+
+#### `useQueueStatus()`
+
+Get queue status with reactive updates.
+
+```tsx
+const status = useQueueStatus();
+// { size, capacity, utilization, isFull }
+```
+
+#### `useQueueDrain(options?)`
+
+Automatically drain queue on mount.
+
+```tsx
+useQueueDrain({
+  interval: 100,
+  onMessage: (msg, options) => {
+    console.log('Processed:', msg);
+  }
+});
+```
+
+### Builder Helpers
+
+#### `createReactSystemBuilder(name, configure)`
+
+Create a reusable system builder function.
+
+```tsx
+const buildTodoSystem = createReactSystemBuilder('todo-app', (b) =>
+  b
+    .config('database', { host: 'localhost' })
+    .use(useDatabase)
+    .use(useListeners)
+);
+
+<MyceliaProvider build={buildTodoSystem}>
+  <App />
+</MyceliaProvider>
+```
+
+### Facet Hook Generator
+
+#### `createFacetHook(kind)`
+
+Generate a custom hook for a specific facet kind.
+
+```tsx
+// In bindings/todo-hooks.ts
+export const useTodoStore = createFacetHook('todoStore');
+export const useAuth = createFacetHook('auth');
+
+// In component
+function TodoList() {
+  const todoStore = useTodoStore();
+  // Use todoStore...
+}
+```
+
+## Examples
+
+See the main [README.md](../../README.md) and [examples](../../examples/) directory for more examples.
+
+## Requirements
+
+- React >= 16.8.0 (for hooks support)
+- Mycelia Plugin System (included)
+

package/src/react/index.js

@@ -0,0 +1,401 @@
+/**
+ * Mycelia Plugin System - React Bindings
+ * 
+ * React utilities that make the Mycelia Plugin System feel natural
+ * inside React applications.
+ * 
+ * @example
+ * ```tsx
+ * import { MyceliaProvider, useFacet, useListener } from 'mycelia-kernel-plugin/react';
+ * 
+ * const buildSystem = () => useBase('app')
+ *   .use(useDatabase)
+ *   .build();
+ * 
+ * function App() {
+ *   return (
+ *     <MyceliaProvider build={buildSystem}>
+ *       <MyComponent />
+ *     </MyceliaProvider>
+ *   );
+ * }
+ * 
+ * function MyComponent() {
+ *   const db = useFacet('database');
+ *   useListener('user:created', (msg) => console.log(msg));
+ *   // ...
+ * }
+ * ```
+ */
+
+import React, {
+  createContext,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+  useCallback
+} from 'react';
+
+// ============================================================================
+// Core Bindings: Provider + Basic Hooks
+// ============================================================================
+
+const MyceliaContext = createContext(null);
+
+/**
+ * MyceliaProvider - Provides Mycelia system to React tree
+ * 
+ * @param {Object} props
+ * @param {Function} props.build - Async function that returns a built system
+ * @param {React.ReactNode} props.children - Child components
+ * @param {React.ReactNode} [props.fallback] - Optional loading/fallback component
+ * 
+ * @example
+ * ```tsx
+ * <MyceliaProvider build={buildSystem}>
+ *   <App />
+ * </MyceliaProvider>
+ * ```
+ */
+export function MyceliaProvider({ build, children, fallback = null }) {
+  const [system, setSystem] = useState(null);
+  const [error, setError] = useState(null);
+  const buildRef = useRef(build);
+
+  // Update build ref when it changes
+  useEffect(() => {
+    buildRef.current = build;
+  }, [build]);
+
+  useEffect(() => {
+    let isMounted = true;
+    let currentSystem = null;
+
+    (async () => {
+      try {
+        currentSystem = await buildRef.current();
+        if (isMounted) {
+          setSystem(currentSystem);
+          setError(null);
+        }
+      } catch (err) {
+        if (isMounted) {
+          setError(err);
+          setSystem(null);
+        }
+      }
+    })();
+
+    return () => {
+      isMounted = false;
+      if (currentSystem && typeof currentSystem.dispose === 'function') {
+        currentSystem.dispose().catch(() => {
+          // Ignore disposal errors
+        });
+      }
+    };
+  }, []); // Only run once on mount
+
+  if (error) {
+    throw error; // Let error boundaries handle it
+  }
+
+  if (!system) {
+    return fallback;
+  }
+
+  return (
+    <MyceliaContext.Provider value={system}>
+      {children}
+    </MyceliaContext.Provider>
+  );
+}
+
+/**
+ * useMycelia - Get the Mycelia system from context
+ * 
+ * @returns {Object} The Mycelia system instance
+ * @throws {Error} If used outside MyceliaProvider
+ * 
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const system = useMycelia();
+ *   // Use system.find(), system.listeners, etc.
+ * }
+ * ```
+ */
+export function useMycelia() {
+  const system = useContext(MyceliaContext);
+  if (!system) {
+    throw new Error('useMycelia must be used within a MyceliaProvider');
+  }
+  return system;
+}
+
+/**
+ * useFacet - Get a facet by kind from the system
+ * 
+ * @param {string} kind - Facet kind identifier
+ * @returns {Object|null} The facet instance, or null if not found
+ * 
+ * @example
+ * ```tsx
+ * function UserList() {
+ *   const db = useFacet('database');
+ *   // Use db.query(), etc.
+ * }
+ * ```
+ */
+export function useFacet(kind) {
+  const system = useMycelia();
+  const [facet, setFacet] = useState(() => system.find?.(kind) ?? null);
+
+  useEffect(() => {
+    setFacet(system.find?.(kind) ?? null);
+  }, [system, kind]);
+
+  return facet;
+}
+
+// ============================================================================
+// Listener Helpers
+// ============================================================================
+
+/**
+ * useListener - Register an event listener with automatic cleanup
+ * 
+ * @param {string} eventName - Event name/path to listen for
+ * @param {Function} handler - Handler function: (message) => void
+ * @param {Array} [deps=[]] - React dependency array for handler
+ * 
+ * @example
+ * ```tsx
+ * function AuditLog() {
+ *   useListener('user:created', (msg) => {
+ *     console.log('User created:', msg.body);
+ *   });
+ *   // ...
+ * }
+ * ```
+ */
+export function useListener(eventName, handler, deps = []) {
+  const system = useMycelia();
+  const listeners = system.listeners; // useListeners facet
+  const handlerRef = useRef(handler);
+
+  // Update handler ref when it changes
+  useEffect(() => {
+    handlerRef.current = handler;
+  }, [handler, ...deps]);
+
+  useEffect(() => {
+    if (!listeners || !listeners.hasListeners?.()) {
+      return;
+    }
+
+    const wrappedHandler = (msg) => {
+      handlerRef.current(msg);
+    };
+
+    listeners.on(eventName, wrappedHandler);
+
+    return () => {
+      listeners.off?.(eventName, wrappedHandler);
+    };
+  }, [listeners, eventName]);
+}
+
+/**
+ * useEventStream - Subscribe to events and keep them in React state
+ * 
+ * @param {string} eventName - Event name/path to listen for
+ * @param {Object} [options={}] - Options
+ * @param {boolean} [options.accumulate=false] - If true, accumulate events in array
+ * @returns {any|any[]|null} Latest event value, array of events, or null
+ * 
+ * @example
+ * ```tsx
+ * function EventList() {
+ *   const events = useEventStream('todo:created', { accumulate: true });
+ *   return <ul>{events?.map(e => <li key={e.id}>{e.text}</li>)}</ul>;
+ * }
+ * ```
+ */
+export function useEventStream(eventName, options = {}) {
+  const { accumulate = false } = options;
+  const [value, setValue] = useState(accumulate ? [] : null);
+
+  useListener(eventName, (msg) => {
+    if (accumulate) {
+      setValue((prev) => [...prev, msg.body]);
+    } else {
+      setValue(msg.body);
+    }
+  }, [accumulate]);
+
+  return value;
+}
+
+// ============================================================================
+// Queue Helpers
+// ============================================================================
+
+/**
+ * useQueueStatus - Get queue status with reactive updates
+ * 
+ * @returns {Object} Queue status object
+ * @returns {number} size - Current queue size
+ * @returns {number} capacity - Maximum queue capacity
+ * @returns {number} utilization - Utilization ratio (0-1)
+ * @returns {boolean} isFull - Whether queue is full
+ * 
+ * @example
+ * ```tsx
+ * function QueueStatus() {
+ *   const status = useQueueStatus();
+ *   return <div>Queue: {status.size}/{status.capacity}</div>;
+ * }
+ * ```
+ */
+export function useQueueStatus() {
+  const queue = useFacet('queue');
+  const [status, setStatus] = useState(() => {
+    if (queue?.getQueueStatus) {
+      return queue.getQueueStatus();
+    }
+    return { size: 0, maxSize: 0, utilization: 0, isFull: false };
+  });
+
+  // Poll for status updates (could be improved with event-based updates)
+  useEffect(() => {
+    if (!queue || !queue.getQueueStatus) return;
+
+    const interval = setInterval(() => {
+      const newStatus = queue.getQueueStatus();
+      setStatus(newStatus);
+    }, 100); // Poll every 100ms
+
+    return () => clearInterval(interval);
+  }, [queue]);
+
+  return {
+    size: status.size || 0,
+    capacity: status.maxSize || 0,
+    utilization: status.utilization || 0,
+    isFull: status.isFull || false
+  };
+}
+
+/**
+ * useQueueDrain - Automatically drain queue on mount
+ * 
+ * @param {Object} [options={}] - Options
+ * @param {number} [options.interval=100] - Polling interval in ms
+ * @param {Function} [options.onMessage] - Callback for each message: (msg, options) => void
+ * 
+ * @example
+ * ```tsx
+ * function QueueProcessor() {
+ *   useQueueDrain({
+ *     interval: 50,
+ *     onMessage: (msg) => console.log('Processed:', msg)
+ *   });
+ *   return null;
+ * }
+ * ```
+ */
+export function useQueueDrain(options = {}) {
+  const { interval = 100, onMessage } = options;
+  const queue = useFacet('queue');
+  const onMessageRef = useRef(onMessage);
+
+  useEffect(() => {
+    onMessageRef.current = onMessage;
+  }, [onMessage]);
+
+  useEffect(() => {
+    if (!queue || !queue.hasMessagesToProcess) return;
+
+    const processInterval = setInterval(() => {
+      if (queue.hasMessagesToProcess()) {
+        const next = queue.selectNextMessage();
+        if (next && onMessageRef.current) {
+          onMessageRef.current(next.msg, next.options);
+        }
+      }
+    }, interval);
+
+    return () => clearInterval(processInterval);
+  }, [queue, interval]);
+}
+
+// ============================================================================
+// Builder Helpers
+// ============================================================================
+
+/**
+ * createReactSystemBuilder - Create a reusable system builder function
+ * 
+ * @param {string} name - System name
+ * @param {Function} configure - Configuration function: (builder) => builder
+ * @returns {Function} Build function: () => Promise<System>
+ * 
+ * @example
+ * ```ts
+ * import { useBase } from 'mycelia-kernel-plugin';
+ * 
+ * const buildTodoSystem = createReactSystemBuilder('todo-app', (b) =>
+ *   b
+ *     .config('database', { host: 'localhost' })
+ *     .use(useDatabase)
+ *     .use(useListeners)
+ * );
+ * 
+ * // Then use in Provider
+ * <MyceliaProvider build={buildTodoSystem}>
+ *   <App />
+ * </MyceliaProvider>
+ * ```
+ */
+export function createReactSystemBuilder(name, configure) {
+  return async function build() {
+    // Import useBase - users should have it available
+    // This avoids bundling issues by letting users import useBase themselves
+    const { useBase } = await import('../utils/use-base.js');
+    let builder = useBase(name);
+    builder = configure(builder);
+    return builder.build();
+  };
+}
+
+// ============================================================================
+// Facet Hook Generator
+// ============================================================================
+
+/**
+ * createFacetHook - Generate a custom hook for a specific facet kind
+ * 
+ * @param {string} kind - Facet kind identifier
+ * @returns {Function} Custom hook: () => Facet | null
+ * 
+ * @example
+ * ```ts
+ * // In bindings/todo-hooks.ts
+ * export const useTodoStore = createFacetHook('todoStore');
+ * export const useAuth = createFacetHook('auth');
+ * 
+ * // In component
+ * function TodoList() {
+ *   const todoStore = useTodoStore();
+ *   // Use todoStore...
+ * }
+ * ```
+ */
+export function createFacetHook(kind) {
+  return function useNamedFacet() {
+    return useFacet(kind);
+  };
+}
+

package/src/utils/use-base.js

@@ -0,0 +1,262 @@
+import { StandalonePluginSystem } from '../system/standalone-plugin-system.js';
+import { deepMerge } from '../builder/context-resolver.js';
+
+/**
+ * useBase - Fluent API Builder for StandalonePluginSystem
+ * 
+ * Provides a convenient, chainable API for creating and configuring
+ * StandalonePluginSystem instances.
+ * 
+ * @param {string} name - Unique name for the plugin system
+ * @param {Object} [options={}] - Initial configuration options
+ * @param {Object} [options.config={}] - Initial configuration object keyed by facet kind
+ * @param {boolean} [options.debug=false] - Enable debug logging
+ * @param {Array} [options.defaultHooks=[]] - Optional default hooks to install
+ * @returns {UseBaseBuilder} Builder instance with fluent API
+ * 
+ * @example
+ * ```javascript
+ * import { useBase } from 'mycelia-kernel-plugin';
+ * import { useDatabase, useCache } from './hooks';
+ * 
+ * const system = await useBase('my-app')
+ *   .config('database', { host: 'localhost' })
+ *   .config('cache', { ttl: 3600 })
+ *   .use(useDatabase)
+ *   .use(useCache)
+ *   .onInit(async (api, ctx) => {
+ *     console.log('System initialized');
+ *   })
+ *   .build();
+ * ```
+ */
+export function useBase(name, options = {}) {
+  if (!name || typeof name !== 'string') {
+    throw new Error('useBase: name must be a non-empty string');
+  }
+
+  // Create the system instance
+  const system = new StandalonePluginSystem(name, options);
+
+  // Create builder with fluent API
+  return new UseBaseBuilder(system);
+}
+
+/**
+ * UseBaseBuilder - Fluent API builder for StandalonePluginSystem
+ * 
+ * Provides chainable methods for configuring and building the system.
+ */
+class UseBaseBuilder {
+  #system;
+  #pendingConfig = {};
+
+  constructor(system) {
+    this.#system = system;
+  }
+
+  /**
+   * Register a hook
+   * 
+   * @param {Function} hook - Hook function to register
+   * @returns {UseBaseBuilder} This builder for chaining
+   * 
+   * @example
+   * ```javascript
+   * builder.use(useDatabase).use(useCache);
+   * ```
+   */
+  use(hook) {
+    if (typeof hook !== 'function') {
+      throw new Error('useBase.use: hook must be a function');
+    }
+    this.#system.use(hook);
+    return this;
+  }
+
+  /**
+   * Conditionally register a hook
+   * 
+   * @param {boolean} condition - Whether to register the hook
+   * @param {Function} hook - Hook function to register if condition is true
+   * @returns {UseBaseBuilder} This builder for chaining
+   * 
+   * @example
+   * ```javascript
+   * builder.useIf(process.env.ENABLE_CACHE === 'true', useCache);
+   * ```
+   */
+  useIf(condition, hook) {
+    if (condition) {
+      return this.use(hook);
+    }
+    return this;
+  }
+
+  /**
+   * Add or update configuration for a specific facet kind
+   * 
+   * Configurations are merged when possible (deep merge for objects).
+   * 
+   * @param {string} kind - Facet kind identifier (e.g., 'database', 'cache')
+   * @param {*} config - Configuration value for this facet kind
+   * @returns {UseBaseBuilder} This builder for chaining
+   * 
+   * @example
+   * ```javascript
+   * builder
+   *   .config('database', { host: 'localhost', port: 5432 })
+   *   .config('cache', { ttl: 3600 });
+   * ```
+   * 
+   * @example
+   * ```javascript
+   * // Merge configurations
+   * builder
+   *   .config('database', { host: 'localhost' })
+   *   .config('database', { port: 5432 }); // Merges with existing
+   * ```
+   */
+  config(kind, config) {
+    if (!kind || typeof kind !== 'string') {
+      throw new Error('useBase.config: kind must be a non-empty string');
+    }
+
+    // Initialize config object if needed
+    if (!this.#system.ctx.config || typeof this.#system.ctx.config !== 'object') {
+      this.#system.ctx.config = {};
+    }
+
+    // Get existing config for this kind
+    const existingConfig = this.#system.ctx.config[kind];
+    const pendingConfig = this.#pendingConfig[kind];
+
+    // Determine the base config (existing or pending)
+    const baseConfig = pendingConfig !== undefined ? pendingConfig : existingConfig;
+
+    // Merge if both are objects
+    if (
+      baseConfig &&
+      typeof baseConfig === 'object' &&
+      !Array.isArray(baseConfig) &&
+      config &&
+      typeof config === 'object' &&
+      !Array.isArray(config)
+    ) {
+      // Deep merge
+      this.#pendingConfig[kind] = deepMerge(baseConfig, config);
+    } else {
+      // Override
+      this.#pendingConfig[kind] = config;
+    }
+
+    return this;
+  }
+
+  /**
+   * Add an initialization callback
+   * 
+   * @param {Function} callback - Callback function: (api, ctx) => Promise<void> | void
+   * @returns {UseBaseBuilder} This builder for chaining
+   * 
+   * @example
+   * ```javascript
+   * builder.onInit(async (api, ctx) => {
+   *   console.log('System initialized:', api.name);
+   * });
+   * ```
+   */
+  onInit(callback) {
+    if (typeof callback !== 'function') {
+      throw new Error('useBase.onInit: callback must be a function');
+    }
+    this.#system.onInit(callback);
+    return this;
+  }
+
+  /**
+   * Add a disposal callback
+   * 
+   * @param {Function} callback - Callback function: () => Promise<void> | void
+   * @returns {UseBaseBuilder} This builder for chaining
+   * 
+   * @example
+   * ```javascript
+   * builder.onDispose(async () => {
+   *   console.log('System disposed');
+   * });
+   * ```
+   */
+  onDispose(callback) {
+    if (typeof callback !== 'function') {
+      throw new Error('useBase.onDispose: callback must be a function');
+    }
+    this.#system.onDispose(callback);
+    return this;
+  }
+
+  /**
+   * Build the system
+   * 
+   * This method is required and must be called to build the system.
+   * It applies any pending configurations and builds the system.
+   * 
+   * @param {Object} [ctx={}] - Additional context to pass to build
+   * @returns {Promise<StandalonePluginSystem>} The built system instance
+   * 
+   * @example
+   * ```javascript
+   * const system = await useBase('my-app')
+   *   .use(useDatabase)
+   *   .build();
+   * ```
+   */
+  async build(ctx = {}) {
+    // Apply pending configurations
+    if (Object.keys(this.#pendingConfig).length > 0) {
+      // Merge pending config into system config
+      if (!this.#system.ctx.config || typeof this.#system.ctx.config !== 'object') {
+        this.#system.ctx.config = {};
+      }
+
+      // Deep merge pending configs
+      for (const [kind, config] of Object.entries(this.#pendingConfig)) {
+        const existing = this.#system.ctx.config[kind];
+        if (
+          existing &&
+          typeof existing === 'object' &&
+          !Array.isArray(existing) &&
+          config &&
+          typeof config === 'object' &&
+          !Array.isArray(config)
+        ) {
+          this.#system.ctx.config[kind] = deepMerge(existing, config);
+        } else {
+          this.#system.ctx.config[kind] = config;
+        }
+      }
+
+      // Clear pending configs
+      this.#pendingConfig = {};
+    }
+
+    // Merge any additional context
+    if (ctx && typeof ctx === 'object' && !Array.isArray(ctx)) {
+      if (ctx.config && typeof ctx.config === 'object' && !Array.isArray(ctx.config)) {
+        if (!this.#system.ctx.config) {
+          this.#system.ctx.config = {};
+        }
+        this.#system.ctx.config = deepMerge(this.#system.ctx.config, ctx.config);
+      }
+      // Merge other ctx properties (shallow)
+      Object.assign(this.#system.ctx, ctx);
+    }
+
+    // Build the system
+    await this.#system.build(ctx);
+
+    // Return the system instance
+    return this.#system;
+  }
+}
+