mycelia-kernel-plugin 1.2.0 → 1.4.0

package/README.md

@@ -1,11 +1,12 @@
 # Mycelia Plugin System
 
-A sophisticated, dependency-aware plugin system with transaction safety and lifecycle management.
+A sophisticated, **framework-agnostic** plugin system with transaction safety, lifecycle management, and official bindings for React, Vue 3, Svelte, Angular, Qwik, and Solid.js.
 
 ## Overview
 
-Mycelia Plugin System is a standalone plugin architecture extracted from [Mycelia Kernel](https://github.com/lesfleursdelanuitdev/mycelia-kernel). It provides:
+Mycelia Plugin System is a **framework-agnostic**, standalone plugin architecture extracted from [Mycelia Kernel](https://github.com/lesfleursdelanuitdev/mycelia-kernel). It provides:
 
+- **Framework-agnostic** - Write domain logic once, use it with React, Vue, or any framework. Plugins are completely independent of UI frameworks
 - **Hook-based composition** - Extend systems without modification
 - **Dependency resolution** - Automatic topological sorting
 - **Transaction safety** - Atomic installation with rollback
@@ -14,9 +15,24 @@ Mycelia Plugin System is a standalone plugin architecture extracted from [Myceli
 - **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`
+- **Framework bindings** - Official bindings for [React](#react-bindings), [Vue 3](#vue-bindings), [Svelte](#svelte-bindings), [Angular](#angular-bindings), [Qwik](#qwik-bindings), and [Solid.js](#solidjs-bindings)
 
 **Facets** are the concrete runtime capabilities produced by hooks and attached to the system.
 
+### Framework Integration
+
+The system is designed to be framework-agnostic. Your domain logic lives in Mycelia plugins, which can be used with any framework:
+
+- **React** - Use `MyceliaProvider` and React hooks (`useFacet`, `useListener`)
+- **Vue 3** - Use `MyceliaPlugin` and Vue composables (`useFacet`, `useListener`)
+- **Svelte** - Use `setMyceliaSystem` and Svelte stores (`useFacet`, `useListener`)
+- **Angular** - Use `MyceliaService` and RxJS observables (`useFacet`, `useListener`)
+- **Qwik** - Use `MyceliaProvider` and Qwik signals (`useFacet`, `useListener`)
+- **Solid.js** - Use `MyceliaProvider` and Solid.js signals (`useFacet`, `useListener`)
+- **Vanilla JS/Node.js** - Use the system directly without any framework bindings
+
+See the [React Todo App](./examples/react-todo/README.md), [Vue Todo App](./examples/vue-todo/README.md), [Svelte Todo App](./examples/svelte-todo/README.md), and [Solid.js Todo App](./examples/solid-todo/README.md) examples - they all use the **exact same plugin code**, demonstrating true framework independence.
+
 ## Quick Start
 
 ### Using useBase (Recommended)
@@ -62,6 +78,15 @@ const system = await useBase('my-app')
   .use(useDatabase)
   .build();
 
+// Or configure multiple facets and hooks at once
+const system = await useBase('my-app')
+  .configMultiple({
+    database: { host: 'localhost', port: 5432 },
+    cache: { ttl: 3600 }
+  })
+  .useMultiple([useDatabase, useCache])
+  .build();
+
 // Use the plugin
 const db = system.find('database');
 await db.query('SELECT * FROM users');
@@ -271,7 +296,7 @@ StandalonePluginSystem
 
 - **`createHook()`** - Create a plugin hook
 - **`createFacetContract()`** - Create a facet contract
-- **`useBase()`** - Fluent API builder for StandalonePluginSystem
+- **`useBase()`** - Fluent API builder for StandalonePluginSystem (see [useBase Documentation](./docs/utils/USE-BASE.md))
 
 ### Utilities
 
@@ -282,10 +307,19 @@ StandalonePluginSystem
 
 Comprehensive documentation is available in the [`docs/`](./docs/) directory:
 
+### Quick Links
+- **[useBase Guide](./docs/utils/USE-BASE.md)** - Complete guide to the fluent API builder with all methods
+- **[Instrumentation](./docs/instrumentation.md)** - Debugging and performance instrumentation
+
+### Full Documentation
 - **[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
+- **[React Bindings](./docs/react/README.md)** - React integration utilities (`MyceliaProvider`, `useFacet`, `useListener`)
+- **[Vue Bindings](./docs/vue/README.md)** - Vue 3 integration utilities (`MyceliaPlugin`, `useFacet`, `useListener`) ⭐
+- **[Svelte Bindings](./docs/svelte/README.md)** - Svelte integration utilities (`setMyceliaSystem`, `useFacet`, `useListener`) ⭐
+- **[Angular Bindings](./docs/angular/README.md)** - Angular integration utilities (`MyceliaService`, `useFacet`, `useListener`) ⭐
+- **[Qwik Bindings](./docs/qwik/README.md)** - Qwik integration utilities (`MyceliaProvider`, `useFacet`, `useListener`) ⭐
 - **[Standalone Plugin System](./docs/standalone/STANDALONE-PLUGIN-SYSTEM.md)** - Complete usage guide
 - **[Documentation Index](./docs/README.md)** - Full documentation index
 
@@ -298,11 +332,41 @@ See the `examples/` directory for:
 - Contract validation
 - Hot reloading
 - useBase fluent API
-- **React Todo App** – A real-world example showing:
+
+### Framework Integration Examples
+
+- **[React Todo App](./examples/react-todo/README.md)** – 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`)
 
+- **[Vue Todo App](./examples/vue-todo/README.md)** ⭐ – A complete Vue 3 example demonstrating:
+  - **Framework-agnostic plugins** - Uses the same shared plugin code as the React example
+  - Event-driven state synchronization (`todos:changed` events)
+  - Vue 3 bindings (`MyceliaPlugin`, `useFacet`, `useListener`)
+  - Composition API integration with reactive state management
+
+- **[Svelte Todo App](./examples/svelte-todo/README.md)** ⭐ – A complete Svelte example demonstrating:
+- **[Solid.js Todo App](./examples/solid-todo/README.md)** ⭐ – A complete Solid.js example demonstrating:
+  - **Framework-agnostic plugins** - Uses the same shared plugin code as React, Vue, and Svelte examples
+  - Event-driven state synchronization (`todos:changed` events)
+  - Solid.js bindings (`MyceliaProvider`, `useFacet`, `useListener`)
+  - Signal-based reactivity with automatic updates
+
+- **[Angular Todo App](./examples/angular-todo/README.md)** ⭐ – A complete Angular example demonstrating:
+  - **Framework-agnostic plugins** - Uses the same shared plugin code as React, Vue, and Svelte examples
+  - Event-driven state synchronization (`todos:changed` events)
+  - Angular bindings (`MyceliaService`, `useFacet`, `useListener`)
+  - RxJS observables for reactive state management
+
+- **[Qwik Todo App](./examples/qwik-todo/README.md)** ⭐ – A complete Qwik example demonstrating:
+  - **Framework-agnostic plugins** - Uses the same shared plugin code as all other framework examples
+  - Event-driven state synchronization (`todos:changed` events)
+  - Qwik bindings (`MyceliaProvider`, `useFacet`, `useListener`)
+  - Qwik signals for reactive state management
+
+All six examples use the **exact same Mycelia plugin code** from `examples/todo-shared/`, proving that plugins are truly framework-independent. Write your domain logic once, use it everywhere!
+
 ## CLI Tool
 
 The package includes a CLI tool for scaffolding hooks, contracts, and projects:
@@ -314,14 +378,33 @@ npx mycelia-kernel-plugin create hook database
 # Create a new contract
 npx mycelia-kernel-plugin create contract database
 
-# Initialize a new project
+# Initialize a new project (vanilla JS)
 npx mycelia-kernel-plugin init my-app
+
+# Initialize a React project with Mycelia bindings
+npx mycelia-kernel-plugin init react my-react-app
+
+# Initialize a Vue 3 project with Mycelia bindings
+npx mycelia-kernel-plugin init vue my-vue-app
+
+# Initialize a Svelte project with Mycelia bindings
+npx mycelia-kernel-plugin init svelte my-svelte-app
+
+# Initialize an Angular project with Mycelia bindings
+npx mycelia-kernel-plugin init angular my-angular-app
+
+# Initialize a Qwik project with Mycelia bindings
+npx mycelia-kernel-plugin init qwik my-qwik-app
+
+# Initialize a Solid.js project with Mycelia bindings
+npx mycelia-kernel-plugin init solid my-solid-app
 ```
 
 Or install globally:
 ```bash
 npm install -g mycelia-kernel-plugin
 mycelia-kernel-plugin create hook database
+mycelia-kernel-plugin init react my-react-app
 ```
 
 ## Testing