mycelia-kernel-plugin 1.4.0 → 1.5.0

package/README.md

@@ -320,6 +320,7 @@ Comprehensive documentation is available in the [`docs/`](./docs/) directory:
 - **[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`) ⭐
+- **[Solid.js Bindings](./src/solid/README.md)** - Solid.js 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
 
@@ -347,14 +348,13 @@ See the `examples/` directory for:
   - 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
+  - **Framework-agnostic plugins** - Uses the same shared plugin code as React, Vue, and other examples
   - Event-driven state synchronization (`todos:changed` events)
-  - Solid.js bindings (`MyceliaProvider`, `useFacet`, `useListener`)
-  - Signal-based reactivity with automatic updates
+  - Svelte bindings (`setMyceliaSystem`, `useFacet`, `useListener`)
+  - Svelte stores for reactive state management
 
 - **[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
+  - **Framework-agnostic plugins** - Uses the same shared plugin code as React, Vue, Svelte, and other examples
   - Event-driven state synchronization (`todos:changed` events)
   - Angular bindings (`MyceliaService`, `useFacet`, `useListener`)
   - RxJS observables for reactive state management
@@ -365,6 +365,12 @@ See the `examples/` directory for:
   - Qwik bindings (`MyceliaProvider`, `useFacet`, `useListener`)
   - Qwik signals for reactive state management
 
+- **[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, Svelte, Angular, and Qwik examples
+  - Event-driven state synchronization (`todos:changed` events)
+  - Solid.js bindings (`MyceliaProvider`, `useFacet`, `useListener`)
+  - Signal-based reactivity with automatic updates
+
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mycelia-kernel-plugin",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "A sophisticated, framework-agnostic plugin system with transaction safety, lifecycle management, and official bindings for React, Vue 3, Svelte, Angular, Qwik, and Solid.js",
   "license": "MIT",
   "type": "module",
@@ -57,13 +57,13 @@
     "test:coverage": "vitest run --coverage"
   },
   "peerDependencies": {
-    "react": ">=16.8.0",
-    "vue": ">=3.0.0",
-    "svelte": ">=3.0.0",
     "@angular/core": ">=15.0.0",
     "@builder.io/qwik": ">=1.0.0",
+    "react": ">=16.8.0",
+    "rxjs": ">=7.0.0",
     "solid-js": ">=1.0.0",
-    "rxjs": ">=7.0.0"
+    "svelte": ">=3.0.0",
+    "vue": ">=3.0.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.36.0",
@@ -73,5 +73,8 @@
   },
   "engines": {
     "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "mitt": "^3.0.1"
   }
 }

package/src/angular/builders.js

@@ -35,3 +35,5 @@ export function createAngularSystemBuilder(name, configure) {
 }
 
 
+
+

package/src/angular/helpers.js

@@ -100,3 +100,5 @@ export function useEventStream(myceliaService, eventName, options = {}) {
 }
 
 
+
+

package/src/angular/services.js

@@ -30,3 +30,5 @@ export function createFacetService(kind) {
 }
 
 
+
+

package/src/contract/contracts/listeners.contract.js

@@ -19,6 +19,7 @@ import { createFacetContract } from '../facet-contract.js';
  * Required methods:
  * - on: Register a listener for a specific message path
  * - off: Unregister a listener for a specific message path
+ * - emit: Emit an event to listeners for a specific path
  * - hasListeners: Check if listeners are enabled
  * - enableListeners: Enable listeners and initialize ListenerManager
  * - disableListeners: Disable listeners (but keep manager instance)
@@ -37,6 +38,7 @@ export const listenersContract = createFacetContract({
   requiredMethods: [
     'on',
     'off',
+    'emit',
     'hasListeners',
     'enableListeners',
     'disableListeners'

package/src/hooks/listeners/use-simple-listeners.js

@@ -0,0 +1,172 @@
+/**
+ * useSimpleListeners Hook
+ * 
+ * Provides simple listener management functionality to subsystems using mitt.
+ * A lightweight alternative to useListeners that wraps the mitt event emitter.
+ * 
+ * @param {Object} ctx - Context object containing config.listeners for listener configuration
+ * @param {Object} api - Subsystem API being built
+ * @param {BaseSubsystem} subsystem - Subsystem instance
+ * @returns {Facet} Facet object with listener methods
+ */
+import mitt from 'mitt';
+import { Facet } from '../../core/facet.js';
+import { createHook } from '../../core/create-hook.js';
+import { getDebugFlag } from '../../utils/debug-flag.js';
+import { createLogger } from '../../utils/logger.js';
+
+export const useSimpleListeners = createHook({
+  kind: 'listeners',
+  version: '1.0.0',
+  overwrite: false,
+  required: [],
+  attach: true,
+  source: import.meta.url,
+  contract: 'listeners',
+  // eslint-disable-next-line no-unused-vars
+  fn: (ctx, api, _subsystem) => {
+    const { name } = api;
+    const config = ctx.config?.listeners || {};
+    const debug = getDebugFlag(config, ctx);
+    
+    // Listeners are optional - can be enabled/disabled
+    let emitter = null;
+    let listenersEnabled = false;
+    
+    return new Facet('listeners', { attach: true, source: import.meta.url, contract: 'listeners' })
+      .add({
+      
+      /**
+       * Check if listeners are enabled
+       * @returns {boolean} True if listeners are enabled
+       */
+      hasListeners() {
+        return listenersEnabled && emitter !== null;
+      },
+      
+      /**
+       * Enable listeners
+       * @param {Object} [listenerOptions={}] - Options (currently unused, for API compatibility)
+       */
+      enableListeners(listenerOptions = {}) {
+        if (emitter === null) {
+          emitter = mitt();
+        }
+        listenersEnabled = true;
+      },
+      
+      /**
+       * Disable listeners
+       */
+      disableListeners() {
+        listenersEnabled = false;
+      },
+      
+      /**
+       * Register a listener for a specific path
+       * @param {string} path - Message path to listen for
+       * @param {Function} handler - Handler function
+       * @param {Object} [options={}] - Registration options (for API compatibility)
+       * @returns {boolean} Success status
+       */
+      on(path, handler, options = {}) {
+        // Check if listeners are enabled
+        if (!listenersEnabled || emitter === null) {
+          const runtimeDebug = options.debug !== undefined ? options.debug : debug;
+          if (runtimeDebug) {
+            const runtimeLogger = createLogger(runtimeDebug, `useSimpleListeners ${name}`);
+            runtimeLogger.warn('Cannot register listener - listeners not enabled');
+          }
+          return false;
+        }
+        
+        // Validate handler is a function
+        if (typeof handler !== 'function') {
+          if (debug) {
+            const runtimeLogger = createLogger(debug, `useSimpleListeners ${name}`);
+            runtimeLogger.warn('Handler must be a function');
+          }
+          return false;
+        }
+        
+        // Register with mitt
+        emitter.on(path, handler);
+        return true;
+      },
+      
+      /**
+       * Unregister a listener for a specific path
+       * @param {string} path - Message path
+       * @param {Function} handler - Handler function to remove
+       * @param {Object} [options={}] - Unregistration options (for API compatibility)
+       * @returns {boolean} Success status
+       */
+      off(path, handler, options = {}) {
+        // Check if listeners are enabled
+        if (!listenersEnabled || emitter === null) {
+          const runtimeDebug = options.debug !== undefined ? options.debug : debug;
+          if (runtimeDebug) {
+            const runtimeLogger = createLogger(runtimeDebug, `useSimpleListeners ${name}`);
+            runtimeLogger.warn('Cannot unregister listener - listeners not enabled');
+          }
+          return false;
+        }
+        
+        // Validate handler is a function
+        if (typeof handler !== 'function') {
+          if (debug) {
+            const runtimeLogger = createLogger(debug, `useSimpleListeners ${name}`);
+            runtimeLogger.warn('Handler must be a function');
+          }
+          return false;
+        }
+        
+        // Unregister from mitt
+        emitter.off(path, handler);
+        return true;
+      },
+      
+      /**
+       * Emit an event to listeners for a specific path
+       * @param {string} path - Message path to emit to
+       * @param {any} message - Message/data to send to listeners
+       * @returns {number} Number of listeners notified, or 0 if listeners not enabled
+       * 
+       * @example
+       * // Emit event to listeners
+       * const notified = subsystem.listeners.emit('layers/create', message);
+       */
+      emit(path, message) {
+        // Check if listeners are enabled
+        if (!listenersEnabled || emitter === null) {
+          if (debug) {
+            const runtimeLogger = createLogger(debug, `useSimpleListeners ${name}`);
+            runtimeLogger.warn('Cannot emit event - listeners not enabled');
+          }
+          return 0;
+        }
+        
+        // Get listeners count before emitting (mitt doesn't return count)
+        const listeners = emitter.all.get(path);
+        const count = listeners ? listeners.length : 0;
+        
+        // Emit to mitt
+        emitter.emit(path, message);
+        
+        return count;
+      },
+      
+      /**
+       * Expose emitter property for direct access
+       * Returns null if listeners are not enabled
+       */
+      get listeners() {
+        return emitter;
+      },
+      
+      // Expose emitter for internal use (compatible with listeners contract)
+      _listenerManager: () => emitter
+      });
+  }
+});
+

package/src/index.js

@@ -31,6 +31,7 @@ export * from './contract/contracts/index.js';
 
 // Hook exports
 export { useListeners } from './hooks/listeners/use-listeners.js';
+export { useSimpleListeners } from './hooks/listeners/use-simple-listeners.js';
 export { useQueue } from './hooks/queue/use-queue.js';
 export { useSpeak } from './hooks/speak/use-speak.js';
 

package/src/manager/facet-manager.js

@@ -510,12 +510,20 @@ export class FacetManager {
   }
   
   clear() {
-    // Dispose all facets before clearing
+    // Dispose all facets before clearing (synchronous best-effort)
+    // Note: dispose() is async, but clear() is synchronous
+    // For async disposal, use disposeAll() instead
     for (const [, facets] of this.#facets.entries()) {
       if (Array.isArray(facets)) {
         for (const facet of facets) {
           try {
-            facet?.dispose?.(this.#subsystem);
+            const disposeResult = facet?.dispose?.(this.#subsystem);
+            // If dispose returns a promise, catch any errors to prevent unhandled rejections
+            if (disposeResult && typeof disposeResult.catch === 'function') {
+              disposeResult.catch(() => {
+                // Best-effort disposal - errors are expected and handled
+              });
+            }
           } catch {
             // Best-effort disposal
           }
@@ -523,7 +531,13 @@ export class FacetManager {
       } else {
         // Legacy: single facet
         try {
-          facets?.dispose?.(this.#subsystem);
+          const disposeResult = facets?.dispose?.(this.#subsystem);
+          // If dispose returns a promise, catch any errors to prevent unhandled rejections
+          if (disposeResult && typeof disposeResult.catch === 'function') {
+            disposeResult.catch(() => {
+              // Best-effort disposal - errors are expected and handled
+            });
+          }
         } catch {
           // Best-effort disposal
         }

package/src/qwik/builders.js

@@ -37,3 +37,5 @@ export function createQwikSystemBuilder(name, configure) {
 }
 
 
+
+

package/src/qwik/queues.js

@@ -85,3 +85,5 @@ export function useQueueDrain(options = {}) {
 }
 
 
+
+

package/src/qwik/signals.js

@@ -30,3 +30,5 @@ export function createFacetSignal(kind) {
 }
 
 
+
+

package/src/react/README.md

@@ -175,3 +175,5 @@ See the main [README.md](../../README.md) and [examples](../../examples/) direct
 
 
 
+
+

package/src/solid/README.md

@@ -67,3 +67,5 @@ function MyComponent() {
 - **Automatic Cleanup** - Listeners and effects cleaned up automatically
 - **Solid Signals** - Reactive state with Solid.js signals
 
+
+

package/src/utils/use-base.js

@@ -247,8 +247,8 @@ class UseBaseBuilder {
     // Get existing config for this kind (from pending or system if created)
     let existingConfig;
     if (this.#system) {
-      if (!this.#system.ctx.config || typeof this.#system.ctx.config !== 'object') {
-        this.#system.ctx.config = {};
+    if (!this.#system.ctx.config || typeof this.#system.ctx.config !== 'object') {
+      this.#system.ctx.config = {};
       }
       existingConfig = this.#system.ctx.config[kind];
     } else {