@almadar/ui 5.51.0 → 5.52.0

package/dist/avl/index.cjs

@@ -57351,7 +57351,7 @@ function convertFnFormLambdasInProps(props) {
 }
 var log10 = logger.createLogger("almadar:ui:effects:client-handlers");
 function createClientEffectHandlers(options) {
-  const { eventBus, slotSetter, navigate, notify, callService } = options;
+  const { eventBus, slotSetter, navigate, notify, callService, liveEntity } = options;
   return {
     emit: (event, payload) => {
       const prefixedEvent = event.startsWith("UI:") ? event : `UI:${event}`;
@@ -57360,8 +57360,12 @@ function createClientEffectHandlers(options) {
     persist: async () => {
       log10.warn("persist is server-side only, ignored on client");
     },
-    set: () => {
-      log10.warn("set is server-side only, ignored on client");
+    set: (_entityId, field, value) => {
+      if (!liveEntity) {
+        log10.warn("set is server-side only, ignored on client (no live entity)");
+        return;
+      }
+      liveEntity[field] = value;
     },
     callService: async (service, action, params) => {
       if (callService) return callService(service, action, params);
@@ -57629,6 +57633,11 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
     const traitName = binding.trait.name;
     const linkedEntity = binding.linkedEntity || "";
     const entityId = payload?.entityId;
+    let liveEntity = traitFieldStatesRef.current.get(traitName);
+    if (!liveEntity) {
+      liveEntity = {};
+      traitFieldStatesRef.current.set(traitName, liveEntity);
+    }
     const effects = syncOnly ? params.effects.filter(
       (e) => Array.isArray(e) && SYNC_TICK_OPERATORS.has(String(e[0]))
     ) : params.effects;
@@ -57651,7 +57660,12 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
       },
       navigate: optionsRef.current?.navigate,
       notify: optionsRef.current?.notify,
-      callService: optionsRef.current?.callService
+      callService: optionsRef.current?.callService,
+      // The canonical client `set` writes `(set @entity.X)` straight into
+      // the trait's one live store — the same object bound below. This is
+      // what makes a [runtime] entity's set (from ticks AND events) reach
+      // the render-ui + next tick + guards.
+      liveEntity
     });
     const persistence = syncOnly ? void 0 : optionsRef.current?.persistence;
     let handlers = clientHandlers;
@@ -57662,7 +57676,7 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
         // uses below. `@payload.*` resolves from `payload` separately,
         // so dropping the prior `payload as EntityRow` cast loses
         // nothing — it just stops mislabelling the payload as an entity.
-        entity: traitFieldStatesRef.current.get(traitName) ?? {},
+        entity: liveEntity,
         payload: payload || {},
         state: previousState
       };
@@ -57702,24 +57716,17 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
     handlers = {
       ...handlers,
       set: async (targetId, field, value) => {
-        let fieldState = traitFieldStatesRef.current.get(traitName);
-        if (!fieldState) {
-          fieldState = {};
-          traitFieldStatesRef.current.set(traitName, fieldState);
-        }
-        fieldState[field] = value;
+        if (baseSet) await baseSet(targetId, field, value);
         log15.debug("set:write", {
           traitName,
           field,
           value: JSON.stringify(value),
           transition: `${previousState}->${newState}`
         });
-        if (baseSet) await baseSet(targetId, field, value);
       }
     };
-    const entityForBinding = traitFieldStatesRef.current.get(traitName) ?? {};
     const bindingCtx = {
-      entity: entityForBinding,
+      entity: liveEntity,
       payload: payload || {},
       state: previousState
     };

package/dist/avl/index.js

@@ -57304,7 +57304,7 @@ function convertFnFormLambdasInProps(props) {
 }
 var log10 = createLogger("almadar:ui:effects:client-handlers");
 function createClientEffectHandlers(options) {
-  const { eventBus, slotSetter, navigate, notify, callService } = options;
+  const { eventBus, slotSetter, navigate, notify, callService, liveEntity } = options;
   return {
     emit: (event, payload) => {
       const prefixedEvent = event.startsWith("UI:") ? event : `UI:${event}`;
@@ -57313,8 +57313,12 @@ function createClientEffectHandlers(options) {
     persist: async () => {
       log10.warn("persist is server-side only, ignored on client");
     },
-    set: () => {
-      log10.warn("set is server-side only, ignored on client");
+    set: (_entityId, field, value) => {
+      if (!liveEntity) {
+        log10.warn("set is server-side only, ignored on client (no live entity)");
+        return;
+      }
+      liveEntity[field] = value;
     },
     callService: async (service, action, params) => {
       if (callService) return callService(service, action, params);
@@ -57582,6 +57586,11 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
     const traitName = binding.trait.name;
     const linkedEntity = binding.linkedEntity || "";
     const entityId = payload?.entityId;
+    let liveEntity = traitFieldStatesRef.current.get(traitName);
+    if (!liveEntity) {
+      liveEntity = {};
+      traitFieldStatesRef.current.set(traitName, liveEntity);
+    }
     const effects = syncOnly ? params.effects.filter(
       (e) => Array.isArray(e) && SYNC_TICK_OPERATORS.has(String(e[0]))
     ) : params.effects;
@@ -57604,7 +57613,12 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
       },
       navigate: optionsRef.current?.navigate,
       notify: optionsRef.current?.notify,
-      callService: optionsRef.current?.callService
+      callService: optionsRef.current?.callService,
+      // The canonical client `set` writes `(set @entity.X)` straight into
+      // the trait's one live store — the same object bound below. This is
+      // what makes a [runtime] entity's set (from ticks AND events) reach
+      // the render-ui + next tick + guards.
+      liveEntity
     });
     const persistence = syncOnly ? void 0 : optionsRef.current?.persistence;
     let handlers = clientHandlers;
@@ -57615,7 +57629,7 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
         // uses below. `@payload.*` resolves from `payload` separately,
         // so dropping the prior `payload as EntityRow` cast loses
         // nothing — it just stops mislabelling the payload as an entity.
-        entity: traitFieldStatesRef.current.get(traitName) ?? {},
+        entity: liveEntity,
         payload: payload || {},
         state: previousState
       };
@@ -57655,24 +57669,17 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
     handlers = {
       ...handlers,
       set: async (targetId, field, value) => {
-        let fieldState = traitFieldStatesRef.current.get(traitName);
-        if (!fieldState) {
-          fieldState = {};
-          traitFieldStatesRef.current.set(traitName, fieldState);
-        }
-        fieldState[field] = value;
+        if (baseSet) await baseSet(targetId, field, value);
         log15.debug("set:write", {
           traitName,
           field,
           value: JSON.stringify(value),
           transition: `${previousState}->${newState}`
         });
-        if (baseSet) await baseSet(targetId, field, value);
       }
     };
-    const entityForBinding = traitFieldStatesRef.current.get(traitName) ?? {};
     const bindingCtx = {
-      entity: entityForBinding,
+      entity: liveEntity,
       payload: payload || {},
       state: previousState
     };

package/dist/runtime/createClientEffectHandlers.d.ts

@@ -5,7 +5,7 @@
  *
  * @packageDocumentation
  */
-import type { EventPayload, ServiceParams } from '@almadar/core';
+import type { EventPayload, EntityRow, ServiceParams } from '@almadar/core';
 import type { EffectHandlers } from '@almadar/runtime';
 export interface ClientEventBus {
     emit: (type: string, payload?: EventPayload) => void;
@@ -19,6 +19,17 @@ export interface CreateClientEffectHandlersOptions {
     slotSetter: SlotSetter;
     navigate?: (path: string, params?: Record<string, unknown>) => void;
     notify?: (message: string, type: 'success' | 'error' | 'warning' | 'info') => void;
+    /**
+     * Live client-entity write target for `[runtime]` entities. `(set
+     * @entity.<field> value)` runs entirely in the browser for in-memory
+     * entities (game boards, wizards): there is no server row to persist to,
+     * so the canonical client `set` must mutate THIS object — the same object
+     * `EffectExecutor` reads `@entity.*` from for the current `executeAll` and
+     * the next tick seeds from. When omitted, `set` is a no-op (bridge mode:
+     * the server owns persistence). One store, read live by render-ui, guards,
+     * and ticks — no guard-vs-render split.
+     */
+    liveEntity?: EntityRow;
     /**
      * Optional consumer-supplied call-service handler. When set, it runs
      * instead of the default mock fallback — use to wire the playground

package/dist/runtime/index.cjs

@@ -51279,7 +51279,7 @@ var init_UISlotRenderer = __esm({
 });
 var log = logger.createLogger("almadar:ui:effects:client-handlers");
 function createClientEffectHandlers(options) {
-  const { eventBus, slotSetter, navigate, notify, callService } = options;
+  const { eventBus, slotSetter, navigate, notify, callService, liveEntity } = options;
   return {
     emit: (event, payload) => {
       const prefixedEvent = event.startsWith("UI:") ? event : `UI:${event}`;
@@ -51288,8 +51288,12 @@ function createClientEffectHandlers(options) {
     persist: async () => {
       log.warn("persist is server-side only, ignored on client");
     },
-    set: () => {
-      log.warn("set is server-side only, ignored on client");
+    set: (_entityId, field, value) => {
+      if (!liveEntity) {
+        log.warn("set is server-side only, ignored on client (no live entity)");
+        return;
+      }
+      liveEntity[field] = value;
     },
     callService: async (service, action, params) => {
       if (callService) return callService(service, action, params);
@@ -51683,6 +51687,11 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
     const traitName = binding.trait.name;
     const linkedEntity = binding.linkedEntity || "";
     const entityId = payload?.entityId;
+    let liveEntity = traitFieldStatesRef.current.get(traitName);
+    if (!liveEntity) {
+      liveEntity = {};
+      traitFieldStatesRef.current.set(traitName, liveEntity);
+    }
     const effects = syncOnly ? params.effects.filter(
       (e) => Array.isArray(e) && SYNC_TICK_OPERATORS.has(String(e[0]))
     ) : params.effects;
@@ -51705,7 +51714,12 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
       },
       navigate: optionsRef.current?.navigate,
       notify: optionsRef.current?.notify,
-      callService: optionsRef.current?.callService
+      callService: optionsRef.current?.callService,
+      // The canonical client `set` writes `(set @entity.X)` straight into
+      // the trait's one live store — the same object bound below. This is
+      // what makes a [runtime] entity's set (from ticks AND events) reach
+      // the render-ui + next tick + guards.
+      liveEntity
     });
     const persistence = syncOnly ? void 0 : optionsRef.current?.persistence;
     let handlers = clientHandlers;
@@ -51716,7 +51730,7 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
         // uses below. `@payload.*` resolves from `payload` separately,
         // so dropping the prior `payload as EntityRow` cast loses
         // nothing — it just stops mislabelling the payload as an entity.
-        entity: traitFieldStatesRef.current.get(traitName) ?? {},
+        entity: liveEntity,
         payload: payload || {},
         state: previousState
       };
@@ -51756,24 +51770,17 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
     handlers = {
       ...handlers,
       set: async (targetId, field, value) => {
-        let fieldState = traitFieldStatesRef.current.get(traitName);
-        if (!fieldState) {
-          fieldState = {};
-          traitFieldStatesRef.current.set(traitName, fieldState);
-        }
-        fieldState[field] = value;
+        if (baseSet) await baseSet(targetId, field, value);
         log14.debug("set:write", {
           traitName,
           field,
           value: JSON.stringify(value),
           transition: `${previousState}->${newState}`
         });
-        if (baseSet) await baseSet(targetId, field, value);
       }
     };
-    const entityForBinding = traitFieldStatesRef.current.get(traitName) ?? {};
     const bindingCtx = {
-      entity: entityForBinding,
+      entity: liveEntity,
       payload: payload || {},
       state: previousState
     };

package/dist/runtime/index.js

@@ -51232,7 +51232,7 @@ var init_UISlotRenderer = __esm({
 });
 var log = createLogger("almadar:ui:effects:client-handlers");
 function createClientEffectHandlers(options) {
-  const { eventBus, slotSetter, navigate, notify, callService } = options;
+  const { eventBus, slotSetter, navigate, notify, callService, liveEntity } = options;
   return {
     emit: (event, payload) => {
       const prefixedEvent = event.startsWith("UI:") ? event : `UI:${event}`;
@@ -51241,8 +51241,12 @@ function createClientEffectHandlers(options) {
     persist: async () => {
       log.warn("persist is server-side only, ignored on client");
     },
-    set: () => {
-      log.warn("set is server-side only, ignored on client");
+    set: (_entityId, field, value) => {
+      if (!liveEntity) {
+        log.warn("set is server-side only, ignored on client (no live entity)");
+        return;
+      }
+      liveEntity[field] = value;
     },
     callService: async (service, action, params) => {
       if (callService) return callService(service, action, params);
@@ -51636,6 +51640,11 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
     const traitName = binding.trait.name;
     const linkedEntity = binding.linkedEntity || "";
     const entityId = payload?.entityId;
+    let liveEntity = traitFieldStatesRef.current.get(traitName);
+    if (!liveEntity) {
+      liveEntity = {};
+      traitFieldStatesRef.current.set(traitName, liveEntity);
+    }
     const effects = syncOnly ? params.effects.filter(
       (e) => Array.isArray(e) && SYNC_TICK_OPERATORS.has(String(e[0]))
     ) : params.effects;
@@ -51658,7 +51667,12 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
       },
       navigate: optionsRef.current?.navigate,
       notify: optionsRef.current?.notify,
-      callService: optionsRef.current?.callService
+      callService: optionsRef.current?.callService,
+      // The canonical client `set` writes `(set @entity.X)` straight into
+      // the trait's one live store — the same object bound below. This is
+      // what makes a [runtime] entity's set (from ticks AND events) reach
+      // the render-ui + next tick + guards.
+      liveEntity
     });
     const persistence = syncOnly ? void 0 : optionsRef.current?.persistence;
     let handlers = clientHandlers;
@@ -51669,7 +51683,7 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
         // uses below. `@payload.*` resolves from `payload` separately,
         // so dropping the prior `payload as EntityRow` cast loses
         // nothing — it just stops mislabelling the payload as an entity.
-        entity: traitFieldStatesRef.current.get(traitName) ?? {},
+        entity: liveEntity,
         payload: payload || {},
         state: previousState
       };
@@ -51709,24 +51723,17 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
     handlers = {
       ...handlers,
       set: async (targetId, field, value) => {
-        let fieldState = traitFieldStatesRef.current.get(traitName);
-        if (!fieldState) {
-          fieldState = {};
-          traitFieldStatesRef.current.set(traitName, fieldState);
-        }
-        fieldState[field] = value;
+        if (baseSet) await baseSet(targetId, field, value);
         log14.debug("set:write", {
           traitName,
           field,
           value: JSON.stringify(value),
           transition: `${previousState}->${newState}`
         });
-        if (baseSet) await baseSet(targetId, field, value);
       }
     };
-    const entityForBinding = traitFieldStatesRef.current.get(traitName) ?? {};
     const bindingCtx = {
-      entity: entityForBinding,
+      entity: liveEntity,
       payload: payload || {},
       state: previousState
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/ui",
-  "version": "5.51.0",
+  "version": "5.52.0",
   "description": "React UI components, hooks, and providers for Almadar",
   "type": "module",
   "sideEffects": [