@almadar/runtime 1.0.15 → 1.0.17

package/dist/index.d.ts

@@ -259,6 +259,67 @@ declare class EffectExecutor {
  */
 declare function createTestExecutor(overrides?: Partial<EffectHandlers>): EffectExecutor;
 
+/**
+ * Client Effect Handlers Factory
+ *
+ * Creates the standard effect handler set for client-side trait execution.
+ * Platform-agnostic — works with any UI framework that provides the required interfaces.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Minimal event bus interface required by the factory.
+ */
+interface ClientEventBus {
+    emit: (type: string, payload?: Record<string, unknown>) => void;
+}
+/**
+ * Slot setter interface for render-ui effects.
+ * The factory doesn't know about React state — it just calls this function.
+ */
+interface SlotSetter {
+    /** Accumulate a pattern into the pending slot map */
+    addPattern: (slot: string, pattern: unknown, props?: Record<string, unknown>) => void;
+    /** Mark a slot for clearing */
+    clearSlot: (slot: string) => void;
+}
+/**
+ * Options for creating client effect handlers.
+ */
+interface CreateClientEffectHandlersOptions {
+    /** Event bus for emit effects */
+    eventBus: ClientEventBus;
+    /** Slot setter for render-ui effects */
+    slotSetter: SlotSetter;
+    /** Navigate function for navigate effects */
+    navigate?: (path: string, params?: Record<string, unknown>) => void;
+    /** Notify function for notification effects */
+    notify?: (message: string, type: 'success' | 'error' | 'warning' | 'info') => void;
+    /** Entity enrichment: inject linkedEntity into entity-aware patterns */
+    enrichPattern?: (pattern: unknown) => unknown;
+}
+/**
+ * Create client-side effect handlers for trait state machine execution.
+ *
+ * Client handles: emit, renderUI, navigate, notify
+ * Server handles: persist, set, callService (logged as warnings on client)
+ *
+ * @example
+ * ```ts
+ * const handlers = createClientEffectHandlers({
+ *   eventBus,
+ *   slotSetter: {
+ *     addPattern: (slot, pattern, props) => pendingSlots.get(slot)?.push({ pattern, props }),
+ *     clearSlot: (slot) => pendingSlots.set(slot, []),
+ *   },
+ *   navigate: (path) => router.push(path),
+ *   notify: (msg, type) => toast[type](msg),
+ * });
+ * ```
+ */
+declare function createClientEffectHandlers(options: CreateClientEffectHandlersOptions): EffectHandlers;
+
 /**
  * MockPersistenceAdapter - In-memory data store with faker-based mock generation
  *
@@ -290,4 +351,4 @@ interface MockPersistenceConfig {
     debug?: boolean;
 }
 
-export { BindingContext, EffectContext, EffectExecutor, type EffectExecutorOptions, EffectHandlers, type EntityField, type EntitySchema, type MockPersistenceConfig, type ProcessEventOptions, StateMachineManager, TraitDefinition, TraitState, TransitionResult, containsBindings, createContextFromBindings, createInitialTraitState, createTestExecutor, extractBindings, findInitialState, findTransition, interpolateProps, interpolateValue, normalizeEventKey, processEvent };
+export { BindingContext, type ClientEventBus, type CreateClientEffectHandlersOptions, EffectContext, EffectExecutor, type EffectExecutorOptions, EffectHandlers, type EntityField, type EntitySchema, type MockPersistenceConfig, type ProcessEventOptions, type SlotSetter, StateMachineManager, TraitDefinition, TraitState, TransitionResult, containsBindings, createClientEffectHandlers, createContextFromBindings, createInitialTraitState, createTestExecutor, extractBindings, findInitialState, findTransition, interpolateProps, interpolateValue, normalizeEventKey, processEvent };

package/dist/index.js

@@ -1,3 +1,40 @@
 export { EffectExecutor, EventBus, StateMachineManager, containsBindings, createContextFromBindings, createInitialTraitState, createMinimalContext, createTestExecutor, extractBindings, findInitialState, findTransition, getIsolatedCollectionName, getNamespacedEvent, interpolateProps, interpolateValue, isNamespacedEvent, normalizeEventKey, parseNamespacedEvent, preprocessSchema, processEvent } from './chunk-KUL6GQI5.js';
+
+// src/ClientEffectHandlers.ts
+function createClientEffectHandlers(options) {
+  const { eventBus, slotSetter, navigate, notify, enrichPattern } = options;
+  return {
+    emit: (event, payload) => {
+      const prefixedEvent = event.startsWith("UI:") ? event : `UI:${event}`;
+      eventBus.emit(prefixedEvent, { payload });
+    },
+    persist: async () => {
+      console.warn("[ClientEffectHandlers] persist is server-side only, ignored on client");
+    },
+    set: () => {
+      console.warn("[ClientEffectHandlers] set is server-side only, ignored on client");
+    },
+    callService: async () => {
+      console.warn("[ClientEffectHandlers] callService is server-side only, ignored on client");
+      return {};
+    },
+    renderUI: (slot, pattern, props) => {
+      if (pattern === null) {
+        slotSetter.clearSlot(slot);
+        return;
+      }
+      const enriched = enrichPattern ? enrichPattern(pattern) : pattern;
+      slotSetter.addPattern(slot, enriched, props);
+    },
+    navigate: navigate ?? ((path) => {
+      console.warn("[ClientEffectHandlers] No navigate handler, ignoring:", path);
+    }),
+    notify: notify ?? ((msg, type) => {
+      console.log(`[ClientEffectHandlers] notify (${type}):`, msg);
+    })
+  };
+}
+
+export { createClientEffectHandlers };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}
+{"version":3,"sources":["../src/ClientEffectHandlers.ts"],"names":[],"mappings":";;;AAwEO,SAAS,2BACZ,OAAA,EACc;AACd,EAAA,MAAM,EAAE,QAAA,EAAU,UAAA,EAAY,QAAA,EAAU,MAAA,EAAQ,eAAc,GAAI,OAAA;AAElE,EAAA,OAAO;AAAA,IACH,IAAA,EAAM,CAAC,KAAA,EAAe,OAAA,KAAsC;AACxD,MAAA,MAAM,gBAAgB,KAAA,CAAM,UAAA,CAAW,KAAK,CAAA,GAAI,KAAA,GAAQ,MAAM,KAAK,CAAA,CAAA;AACnE,MAAA,QAAA,CAAS,IAAA,CAAK,aAAA,EAAe,EAAE,OAAA,EAAS,CAAA;AAAA,IAC5C,CAAA;AAAA,IAEA,SAAS,YAAY;AACjB,MAAA,OAAA,CAAQ,KAAK,uEAAuE,CAAA;AAAA,IACxF,CAAA;AAAA,IAEA,KAAK,MAAM;AACP,MAAA,OAAA,CAAQ,KAAK,mEAAmE,CAAA;AAAA,IACpF,CAAA;AAAA,IAEA,aAAa,YAAY;AACrB,MAAA,OAAA,CAAQ,KAAK,2EAA2E,CAAA;AACxF,MAAA,OAAO,EAAC;AAAA,IACZ,CAAA;AAAA,IAEA,QAAA,EAAU,CAAC,IAAA,EAAc,OAAA,EAAkB,KAAA,KAAoC;AAC3E,MAAA,IAAI,YAAY,IAAA,EAAM;AAClB,QAAA,UAAA,CAAW,UAAU,IAAI,CAAA;AACzB,QAAA;AAAA,MACJ;AACA,MAAA,MAAM,QAAA,GAAW,aAAA,GAAgB,aAAA,CAAc,OAAO,CAAA,GAAI,OAAA;AAC1D,MAAA,UAAA,CAAW,UAAA,CAAW,IAAA,EAAM,QAAA,EAAU,KAAK,CAAA;AAAA,IAC/C,CAAA;AAAA,IAEA,QAAA,EAAU,QAAA,KAAa,CAAC,IAAA,KAAiB;AACrC,MAAA,OAAA,CAAQ,IAAA,CAAK,yDAAyD,IAAI,CAAA;AAAA,IAC9E,CAAA,CAAA;AAAA,IAEA,MAAA,EAAQ,MAAA,KAAW,CAAC,GAAA,EAAa,IAAA,KAAkB;AAC/C,MAAA,OAAA,CAAQ,GAAA,CAAI,CAAA,+BAAA,EAAkC,IAAI,CAAA,EAAA,CAAA,EAAM,GAAG,CAAA;AAAA,IAC/D,CAAA;AAAA,GACJ;AACJ","file":"index.js","sourcesContent":["/**\n * Client Effect Handlers Factory\n *\n * Creates the standard effect handler set for client-side trait execution.\n * Platform-agnostic — works with any UI framework that provides the required interfaces.\n *\n * @packageDocumentation\n */\n\nimport type { EffectHandlers } from './types.js';\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/**\n * Minimal event bus interface required by the factory.\n */\nexport interface ClientEventBus {\n    emit: (type: string, payload?: Record<string, unknown>) => void;\n}\n\n/**\n * Slot setter interface for render-ui effects.\n * The factory doesn't know about React state — it just calls this function.\n */\nexport interface SlotSetter {\n    /** Accumulate a pattern into the pending slot map */\n    addPattern: (slot: string, pattern: unknown, props?: Record<string, unknown>) => void;\n    /** Mark a slot for clearing */\n    clearSlot: (slot: string) => void;\n}\n\n/**\n * Options for creating client effect handlers.\n */\nexport interface CreateClientEffectHandlersOptions {\n    /** Event bus for emit effects */\n    eventBus: ClientEventBus;\n    /** Slot setter for render-ui effects */\n    slotSetter: SlotSetter;\n    /** Navigate function for navigate effects */\n    navigate?: (path: string, params?: Record<string, unknown>) => void;\n    /** Notify function for notification effects */\n    notify?: (message: string, type: 'success' | 'error' | 'warning' | 'info') => void;\n    /** Entity enrichment: inject linkedEntity into entity-aware patterns */\n    enrichPattern?: (pattern: unknown) => unknown;\n}\n\n// ============================================================================\n// Factory\n// ============================================================================\n\n/**\n * Create client-side effect handlers for trait state machine execution.\n *\n * Client handles: emit, renderUI, navigate, notify\n * Server handles: persist, set, callService (logged as warnings on client)\n *\n * @example\n * ```ts\n * const handlers = createClientEffectHandlers({\n *   eventBus,\n *   slotSetter: {\n *     addPattern: (slot, pattern, props) => pendingSlots.get(slot)?.push({ pattern, props }),\n *     clearSlot: (slot) => pendingSlots.set(slot, []),\n *   },\n *   navigate: (path) => router.push(path),\n *   notify: (msg, type) => toast[type](msg),\n * });\n * ```\n */\nexport function createClientEffectHandlers(\n    options: CreateClientEffectHandlersOptions\n): EffectHandlers {\n    const { eventBus, slotSetter, navigate, notify, enrichPattern } = options;\n\n    return {\n        emit: (event: string, payload?: Record<string, unknown>) => {\n            const prefixedEvent = event.startsWith('UI:') ? event : `UI:${event}`;\n            eventBus.emit(prefixedEvent, { payload });\n        },\n\n        persist: async () => {\n            console.warn('[ClientEffectHandlers] persist is server-side only, ignored on client');\n        },\n\n        set: () => {\n            console.warn('[ClientEffectHandlers] set is server-side only, ignored on client');\n        },\n\n        callService: async () => {\n            console.warn('[ClientEffectHandlers] callService is server-side only, ignored on client');\n            return {};\n        },\n\n        renderUI: (slot: string, pattern: unknown, props?: Record<string, unknown>) => {\n            if (pattern === null) {\n                slotSetter.clearSlot(slot);\n                return;\n            }\n            const enriched = enrichPattern ? enrichPattern(pattern) : pattern;\n            slotSetter.addPattern(slot, enriched, props);\n        },\n\n        navigate: navigate ?? ((path: string) => {\n            console.warn('[ClientEffectHandlers] No navigate handler, ignoring:', path);\n        }),\n\n        notify: notify ?? ((msg: string, type?: string) => {\n            console.log(`[ClientEffectHandlers] notify (${type}):`, msg);\n        }),\n    };\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/runtime",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "description": "Interpreted runtime for Almadar orbital applications (OrbitalServerRuntime)",
   "type": "module",
   "main": "./dist/index.js",
@@ -28,9 +28,9 @@
   },
   "dependencies": {
     "@faker-js/faker": "^9.3.0",
-    "@almadar/server": "1.0.14",
+    "@almadar/server": "1.0.16",
     "@almadar/evaluator": "1.0.13",
-    "@almadar/core": "1.0.14"
+    "@almadar/core": "1.0.16"
   },
   "peerDependencies": {
     "express": "^4.0.0"