@almadar/ui 3.8.3 → 3.9.0

package/dist/avl/index.cjs

@@ -51367,7 +51367,7 @@ function useTraitStateMachine(traitBindings, slotsActions, options) {
           effects: result.effects,
           traitDefinition: binding.trait
         };
-        const handlers = createClientEffectHandlers({
+        const clientHandlers = createClientEffectHandlers({
           eventBus,
           slotSetter: {
             addPattern: (slot, pattern, props) => {
@@ -51382,6 +51382,43 @@ function useTraitStateMachine(traitBindings, slotsActions, options) {
           navigate: optionsRef.current?.navigate,
           notify: optionsRef.current?.notify
         });
+        const persistence = optionsRef.current?.persistence;
+        let handlers = clientHandlers;
+        if (persistence) {
+          const sharedBindings = {
+            entity: payload ?? {},
+            payload: payload || {},
+            state: result.previousState
+          };
+          if (binding.config) {
+            sharedBindings.config = binding.config;
+          }
+          const serverHandlers = runtime.createServerEffectHandlers({
+            persistence,
+            eventBus,
+            entityType: linkedEntity,
+            entityId,
+            bindings: sharedBindings,
+            context: {
+              traitName: binding.trait.name,
+              state: result.previousState,
+              transition: `${result.previousState}->${result.newState}`,
+              linkedEntity,
+              entityId
+            },
+            source: { trait: binding.trait.name },
+            callService: optionsRef.current?.callService
+          });
+          handlers = {
+            ...serverHandlers,
+            // Client handlers own UI + emit: keep the slot setter
+            // and pre-prefixed UI:* emit path intact.
+            emit: clientHandlers.emit,
+            renderUI: clientHandlers.renderUI,
+            navigate: clientHandlers.navigate,
+            notify: clientHandlers.notify
+          };
+        }
         const entityFromPayload = payload ?? {};
         const bindingCtx = {
           entity: entityFromPayload,
@@ -51881,7 +51918,7 @@ function applyServerEffects(effects, uiSlots, onNavigate) {
     }
   }
 }
-function TraitInitializer({ traits: traits2, orbitalNames, onNavigate, onLocalFallback }) {
+function TraitInitializer({ traits: traits2, orbitalNames, onNavigate, onLocalFallback, persistence }) {
   const slotsActions = useSlotsActions();
   const bridge = useServerBridge();
   const uiSlots = useUISlots();
@@ -51893,7 +51930,7 @@ function TraitInitializer({ traits: traits2, orbitalNames, onNavigate, onLocalFa
       applyServerEffects(effects, uiSlots, onNavigate);
     }
   }, [bridge.connected, bridge.sendEvent, orbitalNames, uiSlots, onNavigate]);
-  const opts = orbitalNames ? { onEventProcessed, navigate: onNavigate } : { navigate: onNavigate };
+  const opts = orbitalNames ? { onEventProcessed, navigate: onNavigate } : { navigate: onNavigate, persistence };
   const { sendEvent } = useTraitStateMachine(traits2, slotsActions, opts);
   const initSentRef = React126.useRef(false);
   React126.useEffect(() => {
@@ -51938,7 +51975,7 @@ function TraitInitializer({ traits: traits2, orbitalNames, onNavigate, onLocalFa
   }, [bridge.connected, orbitalNames, bridge.sendEvent, uiSlots, onNavigate]);
   return null;
 }
-function SchemaRunner({ schema, serverUrl, mockData, pageName, onNavigate, onLocalFallback }) {
+function SchemaRunner({ schema, serverUrl, mockData, pageName, onNavigate, onLocalFallback, persistence }) {
   const { traits: traits2, allEntities, ir } = useResolvedSchema(schema, pageName);
   const allPageTraits = React126.useMemo(() => {
     if (pageName && traits2.length > 0) return traits2;
@@ -51971,7 +52008,8 @@ function SchemaRunner({ schema, serverUrl, mockData, pageName, onNavigate, onLoc
         traits: allPageTraits,
         orbitalNames: serverUrl ? orbitalNames : void 0,
         onNavigate,
-        onLocalFallback
+        onLocalFallback,
+        persistence
       }
     ),
     /* @__PURE__ */ jsxRuntime.jsx(SlotBridge, {}),
@@ -52019,6 +52057,13 @@ function OrbPreview({
   }, [schema, autoMock, serverUrl, mockData]);
   const parsedSchema = parseResult.ok ? parseResult.schema : null;
   const effectiveMockData = parseResult.ok ? parseResult.mockData : {};
+  const persistence = React126.useMemo(() => {
+    if (!parsedSchema || serverUrl) return void 0;
+    if (!autoMock) return void 0;
+    const adapter = new runtime.InMemoryPersistence();
+    adapter.seed(effectiveMockData);
+    return adapter;
+  }, [parsedSchema, serverUrl, autoMock, effectiveMockData]);
   const pages = React126.useMemo(() => {
     if (!parsedSchema) return [];
     try {
@@ -52073,7 +52118,8 @@ function OrbPreview({
             mockData: effectiveMockData,
             pageName: currentPage,
             onNavigate: handleNavigate,
-            onLocalFallback: handleLocalFallback
+            onLocalFallback: handleLocalFallback,
+            persistence
           }
         ) }) })
       ]

package/dist/avl/index.js

@@ -43,7 +43,7 @@ import { EffectComposer, Bloom, DepthOfField, Vignette } from '@react-three/post
 import ELK from 'elkjs/lib/elk.bundled.js';
 import { MarkerType, Handle, Position, getBezierPath, EdgeLabelRenderer, BaseEdge, ReactFlowProvider, useNodesState, useEdgesState, useReactFlow, ReactFlow, Controls, Background, BackgroundVariant } from '@xyflow/react';
 import '@tanstack/react-query';
-import { StateMachineManager, createContextFromBindings, interpolateValue, EffectExecutor } from '@almadar/runtime';
+import { InMemoryPersistence, StateMachineManager, createContextFromBindings, interpolateValue, createServerEffectHandlers, EffectExecutor } from '@almadar/runtime';
 
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -51321,7 +51321,7 @@ function useTraitStateMachine(traitBindings, slotsActions, options) {
           effects: result.effects,
           traitDefinition: binding.trait
         };
-        const handlers = createClientEffectHandlers({
+        const clientHandlers = createClientEffectHandlers({
           eventBus,
           slotSetter: {
             addPattern: (slot, pattern, props) => {
@@ -51336,6 +51336,43 @@ function useTraitStateMachine(traitBindings, slotsActions, options) {
           navigate: optionsRef.current?.navigate,
           notify: optionsRef.current?.notify
         });
+        const persistence = optionsRef.current?.persistence;
+        let handlers = clientHandlers;
+        if (persistence) {
+          const sharedBindings = {
+            entity: payload ?? {},
+            payload: payload || {},
+            state: result.previousState
+          };
+          if (binding.config) {
+            sharedBindings.config = binding.config;
+          }
+          const serverHandlers = createServerEffectHandlers({
+            persistence,
+            eventBus,
+            entityType: linkedEntity,
+            entityId,
+            bindings: sharedBindings,
+            context: {
+              traitName: binding.trait.name,
+              state: result.previousState,
+              transition: `${result.previousState}->${result.newState}`,
+              linkedEntity,
+              entityId
+            },
+            source: { trait: binding.trait.name },
+            callService: optionsRef.current?.callService
+          });
+          handlers = {
+            ...serverHandlers,
+            // Client handlers own UI + emit: keep the slot setter
+            // and pre-prefixed UI:* emit path intact.
+            emit: clientHandlers.emit,
+            renderUI: clientHandlers.renderUI,
+            navigate: clientHandlers.navigate,
+            notify: clientHandlers.notify
+          };
+        }
         const entityFromPayload = payload ?? {};
         const bindingCtx = {
           entity: entityFromPayload,
@@ -51835,7 +51872,7 @@ function applyServerEffects(effects, uiSlots, onNavigate) {
     }
   }
 }
-function TraitInitializer({ traits: traits2, orbitalNames, onNavigate, onLocalFallback }) {
+function TraitInitializer({ traits: traits2, orbitalNames, onNavigate, onLocalFallback, persistence }) {
   const slotsActions = useSlotsActions();
   const bridge = useServerBridge();
   const uiSlots = useUISlots();
@@ -51847,7 +51884,7 @@ function TraitInitializer({ traits: traits2, orbitalNames, onNavigate, onLocalFa
       applyServerEffects(effects, uiSlots, onNavigate);
     }
   }, [bridge.connected, bridge.sendEvent, orbitalNames, uiSlots, onNavigate]);
-  const opts = orbitalNames ? { onEventProcessed, navigate: onNavigate } : { navigate: onNavigate };
+  const opts = orbitalNames ? { onEventProcessed, navigate: onNavigate } : { navigate: onNavigate, persistence };
   const { sendEvent } = useTraitStateMachine(traits2, slotsActions, opts);
   const initSentRef = useRef(false);
   useEffect(() => {
@@ -51892,7 +51929,7 @@ function TraitInitializer({ traits: traits2, orbitalNames, onNavigate, onLocalFa
   }, [bridge.connected, orbitalNames, bridge.sendEvent, uiSlots, onNavigate]);
   return null;
 }
-function SchemaRunner({ schema, serverUrl, mockData, pageName, onNavigate, onLocalFallback }) {
+function SchemaRunner({ schema, serverUrl, mockData, pageName, onNavigate, onLocalFallback, persistence }) {
   const { traits: traits2, allEntities, ir } = useResolvedSchema(schema, pageName);
   const allPageTraits = useMemo(() => {
     if (pageName && traits2.length > 0) return traits2;
@@ -51925,7 +51962,8 @@ function SchemaRunner({ schema, serverUrl, mockData, pageName, onNavigate, onLoc
         traits: allPageTraits,
         orbitalNames: serverUrl ? orbitalNames : void 0,
         onNavigate,
-        onLocalFallback
+        onLocalFallback,
+        persistence
       }
     ),
     /* @__PURE__ */ jsx(SlotBridge, {}),
@@ -51973,6 +52011,13 @@ function OrbPreview({
   }, [schema, autoMock, serverUrl, mockData]);
   const parsedSchema = parseResult.ok ? parseResult.schema : null;
   const effectiveMockData = parseResult.ok ? parseResult.mockData : {};
+  const persistence = useMemo(() => {
+    if (!parsedSchema || serverUrl) return void 0;
+    if (!autoMock) return void 0;
+    const adapter = new InMemoryPersistence();
+    adapter.seed(effectiveMockData);
+    return adapter;
+  }, [parsedSchema, serverUrl, autoMock, effectiveMockData]);
   const pages = useMemo(() => {
     if (!parsedSchema) return [];
     try {
@@ -52027,7 +52072,8 @@ function OrbPreview({
             mockData: effectiveMockData,
             pageName: currentPage,
             onNavigate: handleNavigate,
-            onLocalFallback: handleLocalFallback
+            onLocalFallback: handleLocalFallback,
+            persistence
           }
         ) }) })
       ]

package/dist/runtime/index.cjs

@@ -38163,7 +38163,7 @@ function useTraitStateMachine(traitBindings, slotsActions, options) {
           effects: result.effects,
           traitDefinition: binding.trait
         };
-        const handlers = createClientEffectHandlers({
+        const clientHandlers = createClientEffectHandlers({
           eventBus,
           slotSetter: {
             addPattern: (slot, pattern, props) => {
@@ -38178,6 +38178,43 @@ function useTraitStateMachine(traitBindings, slotsActions, options) {
           navigate: optionsRef.current?.navigate,
           notify: optionsRef.current?.notify
         });
+        const persistence = optionsRef.current?.persistence;
+        let handlers = clientHandlers;
+        if (persistence) {
+          const sharedBindings = {
+            entity: payload ?? {},
+            payload: payload || {},
+            state: result.previousState
+          };
+          if (binding.config) {
+            sharedBindings.config = binding.config;
+          }
+          const serverHandlers = runtime.createServerEffectHandlers({
+            persistence,
+            eventBus,
+            entityType: linkedEntity,
+            entityId,
+            bindings: sharedBindings,
+            context: {
+              traitName: binding.trait.name,
+              state: result.previousState,
+              transition: `${result.previousState}->${result.newState}`,
+              linkedEntity,
+              entityId
+            },
+            source: { trait: binding.trait.name },
+            callService: optionsRef.current?.callService
+          });
+          handlers = {
+            ...serverHandlers,
+            // Client handlers own UI + emit: keep the slot setter
+            // and pre-prefixed UI:* emit path intact.
+            emit: clientHandlers.emit,
+            renderUI: clientHandlers.renderUI,
+            navigate: clientHandlers.navigate,
+            notify: clientHandlers.notify
+          };
+        }
         const entityFromPayload = payload ?? {};
         const bindingCtx = {
           entity: entityFromPayload,
@@ -38799,7 +38836,7 @@ function applyServerEffects(effects, uiSlots, onNavigate) {
     }
   }
 }
-function TraitInitializer({ traits: traits2, orbitalNames, onNavigate, onLocalFallback }) {
+function TraitInitializer({ traits: traits2, orbitalNames, onNavigate, onLocalFallback, persistence }) {
   const slotsActions = useSlotsActions();
   const bridge = useServerBridge();
   const uiSlots = context.useUISlots();
@@ -38811,7 +38848,7 @@ function TraitInitializer({ traits: traits2, orbitalNames, onNavigate, onLocalFa
       applyServerEffects(effects, uiSlots, onNavigate);
     }
   }, [bridge.connected, bridge.sendEvent, orbitalNames, uiSlots, onNavigate]);
-  const opts = orbitalNames ? { onEventProcessed, navigate: onNavigate } : { navigate: onNavigate };
+  const opts = orbitalNames ? { onEventProcessed, navigate: onNavigate } : { navigate: onNavigate, persistence };
   const { sendEvent } = useTraitStateMachine(traits2, slotsActions, opts);
   const initSentRef = React116.useRef(false);
   React116.useEffect(() => {
@@ -38856,7 +38893,7 @@ function TraitInitializer({ traits: traits2, orbitalNames, onNavigate, onLocalFa
   }, [bridge.connected, orbitalNames, bridge.sendEvent, uiSlots, onNavigate]);
   return null;
 }
-function SchemaRunner({ schema, serverUrl, mockData, pageName, onNavigate, onLocalFallback }) {
+function SchemaRunner({ schema, serverUrl, mockData, pageName, onNavigate, onLocalFallback, persistence }) {
   const { traits: traits2, allEntities, ir } = useResolvedSchema(schema, pageName);
   const allPageTraits = React116.useMemo(() => {
     if (pageName && traits2.length > 0) return traits2;
@@ -38889,7 +38926,8 @@ function SchemaRunner({ schema, serverUrl, mockData, pageName, onNavigate, onLoc
         traits: allPageTraits,
         orbitalNames: serverUrl ? orbitalNames : void 0,
         onNavigate,
-        onLocalFallback
+        onLocalFallback,
+        persistence
       }
     ),
     /* @__PURE__ */ jsxRuntime.jsx(SlotBridge, {}),
@@ -38937,6 +38975,13 @@ function OrbPreview({
   }, [schema, autoMock, serverUrl, mockData]);
   const parsedSchema = parseResult.ok ? parseResult.schema : null;
   const effectiveMockData = parseResult.ok ? parseResult.mockData : {};
+  const persistence = React116.useMemo(() => {
+    if (!parsedSchema || serverUrl) return void 0;
+    if (!autoMock) return void 0;
+    const adapter = new runtime.InMemoryPersistence();
+    adapter.seed(effectiveMockData);
+    return adapter;
+  }, [parsedSchema, serverUrl, autoMock, effectiveMockData]);
   const pages = React116.useMemo(() => {
     if (!parsedSchema) return [];
     try {
@@ -38991,7 +39036,8 @@ function OrbPreview({
             mockData: effectiveMockData,
             pageName: currentPage,
             onNavigate: handleNavigate,
-            onLocalFallback: handleLocalFallback
+            onLocalFallback: handleLocalFallback,
+            persistence
           }
         ) }) })
       ]

package/dist/runtime/index.js

@@ -36,7 +36,7 @@ import langGo from 'react-syntax-highlighter/dist/esm/languages/prism/go.js';
 import langGraphql from 'react-syntax-highlighter/dist/esm/languages/prism/graphql.js';
 import { isCircuitEvent, schemaToIR, getPage, clearSchemaCache as clearSchemaCache$1, isEntityCall, isInlineTrait } from '@almadar/core';
 import '@tanstack/react-query';
-import { StateMachineManager, createContextFromBindings, interpolateValue, EffectExecutor } from '@almadar/runtime';
+import { StateMachineManager, createContextFromBindings, interpolateValue, createServerEffectHandlers, EffectExecutor, InMemoryPersistence } from '@almadar/runtime';
 
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -38118,7 +38118,7 @@ function useTraitStateMachine(traitBindings, slotsActions, options) {
           effects: result.effects,
           traitDefinition: binding.trait
         };
-        const handlers = createClientEffectHandlers({
+        const clientHandlers = createClientEffectHandlers({
           eventBus,
           slotSetter: {
             addPattern: (slot, pattern, props) => {
@@ -38133,6 +38133,43 @@ function useTraitStateMachine(traitBindings, slotsActions, options) {
           navigate: optionsRef.current?.navigate,
           notify: optionsRef.current?.notify
         });
+        const persistence = optionsRef.current?.persistence;
+        let handlers = clientHandlers;
+        if (persistence) {
+          const sharedBindings = {
+            entity: payload ?? {},
+            payload: payload || {},
+            state: result.previousState
+          };
+          if (binding.config) {
+            sharedBindings.config = binding.config;
+          }
+          const serverHandlers = createServerEffectHandlers({
+            persistence,
+            eventBus,
+            entityType: linkedEntity,
+            entityId,
+            bindings: sharedBindings,
+            context: {
+              traitName: binding.trait.name,
+              state: result.previousState,
+              transition: `${result.previousState}->${result.newState}`,
+              linkedEntity,
+              entityId
+            },
+            source: { trait: binding.trait.name },
+            callService: optionsRef.current?.callService
+          });
+          handlers = {
+            ...serverHandlers,
+            // Client handlers own UI + emit: keep the slot setter
+            // and pre-prefixed UI:* emit path intact.
+            emit: clientHandlers.emit,
+            renderUI: clientHandlers.renderUI,
+            navigate: clientHandlers.navigate,
+            notify: clientHandlers.notify
+          };
+        }
         const entityFromPayload = payload ?? {};
         const bindingCtx = {
           entity: entityFromPayload,
@@ -38754,7 +38791,7 @@ function applyServerEffects(effects, uiSlots, onNavigate) {
     }
   }
 }
-function TraitInitializer({ traits: traits2, orbitalNames, onNavigate, onLocalFallback }) {
+function TraitInitializer({ traits: traits2, orbitalNames, onNavigate, onLocalFallback, persistence }) {
   const slotsActions = useSlotsActions();
   const bridge = useServerBridge();
   const uiSlots = useUISlots();
@@ -38766,7 +38803,7 @@ function TraitInitializer({ traits: traits2, orbitalNames, onNavigate, onLocalFa
       applyServerEffects(effects, uiSlots, onNavigate);
     }
   }, [bridge.connected, bridge.sendEvent, orbitalNames, uiSlots, onNavigate]);
-  const opts = orbitalNames ? { onEventProcessed, navigate: onNavigate } : { navigate: onNavigate };
+  const opts = orbitalNames ? { onEventProcessed, navigate: onNavigate } : { navigate: onNavigate, persistence };
   const { sendEvent } = useTraitStateMachine(traits2, slotsActions, opts);
   const initSentRef = useRef(false);
   useEffect(() => {
@@ -38811,7 +38848,7 @@ function TraitInitializer({ traits: traits2, orbitalNames, onNavigate, onLocalFa
   }, [bridge.connected, orbitalNames, bridge.sendEvent, uiSlots, onNavigate]);
   return null;
 }
-function SchemaRunner({ schema, serverUrl, mockData, pageName, onNavigate, onLocalFallback }) {
+function SchemaRunner({ schema, serverUrl, mockData, pageName, onNavigate, onLocalFallback, persistence }) {
   const { traits: traits2, allEntities, ir } = useResolvedSchema(schema, pageName);
   const allPageTraits = useMemo(() => {
     if (pageName && traits2.length > 0) return traits2;
@@ -38844,7 +38881,8 @@ function SchemaRunner({ schema, serverUrl, mockData, pageName, onNavigate, onLoc
         traits: allPageTraits,
         orbitalNames: serverUrl ? orbitalNames : void 0,
         onNavigate,
-        onLocalFallback
+        onLocalFallback,
+        persistence
       }
     ),
     /* @__PURE__ */ jsx(SlotBridge, {}),
@@ -38892,6 +38930,13 @@ function OrbPreview({
   }, [schema, autoMock, serverUrl, mockData]);
   const parsedSchema = parseResult.ok ? parseResult.schema : null;
   const effectiveMockData = parseResult.ok ? parseResult.mockData : {};
+  const persistence = useMemo(() => {
+    if (!parsedSchema || serverUrl) return void 0;
+    if (!autoMock) return void 0;
+    const adapter = new InMemoryPersistence();
+    adapter.seed(effectiveMockData);
+    return adapter;
+  }, [parsedSchema, serverUrl, autoMock, effectiveMockData]);
   const pages = useMemo(() => {
     if (!parsedSchema) return [];
     try {
@@ -38946,7 +38991,8 @@ function OrbPreview({
             mockData: effectiveMockData,
             pageName: currentPage,
             onNavigate: handleNavigate,
-            onLocalFallback: handleLocalFallback
+            onLocalFallback: handleLocalFallback,
+            persistence
           }
         ) }) })
       ]

package/dist/runtime/useTraitStateMachine.d.ts

@@ -38,6 +38,17 @@ export interface UseTraitStateMachineOptions {
     navigate?: (path: string, params?: Record<string, unknown>) => void;
     /** Notification function for notify effects */
     notify?: (message: string, type?: 'success' | 'error' | 'warning' | 'info') => void;
+    /**
+     * Offline-preview persistence layer. When set, the client runtime merges
+     * `@almadar/runtime` `createServerEffectHandlers` on top of the default
+     * client handlers so `fetch` / `persist` / `set` / `ref` / `deref` /
+     * `swap!` / `atomic` / `callService` run against this adapter — matching
+     * what `OrbitalServerRuntime` would do on the server. Left unset in the
+     * server-bridge path; effects there flow to the real server.
+     */
+    persistence?: import('@almadar/runtime').PersistenceAdapter;
+    /** Optional consumer `call-service` hook forwarded to the mock server handlers. */
+    callService?: (service: string, action: string, params: unknown) => Promise<unknown>;
 }
 /**
  * useTraitStateMachine - Manages state machines for multiple traits

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/ui",
-  "version": "3.8.3",
+  "version": "3.9.0",
   "description": "React UI components, hooks, and providers for Almadar",
   "type": "module",
   "main": "./dist/components/index.js",
@@ -121,7 +121,7 @@
     "@almadar/core": ">=5.7.0",
     "@almadar/evaluator": ">=2.9.2",
     "@almadar/patterns": ">=2.17.1",
-    "@almadar/runtime": ">=4.3.0",
+    "@almadar/runtime": "^4.11.1",
     "@almadar/std": ">=6.4.1",
     "@almadar/syntax": ">=1.3.1",
     "@xyflow/react": "12.10.1",