@quazardous/quarkernel-svelte 2.1.0

package/README.md

@@ -0,0 +1,128 @@
+# @quazardous/quarkernel-svelte
+
+Svelte 5 adapter for QuarKernel - context API and composables for seamless event kernel integration.
+
+## Installation
+
+```bash
+npm install @quazardous/quarkernel @quazardous/quarkernel-svelte
+```
+
+## Features
+
+- **Context API**: `setKernel()`/`getKernel()` for dependency injection
+- **Auto-cleanup**: `onEvent()` composable with automatic unsubscribe on destroy
+- **Type-safe**: Full TypeScript support
+- **Svelte 5**: Designed for Svelte 5+ with modern context system
+- **Zero runtime deps**: Only peer dependencies on Svelte and QuarKernel
+
+## Usage
+
+### Basic Setup
+
+```svelte
+<!-- App.svelte (root component) -->
+<script>
+  import { createKernel } from '@quazardous/quarkernel';
+  import { setKernel } from '@quazardous/quarkernel-svelte';
+
+  const qk = createKernel();
+  setKernel(kernel);
+</script>
+
+<ChildComponent />
+```
+
+### Using in Child Components
+
+```svelte
+<!-- ChildComponent.svelte -->
+<script>
+  import { getKernel, onEvent } from '@quazardous/quarkernel-svelte';
+
+  // Get kernel from context
+  const qk = getKernel();
+
+  // Register listener with auto-cleanup
+  onEvent('user:login', async (event) => {
+    console.log('User logged in:', event.data);
+  });
+
+  // Manual emit
+  function handleClick() {
+    qk.emit('button:clicked', { timestamp: Date.now() });
+  }
+</script>
+
+<button on:click={handleClick}>Click me</button>
+```
+
+### Wildcard Patterns
+
+```svelte
+<script>
+  import { onEvent } from '@quazardous/quarkernel-svelte';
+
+  // Listen to all user events
+  onEvent('user:*', (event) => {
+    console.log('User event:', event);
+  });
+</script>
+```
+
+### Manual Cleanup
+
+```svelte
+<script>
+  import { onEvent } from '@quazardous/quarkernel-svelte';
+
+  // onEvent returns unsubscribe function
+  const unsubscribe = onEvent('temp:event', (event) => {
+    console.log('Temporary listener');
+  });
+
+  function cleanup() {
+    unsubscribe(); // Remove listener before component destroys
+  }
+</script>
+```
+
+## API
+
+### `setKernel(kernel)`
+
+Store kernel instance in Svelte context. Must be called during component initialization.
+
+**Parameters:**
+- `kernel`: Kernel instance to provide to child components
+
+**Throws:**
+- Error if kernel is null/undefined
+
+### `getKernel()`
+
+Retrieve kernel instance from Svelte context.
+
+**Returns:**
+- Kernel instance
+
+**Throws:**
+- `KernelContextError` if called outside context or before `setKernel()`
+
+### `onEvent(pattern, handler)`
+
+Register event listener with automatic cleanup on component destroy.
+
+**Parameters:**
+- `pattern`: Event name or wildcard pattern (e.g., `'user:*'`)
+- `handler`: Event handler function `(event, ctx) => void | Promise<void>`
+
+**Returns:**
+- Unsubscribe function for manual cleanup
+
+**Throws:**
+- `KernelContextError` if kernel not in context
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,67 @@
+'use strict';
+
+var svelte = require('svelte');
+var store = require('svelte/store');
+
+// src/context.ts
+var KERNEL_CONTEXT_KEY = /* @__PURE__ */ Symbol("quarkernel");
+var KernelContextError = class extends Error {
+  constructor() {
+    super(
+      "getKernel() must be called within a component where setKernel() was used. Ensure you call setKernel(kernel) in a parent component."
+    );
+    this.name = "KernelContextError";
+  }
+};
+function setKernel(kernel) {
+  if (!kernel) {
+    throw new Error("[QuarKernel Svelte] setKernel() requires a kernel instance");
+  }
+  svelte.setContext(KERNEL_CONTEXT_KEY, kernel);
+}
+function getKernel() {
+  const kernel = svelte.getContext(KERNEL_CONTEXT_KEY);
+  if (!kernel) {
+    throw new KernelContextError();
+  }
+  return kernel;
+}
+function onEvent(pattern, handler) {
+  const kernel = getKernel();
+  const unsubscribe = kernel.on(pattern, handler);
+  svelte.onDestroy(() => {
+    unsubscribe();
+  });
+  return unsubscribe;
+}
+function eventStore(pattern) {
+  return store.readable(void 0, (set) => {
+    const kernel = getKernel();
+    const unsubscribe = kernel.on(pattern, async (event, _context) => {
+      set(event);
+    });
+    return () => {
+      unsubscribe();
+    };
+  });
+}
+function contextStore(pattern) {
+  return store.readable(void 0, (set) => {
+    const kernel = getKernel();
+    const unsubscribe = kernel.on(pattern, async (_event, ctx) => {
+      set(ctx);
+    });
+    return () => {
+      unsubscribe();
+    };
+  });
+}
+
+exports.KernelContextError = KernelContextError;
+exports.contextStore = contextStore;
+exports.eventStore = eventStore;
+exports.getKernel = getKernel;
+exports.onEvent = onEvent;
+exports.setKernel = setKernel;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/context.ts","../src/stores.ts"],"names":["setContext","getContext","onDestroy","readable"],"mappings":";;;;;;AAcA,IAAM,kBAAA,0BAA4B,YAAY,CAAA;AAKvC,IAAM,kBAAA,GAAN,cAAiC,KAAA,CAAM;AAAA,EAC5C,WAAA,GAAc;AACZ,IAAA,KAAA;AAAA,MACE;AAAA,KAEF;AACA,IAAA,IAAA,CAAK,IAAA,GAAO,oBAAA;AAAA,EACd;AACF;AAqBO,SAAS,UAAU,MAAA,EAAsB;AAC9C,EAAA,IAAI,CAAC,MAAA,EAAQ;AACX,IAAA,MAAM,IAAI,MAAM,4DAA4D,CAAA;AAAA,EAC9E;AAEA,EAAAA,iBAAA,CAAW,oBAAoB,MAAM,CAAA;AACvC;AAuBO,SAAS,SAAA,GAA0C;AACxD,EAAA,MAAM,MAAA,GAASC,kBAAc,kBAAkB,CAAA;AAE/C,EAAA,IAAI,CAAC,MAAA,EAAQ;AACX,IAAA,MAAM,IAAI,kBAAA,EAAmB;AAAA,EAC/B;AAEA,EAAA,OAAO,MAAA;AACT;AAoCO,SAAS,OAAA,CACd,SACA,OAAA,EACY;AACZ,EAAA,MAAM,SAAS,SAAA,EAAU;AAGzB,EAAA,MAAM,WAAA,GAAc,MAAA,CAAO,EAAA,CAAG,OAAA,EAAS,OAAO,CAAA;AAG9C,EAAAC,gBAAA,CAAU,MAAM;AACd,IAAA,WAAA,EAAY;AAAA,EACd,CAAC,CAAA;AAED,EAAA,OAAO,WAAA;AACT;AC/FO,SAAS,WAAoB,OAAA,EAAwD;AAC1F,EAAA,OAAOC,cAAA,CAAsC,MAAA,EAAW,CAAC,GAAA,KAAQ;AAC/D,IAAA,MAAM,SAAS,SAAA,EAAU;AAGzB,IAAA,MAAM,cAAc,MAAA,CAAO,EAAA,CAAG,OAAA,EAAS,OAAO,OAAO,QAAA,KAAa;AAChE,MAAA,GAAA,CAAI,KAAK,CAAA;AAAA,IACX,CAAC,CAAA;AAGD,IAAA,OAAO,MAAM;AACX,MAAA,WAAA,EAAY;AAAA,IACd,CAAA;AAAA,EACF,CAAC,CAAA;AACH;AA4BO,SAAS,aAAa,OAAA,EAAyD;AACpF,EAAA,OAAOA,cAAA,CAAuC,MAAA,EAAW,CAAC,GAAA,KAAQ;AAChE,IAAA,MAAM,SAAS,SAAA,EAAU;AAGzB,IAAA,MAAM,cAAc,MAAA,CAAO,EAAA,CAAG,OAAA,EAAS,OAAO,QAAQ,GAAA,KAAQ;AAC5D,MAAA,GAAA,CAAI,GAAG,CAAA;AAAA,IACT,CAAC,CAAA;AAGD,IAAA,OAAO,MAAM;AACX,MAAA,WAAA,EAAY;AAAA,IACd,CAAA;AAAA,EACF,CAAC,CAAA;AACH","file":"index.cjs","sourcesContent":["/**\n * Svelte context API for QuarKernel integration\n *\n * Provides setKernel/getKernel for dependency injection and onEvent\n * composable for event subscriptions with automatic cleanup.\n */\n\nimport { getContext, setContext, onDestroy } from 'svelte';\nimport type { Kernel } from '@quazardous/quarkernel';\n\n/**\n * Context key for kernel instance\n * @internal\n */\nconst KERNEL_CONTEXT_KEY = Symbol('quarkernel');\n\n/**\n * Error thrown when getKernel is called outside context\n */\nexport class KernelContextError extends Error {\n  constructor() {\n    super(\n      'getKernel() must be called within a component where setKernel() was used. ' +\n      'Ensure you call setKernel(kernel) in a parent component.'\n    );\n    this.name = 'KernelContextError';\n  }\n}\n\n/**\n * Store kernel instance in Svelte context\n *\n * Must be called during component initialization (top level of component script).\n * Makes kernel available to all child components via getKernel().\n *\n * @param kernel - Kernel instance to provide to child components\n *\n * @example\n * ```svelte\n * <script>\n *   import { createKernel } from '@quazardous/quarkernel';\n *   import { setKernel } from '@quazardous/quarkernel-svelte';\n *\n *   const kernel = createKernel();\n *   setKernel(kernel);\n * </script>\n * ```\n */\nexport function setKernel(kernel: Kernel): void {\n  if (!kernel) {\n    throw new Error('[QuarKernel Svelte] setKernel() requires a kernel instance');\n  }\n\n  setContext(KERNEL_CONTEXT_KEY, kernel);\n}\n\n/**\n * Retrieve kernel instance from Svelte context\n *\n * Must be called within a component where a parent called setKernel().\n * Throws KernelContextError if kernel not found in context.\n *\n * @throws {KernelContextError} If called outside context or before setKernel()\n * @returns The kernel instance\n *\n * @example\n * ```svelte\n * <script>\n *   import { getKernel } from '@quazardous/quarkernel-svelte';\n *\n *   const kernel = getKernel();\n *\n *   // Use kernel directly\n *   kernel.emit('user:login', { id: 123 });\n * </script>\n * ```\n */\nexport function getKernel<T extends Kernel = Kernel>(): T {\n  const kernel = getContext<T>(KERNEL_CONTEXT_KEY);\n\n  if (!kernel) {\n    throw new KernelContextError();\n  }\n\n  return kernel;\n}\n\n/**\n * Register an event listener with automatic cleanup on component destroy\n *\n * Convenience wrapper around kernel.on() that:\n * - Retrieves kernel from context\n * - Registers the listener\n * - Automatically unsubscribes when component is destroyed\n * - Returns unsubscribe function for manual cleanup\n *\n * @param pattern - Event name or pattern (supports wildcards)\n * @param handler - Event handler function\n * @returns Unsubscribe function to manually remove listener before destroy\n *\n * @example\n * ```svelte\n * <script>\n *   import { onEvent } from '@quazardous/quarkernel-svelte';\n *\n *   // Auto-cleanup on component destroy\n *   onEvent('user:*', async (event) => {\n *     console.log('User event:', event.data);\n *   });\n *\n *   // Manual cleanup if needed\n *   const unsubscribe = onEvent('cart:update', (event) => {\n *     console.log('Cart updated');\n *   });\n *\n *   function handleClick() {\n *     unsubscribe(); // Remove listener early\n *   }\n * </script>\n * ```\n */\nexport function onEvent(\n  pattern: string,\n  handler: (event: any, ctx: any) => void | Promise<void>\n): () => void {\n  const kernel = getKernel();\n\n  // Register listener and get unsubscribe function\n  const unsubscribe = kernel.on(pattern, handler);\n\n  // Auto-cleanup on component destroy\n  onDestroy(() => {\n    unsubscribe();\n  });\n\n  return unsubscribe;\n}\n","/**\n * Reactive Svelte stores for QuarKernel events\n *\n * Provides eventStore and contextStore factories that wrap kernel events\n * in Svelte readable stores with automatic subscription management.\n */\n\nimport { readable } from 'svelte/store';\nimport type { Readable } from 'svelte/store';\nimport type { IKernelEvent, IListenerContext } from '@quazardous/quarkernel';\nimport { getKernel } from './context.js';\n\n/**\n * Create a readable store that updates when matching events occur\n *\n * The store subscribes to kernel events matching the pattern and updates\n * with the latest event data. Automatically manages kernel subscriptions\n * based on store subscription lifecycle.\n *\n * @param pattern - Event name or wildcard pattern to match\n * @returns Readable store containing latest event data (or undefined initially)\n *\n * @example\n * ```svelte\n * <script>\n *   import { eventStore } from '@quazardous/quarkernel-svelte';\n *\n *   const userEvents = eventStore('user:*');\n *\n *   // Svelte 5 runes\n *   $: console.log('Latest user event:', $userEvents);\n * </script>\n *\n * <div>\n *   {#if $userEvents}\n *     <p>Event: {$userEvents.name}</p>\n *     <p>Data: {JSON.stringify($userEvents.data)}</p>\n *   {/if}\n * </div>\n * ```\n */\nexport function eventStore<T = any>(pattern: string): Readable<IKernelEvent<T> | undefined> {\n  return readable<IKernelEvent<T> | undefined>(undefined, (set) => {\n    const kernel = getKernel();\n\n    // Subscribe to kernel events and update store\n    const unsubscribe = kernel.on(pattern, async (event, _context) => {\n      set(event);\n    });\n\n    // Return cleanup function - called when store has no subscribers\n    return () => {\n      unsubscribe();\n    };\n  });\n}\n\n/**\n * Create a readable store that updates with current listener context\n *\n * Useful for accessing context data in reactive Svelte components.\n * The store updates whenever an event matching the pattern is processed\n * and provides access to the listener context object.\n *\n * @param pattern - Event name or wildcard pattern to match\n * @returns Readable store containing latest listener context (or undefined initially)\n *\n * @example\n * ```svelte\n * <script>\n *   import { contextStore } from '@quazardous/quarkernel-svelte';\n *\n *   const ctx = contextStore('cart:*');\n * </script>\n *\n * <div>\n *   {#if $ctx}\n *     <p>Listener ID: {$ctx.id}</p>\n *     <p>Context data: {JSON.stringify($ctx)}</p>\n *   {/if}\n * </div>\n * ```\n */\nexport function contextStore(pattern: string): Readable<IListenerContext | undefined> {\n  return readable<IListenerContext | undefined>(undefined, (set) => {\n    const kernel = getKernel();\n\n    // Subscribe to kernel events and update store with context\n    const unsubscribe = kernel.on(pattern, async (_event, ctx) => {\n      set(ctx);\n    });\n\n    // Return cleanup function - called when store has no subscribers\n    return () => {\n      unsubscribe();\n    };\n  });\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,160 @@
+import { Kernel, IKernelEvent, IListenerContext } from '@quazardous/quarkernel';
+import { Readable } from 'svelte/store';
+
+/**
+ * Svelte context API for QuarKernel integration
+ *
+ * Provides setKernel/getKernel for dependency injection and onEvent
+ * composable for event subscriptions with automatic cleanup.
+ */
+
+/**
+ * Error thrown when getKernel is called outside context
+ */
+declare class KernelContextError extends Error {
+    constructor();
+}
+/**
+ * Store kernel instance in Svelte context
+ *
+ * Must be called during component initialization (top level of component script).
+ * Makes kernel available to all child components via getKernel().
+ *
+ * @param kernel - Kernel instance to provide to child components
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { createKernel } from '@quazardous/quarkernel';
+ *   import { setKernel } from '@quazardous/quarkernel-svelte';
+ *
+ *   const kernel = createKernel();
+ *   setKernel(kernel);
+ * </script>
+ * ```
+ */
+declare function setKernel(kernel: Kernel): void;
+/**
+ * Retrieve kernel instance from Svelte context
+ *
+ * Must be called within a component where a parent called setKernel().
+ * Throws KernelContextError if kernel not found in context.
+ *
+ * @throws {KernelContextError} If called outside context or before setKernel()
+ * @returns The kernel instance
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { getKernel } from '@quazardous/quarkernel-svelte';
+ *
+ *   const kernel = getKernel();
+ *
+ *   // Use kernel directly
+ *   kernel.emit('user:login', { id: 123 });
+ * </script>
+ * ```
+ */
+declare function getKernel<T extends Kernel = Kernel>(): T;
+/**
+ * Register an event listener with automatic cleanup on component destroy
+ *
+ * Convenience wrapper around kernel.on() that:
+ * - Retrieves kernel from context
+ * - Registers the listener
+ * - Automatically unsubscribes when component is destroyed
+ * - Returns unsubscribe function for manual cleanup
+ *
+ * @param pattern - Event name or pattern (supports wildcards)
+ * @param handler - Event handler function
+ * @returns Unsubscribe function to manually remove listener before destroy
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { onEvent } from '@quazardous/quarkernel-svelte';
+ *
+ *   // Auto-cleanup on component destroy
+ *   onEvent('user:*', async (event) => {
+ *     console.log('User event:', event.data);
+ *   });
+ *
+ *   // Manual cleanup if needed
+ *   const unsubscribe = onEvent('cart:update', (event) => {
+ *     console.log('Cart updated');
+ *   });
+ *
+ *   function handleClick() {
+ *     unsubscribe(); // Remove listener early
+ *   }
+ * </script>
+ * ```
+ */
+declare function onEvent(pattern: string, handler: (event: any, ctx: any) => void | Promise<void>): () => void;
+
+/**
+ * Reactive Svelte stores for QuarKernel events
+ *
+ * Provides eventStore and contextStore factories that wrap kernel events
+ * in Svelte readable stores with automatic subscription management.
+ */
+
+/**
+ * Create a readable store that updates when matching events occur
+ *
+ * The store subscribes to kernel events matching the pattern and updates
+ * with the latest event data. Automatically manages kernel subscriptions
+ * based on store subscription lifecycle.
+ *
+ * @param pattern - Event name or wildcard pattern to match
+ * @returns Readable store containing latest event data (or undefined initially)
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { eventStore } from '@quazardous/quarkernel-svelte';
+ *
+ *   const userEvents = eventStore('user:*');
+ *
+ *   // Svelte 5 runes
+ *   $: console.log('Latest user event:', $userEvents);
+ * </script>
+ *
+ * <div>
+ *   {#if $userEvents}
+ *     <p>Event: {$userEvents.name}</p>
+ *     <p>Data: {JSON.stringify($userEvents.data)}</p>
+ *   {/if}
+ * </div>
+ * ```
+ */
+declare function eventStore<T = any>(pattern: string): Readable<IKernelEvent<T> | undefined>;
+/**
+ * Create a readable store that updates with current listener context
+ *
+ * Useful for accessing context data in reactive Svelte components.
+ * The store updates whenever an event matching the pattern is processed
+ * and provides access to the listener context object.
+ *
+ * @param pattern - Event name or wildcard pattern to match
+ * @returns Readable store containing latest listener context (or undefined initially)
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { contextStore } from '@quazardous/quarkernel-svelte';
+ *
+ *   const ctx = contextStore('cart:*');
+ * </script>
+ *
+ * <div>
+ *   {#if $ctx}
+ *     <p>Listener ID: {$ctx.id}</p>
+ *     <p>Context data: {JSON.stringify($ctx)}</p>
+ *   {/if}
+ * </div>
+ * ```
+ */
+declare function contextStore(pattern: string): Readable<IListenerContext | undefined>;
+
+export { KernelContextError, contextStore, eventStore, getKernel, onEvent, setKernel };

package/dist/index.d.ts

@@ -0,0 +1,160 @@
+import { Kernel, IKernelEvent, IListenerContext } from '@quazardous/quarkernel';
+import { Readable } from 'svelte/store';
+
+/**
+ * Svelte context API for QuarKernel integration
+ *
+ * Provides setKernel/getKernel for dependency injection and onEvent
+ * composable for event subscriptions with automatic cleanup.
+ */
+
+/**
+ * Error thrown when getKernel is called outside context
+ */
+declare class KernelContextError extends Error {
+    constructor();
+}
+/**
+ * Store kernel instance in Svelte context
+ *
+ * Must be called during component initialization (top level of component script).
+ * Makes kernel available to all child components via getKernel().
+ *
+ * @param kernel - Kernel instance to provide to child components
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { createKernel } from '@quazardous/quarkernel';
+ *   import { setKernel } from '@quazardous/quarkernel-svelte';
+ *
+ *   const kernel = createKernel();
+ *   setKernel(kernel);
+ * </script>
+ * ```
+ */
+declare function setKernel(kernel: Kernel): void;
+/**
+ * Retrieve kernel instance from Svelte context
+ *
+ * Must be called within a component where a parent called setKernel().
+ * Throws KernelContextError if kernel not found in context.
+ *
+ * @throws {KernelContextError} If called outside context or before setKernel()
+ * @returns The kernel instance
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { getKernel } from '@quazardous/quarkernel-svelte';
+ *
+ *   const kernel = getKernel();
+ *
+ *   // Use kernel directly
+ *   kernel.emit('user:login', { id: 123 });
+ * </script>
+ * ```
+ */
+declare function getKernel<T extends Kernel = Kernel>(): T;
+/**
+ * Register an event listener with automatic cleanup on component destroy
+ *
+ * Convenience wrapper around kernel.on() that:
+ * - Retrieves kernel from context
+ * - Registers the listener
+ * - Automatically unsubscribes when component is destroyed
+ * - Returns unsubscribe function for manual cleanup
+ *
+ * @param pattern - Event name or pattern (supports wildcards)
+ * @param handler - Event handler function
+ * @returns Unsubscribe function to manually remove listener before destroy
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { onEvent } from '@quazardous/quarkernel-svelte';
+ *
+ *   // Auto-cleanup on component destroy
+ *   onEvent('user:*', async (event) => {
+ *     console.log('User event:', event.data);
+ *   });
+ *
+ *   // Manual cleanup if needed
+ *   const unsubscribe = onEvent('cart:update', (event) => {
+ *     console.log('Cart updated');
+ *   });
+ *
+ *   function handleClick() {
+ *     unsubscribe(); // Remove listener early
+ *   }
+ * </script>
+ * ```
+ */
+declare function onEvent(pattern: string, handler: (event: any, ctx: any) => void | Promise<void>): () => void;
+
+/**
+ * Reactive Svelte stores for QuarKernel events
+ *
+ * Provides eventStore and contextStore factories that wrap kernel events
+ * in Svelte readable stores with automatic subscription management.
+ */
+
+/**
+ * Create a readable store that updates when matching events occur
+ *
+ * The store subscribes to kernel events matching the pattern and updates
+ * with the latest event data. Automatically manages kernel subscriptions
+ * based on store subscription lifecycle.
+ *
+ * @param pattern - Event name or wildcard pattern to match
+ * @returns Readable store containing latest event data (or undefined initially)
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { eventStore } from '@quazardous/quarkernel-svelte';
+ *
+ *   const userEvents = eventStore('user:*');
+ *
+ *   // Svelte 5 runes
+ *   $: console.log('Latest user event:', $userEvents);
+ * </script>
+ *
+ * <div>
+ *   {#if $userEvents}
+ *     <p>Event: {$userEvents.name}</p>
+ *     <p>Data: {JSON.stringify($userEvents.data)}</p>
+ *   {/if}
+ * </div>
+ * ```
+ */
+declare function eventStore<T = any>(pattern: string): Readable<IKernelEvent<T> | undefined>;
+/**
+ * Create a readable store that updates with current listener context
+ *
+ * Useful for accessing context data in reactive Svelte components.
+ * The store updates whenever an event matching the pattern is processed
+ * and provides access to the listener context object.
+ *
+ * @param pattern - Event name or wildcard pattern to match
+ * @returns Readable store containing latest listener context (or undefined initially)
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { contextStore } from '@quazardous/quarkernel-svelte';
+ *
+ *   const ctx = contextStore('cart:*');
+ * </script>
+ *
+ * <div>
+ *   {#if $ctx}
+ *     <p>Listener ID: {$ctx.id}</p>
+ *     <p>Context data: {JSON.stringify($ctx)}</p>
+ *   {/if}
+ * </div>
+ * ```
+ */
+declare function contextStore(pattern: string): Readable<IListenerContext | undefined>;
+
+export { KernelContextError, contextStore, eventStore, getKernel, onEvent, setKernel };

package/dist/index.js

@@ -0,0 +1,60 @@
+import { setContext, getContext, onDestroy } from 'svelte';
+import { readable } from 'svelte/store';
+
+// src/context.ts
+var KERNEL_CONTEXT_KEY = /* @__PURE__ */ Symbol("quarkernel");
+var KernelContextError = class extends Error {
+  constructor() {
+    super(
+      "getKernel() must be called within a component where setKernel() was used. Ensure you call setKernel(kernel) in a parent component."
+    );
+    this.name = "KernelContextError";
+  }
+};
+function setKernel(kernel) {
+  if (!kernel) {
+    throw new Error("[QuarKernel Svelte] setKernel() requires a kernel instance");
+  }
+  setContext(KERNEL_CONTEXT_KEY, kernel);
+}
+function getKernel() {
+  const kernel = getContext(KERNEL_CONTEXT_KEY);
+  if (!kernel) {
+    throw new KernelContextError();
+  }
+  return kernel;
+}
+function onEvent(pattern, handler) {
+  const kernel = getKernel();
+  const unsubscribe = kernel.on(pattern, handler);
+  onDestroy(() => {
+    unsubscribe();
+  });
+  return unsubscribe;
+}
+function eventStore(pattern) {
+  return readable(void 0, (set) => {
+    const kernel = getKernel();
+    const unsubscribe = kernel.on(pattern, async (event, _context) => {
+      set(event);
+    });
+    return () => {
+      unsubscribe();
+    };
+  });
+}
+function contextStore(pattern) {
+  return readable(void 0, (set) => {
+    const kernel = getKernel();
+    const unsubscribe = kernel.on(pattern, async (_event, ctx) => {
+      set(ctx);
+    });
+    return () => {
+      unsubscribe();
+    };
+  });
+}
+
+export { KernelContextError, contextStore, eventStore, getKernel, onEvent, setKernel };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/context.ts","../src/stores.ts"],"names":[],"mappings":";;;;AAcA,IAAM,kBAAA,0BAA4B,YAAY,CAAA;AAKvC,IAAM,kBAAA,GAAN,cAAiC,KAAA,CAAM;AAAA,EAC5C,WAAA,GAAc;AACZ,IAAA,KAAA;AAAA,MACE;AAAA,KAEF;AACA,IAAA,IAAA,CAAK,IAAA,GAAO,oBAAA;AAAA,EACd;AACF;AAqBO,SAAS,UAAU,MAAA,EAAsB;AAC9C,EAAA,IAAI,CAAC,MAAA,EAAQ;AACX,IAAA,MAAM,IAAI,MAAM,4DAA4D,CAAA;AAAA,EAC9E;AAEA,EAAA,UAAA,CAAW,oBAAoB,MAAM,CAAA;AACvC;AAuBO,SAAS,SAAA,GAA0C;AACxD,EAAA,MAAM,MAAA,GAAS,WAAc,kBAAkB,CAAA;AAE/C,EAAA,IAAI,CAAC,MAAA,EAAQ;AACX,IAAA,MAAM,IAAI,kBAAA,EAAmB;AAAA,EAC/B;AAEA,EAAA,OAAO,MAAA;AACT;AAoCO,SAAS,OAAA,CACd,SACA,OAAA,EACY;AACZ,EAAA,MAAM,SAAS,SAAA,EAAU;AAGzB,EAAA,MAAM,WAAA,GAAc,MAAA,CAAO,EAAA,CAAG,OAAA,EAAS,OAAO,CAAA;AAG9C,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,WAAA,EAAY;AAAA,EACd,CAAC,CAAA;AAED,EAAA,OAAO,WAAA;AACT;AC/FO,SAAS,WAAoB,OAAA,EAAwD;AAC1F,EAAA,OAAO,QAAA,CAAsC,MAAA,EAAW,CAAC,GAAA,KAAQ;AAC/D,IAAA,MAAM,SAAS,SAAA,EAAU;AAGzB,IAAA,MAAM,cAAc,MAAA,CAAO,EAAA,CAAG,OAAA,EAAS,OAAO,OAAO,QAAA,KAAa;AAChE,MAAA,GAAA,CAAI,KAAK,CAAA;AAAA,IACX,CAAC,CAAA;AAGD,IAAA,OAAO,MAAM;AACX,MAAA,WAAA,EAAY;AAAA,IACd,CAAA;AAAA,EACF,CAAC,CAAA;AACH;AA4BO,SAAS,aAAa,OAAA,EAAyD;AACpF,EAAA,OAAO,QAAA,CAAuC,MAAA,EAAW,CAAC,GAAA,KAAQ;AAChE,IAAA,MAAM,SAAS,SAAA,EAAU;AAGzB,IAAA,MAAM,cAAc,MAAA,CAAO,EAAA,CAAG,OAAA,EAAS,OAAO,QAAQ,GAAA,KAAQ;AAC5D,MAAA,GAAA,CAAI,GAAG,CAAA;AAAA,IACT,CAAC,CAAA;AAGD,IAAA,OAAO,MAAM;AACX,MAAA,WAAA,EAAY;AAAA,IACd,CAAA;AAAA,EACF,CAAC,CAAA;AACH","file":"index.js","sourcesContent":["/**\n * Svelte context API for QuarKernel integration\n *\n * Provides setKernel/getKernel for dependency injection and onEvent\n * composable for event subscriptions with automatic cleanup.\n */\n\nimport { getContext, setContext, onDestroy } from 'svelte';\nimport type { Kernel } from '@quazardous/quarkernel';\n\n/**\n * Context key for kernel instance\n * @internal\n */\nconst KERNEL_CONTEXT_KEY = Symbol('quarkernel');\n\n/**\n * Error thrown when getKernel is called outside context\n */\nexport class KernelContextError extends Error {\n  constructor() {\n    super(\n      'getKernel() must be called within a component where setKernel() was used. ' +\n      'Ensure you call setKernel(kernel) in a parent component.'\n    );\n    this.name = 'KernelContextError';\n  }\n}\n\n/**\n * Store kernel instance in Svelte context\n *\n * Must be called during component initialization (top level of component script).\n * Makes kernel available to all child components via getKernel().\n *\n * @param kernel - Kernel instance to provide to child components\n *\n * @example\n * ```svelte\n * <script>\n *   import { createKernel } from '@quazardous/quarkernel';\n *   import { setKernel } from '@quazardous/quarkernel-svelte';\n *\n *   const kernel = createKernel();\n *   setKernel(kernel);\n * </script>\n * ```\n */\nexport function setKernel(kernel: Kernel): void {\n  if (!kernel) {\n    throw new Error('[QuarKernel Svelte] setKernel() requires a kernel instance');\n  }\n\n  setContext(KERNEL_CONTEXT_KEY, kernel);\n}\n\n/**\n * Retrieve kernel instance from Svelte context\n *\n * Must be called within a component where a parent called setKernel().\n * Throws KernelContextError if kernel not found in context.\n *\n * @throws {KernelContextError} If called outside context or before setKernel()\n * @returns The kernel instance\n *\n * @example\n * ```svelte\n * <script>\n *   import { getKernel } from '@quazardous/quarkernel-svelte';\n *\n *   const kernel = getKernel();\n *\n *   // Use kernel directly\n *   kernel.emit('user:login', { id: 123 });\n * </script>\n * ```\n */\nexport function getKernel<T extends Kernel = Kernel>(): T {\n  const kernel = getContext<T>(KERNEL_CONTEXT_KEY);\n\n  if (!kernel) {\n    throw new KernelContextError();\n  }\n\n  return kernel;\n}\n\n/**\n * Register an event listener with automatic cleanup on component destroy\n *\n * Convenience wrapper around kernel.on() that:\n * - Retrieves kernel from context\n * - Registers the listener\n * - Automatically unsubscribes when component is destroyed\n * - Returns unsubscribe function for manual cleanup\n *\n * @param pattern - Event name or pattern (supports wildcards)\n * @param handler - Event handler function\n * @returns Unsubscribe function to manually remove listener before destroy\n *\n * @example\n * ```svelte\n * <script>\n *   import { onEvent } from '@quazardous/quarkernel-svelte';\n *\n *   // Auto-cleanup on component destroy\n *   onEvent('user:*', async (event) => {\n *     console.log('User event:', event.data);\n *   });\n *\n *   // Manual cleanup if needed\n *   const unsubscribe = onEvent('cart:update', (event) => {\n *     console.log('Cart updated');\n *   });\n *\n *   function handleClick() {\n *     unsubscribe(); // Remove listener early\n *   }\n * </script>\n * ```\n */\nexport function onEvent(\n  pattern: string,\n  handler: (event: any, ctx: any) => void | Promise<void>\n): () => void {\n  const kernel = getKernel();\n\n  // Register listener and get unsubscribe function\n  const unsubscribe = kernel.on(pattern, handler);\n\n  // Auto-cleanup on component destroy\n  onDestroy(() => {\n    unsubscribe();\n  });\n\n  return unsubscribe;\n}\n","/**\n * Reactive Svelte stores for QuarKernel events\n *\n * Provides eventStore and contextStore factories that wrap kernel events\n * in Svelte readable stores with automatic subscription management.\n */\n\nimport { readable } from 'svelte/store';\nimport type { Readable } from 'svelte/store';\nimport type { IKernelEvent, IListenerContext } from '@quazardous/quarkernel';\nimport { getKernel } from './context.js';\n\n/**\n * Create a readable store that updates when matching events occur\n *\n * The store subscribes to kernel events matching the pattern and updates\n * with the latest event data. Automatically manages kernel subscriptions\n * based on store subscription lifecycle.\n *\n * @param pattern - Event name or wildcard pattern to match\n * @returns Readable store containing latest event data (or undefined initially)\n *\n * @example\n * ```svelte\n * <script>\n *   import { eventStore } from '@quazardous/quarkernel-svelte';\n *\n *   const userEvents = eventStore('user:*');\n *\n *   // Svelte 5 runes\n *   $: console.log('Latest user event:', $userEvents);\n * </script>\n *\n * <div>\n *   {#if $userEvents}\n *     <p>Event: {$userEvents.name}</p>\n *     <p>Data: {JSON.stringify($userEvents.data)}</p>\n *   {/if}\n * </div>\n * ```\n */\nexport function eventStore<T = any>(pattern: string): Readable<IKernelEvent<T> | undefined> {\n  return readable<IKernelEvent<T> | undefined>(undefined, (set) => {\n    const kernel = getKernel();\n\n    // Subscribe to kernel events and update store\n    const unsubscribe = kernel.on(pattern, async (event, _context) => {\n      set(event);\n    });\n\n    // Return cleanup function - called when store has no subscribers\n    return () => {\n      unsubscribe();\n    };\n  });\n}\n\n/**\n * Create a readable store that updates with current listener context\n *\n * Useful for accessing context data in reactive Svelte components.\n * The store updates whenever an event matching the pattern is processed\n * and provides access to the listener context object.\n *\n * @param pattern - Event name or wildcard pattern to match\n * @returns Readable store containing latest listener context (or undefined initially)\n *\n * @example\n * ```svelte\n * <script>\n *   import { contextStore } from '@quazardous/quarkernel-svelte';\n *\n *   const ctx = contextStore('cart:*');\n * </script>\n *\n * <div>\n *   {#if $ctx}\n *     <p>Listener ID: {$ctx.id}</p>\n *     <p>Context data: {JSON.stringify($ctx)}</p>\n *   {/if}\n * </div>\n * ```\n */\nexport function contextStore(pattern: string): Readable<IListenerContext | undefined> {\n  return readable<IListenerContext | undefined>(undefined, (set) => {\n    const kernel = getKernel();\n\n    // Subscribe to kernel events and update store with context\n    const unsubscribe = kernel.on(pattern, async (_event, ctx) => {\n      set(ctx);\n    });\n\n    // Return cleanup function - called when store has no subscribers\n    return () => {\n      unsubscribe();\n    };\n  });\n}\n"]}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@quazardous/quarkernel-svelte",
+  "version": "2.1.0",
+  "type": "module",
+  "description": "Svelte 5 adapter for QuarKernel - event kernel integration with Svelte context",
+  "author": "quazardous <berliozdavid@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/quazardous/quarkernel.git",
+    "directory": "packages/svelte"
+  },
+  "bugs": {
+    "url": "https://github.com/quazardous/quarkernel/issues"
+  },
+  "homepage": "https://github.com/quazardous/quarkernel#readme",
+  "keywords": [
+    "quarkernel",
+    "svelte",
+    "svelte5",
+    "event",
+    "events",
+    "kernel",
+    "context",
+    "composable",
+    "reactivity"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "build:watch": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  },
+  "peerDependencies": {
+    "@quazardous/quarkernel": "^2.1.0",
+    "svelte": "^5.0.0"
+  },
+  "devDependencies": {
+    "@quazardous/quarkernel": "file:../quarkernel",
+    "svelte": "^5.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  }
+}