@almadar/ui 4.15.4 → 4.15.5

package/dist/avl/index.cjs

@@ -4348,6 +4348,13 @@ function useUISlotManager() {
           indexTraitRender(content.sourceTrait, content);
           notifyTraitSubscribers(content.sourceTrait, content);
         }
+        slotLog.info("slot:written", {
+          slot: config.target,
+          sourceKey,
+          sourceTrait: content.sourceTrait,
+          patternType: content.pattern,
+          priority: content.priority
+        });
         notifySubscribers(config.target, aggregateSlot(nextSources));
         return nextAll;
       });
@@ -4385,7 +4392,10 @@ function useUISlotManager() {
       const sourceKey = sourceTrait;
       setSources((prev) => {
         const slotSources = prev[slot];
-        if (!slotSources || !(sourceKey in slotSources)) return prev;
+        if (!slotSources || !(sourceKey in slotSources)) {
+          slotLog.debug("slot:clear-noop", { slot, sourceTrait, reason: !slotSources ? "no-slot" : "no-source" });
+          return prev;
+        }
         const content = slotSources[sourceKey];
         const timer = timersRef.current.get(content.id);
         if (timer) {
@@ -4399,6 +4409,7 @@ function useUISlotManager() {
         }
         const nextSources = { ...slotSources };
         delete nextSources[sourceKey];
+        slotLog.info("slot:cleared", { slot, sourceTrait, lastPatternType: content.pattern });
         notifySubscribers(slot, aggregateSlot(nextSources));
         return { ...prev, [slot]: nextSources };
       });
@@ -4517,10 +4528,12 @@ function useUISlotManager() {
     updateTraitContent
   };
 }
-var DEFAULT_SOURCE_KEY, MULTI_SOURCE_STACK_TRAIT, ALL_SLOTS, DEFAULT_SLOTS, DEFAULT_SOURCES, idCounter;
+var slotLog, DEFAULT_SOURCE_KEY, MULTI_SOURCE_STACK_TRAIT, ALL_SLOTS, DEFAULT_SLOTS, DEFAULT_SOURCES, idCounter;
 var init_useUISlots = __esm({
   "hooks/useUISlots.ts"() {
     "use client";
+    init_logger();
+    slotLog = createLogger("almadar:ui:useUISlots");
     DEFAULT_SOURCE_KEY = "__default__";
     MULTI_SOURCE_STACK_TRAIT = "__multi_source_stack__";
     ALL_SLOTS = [
@@ -5426,11 +5439,11 @@ function refId(obj) {
   refIds.set(obj, id);
   return id;
 }
-var slotLog, refIds, nextRefId;
+var slotLog2, refIds, nextRefId;
 var init_slot_types = __esm({
   "runtime/ui/slot-types.ts"() {
     init_logger();
-    slotLog = createLogger("almadar:ui:slot-render");
+    slotLog2 = createLogger("almadar:ui:slot-render");
     refIds = /* @__PURE__ */ new WeakMap();
     nextRefId = 1;
   }
@@ -47008,7 +47021,7 @@ function SlotContentRenderer({
 }) {
   const entityProp = content.props.entity;
   if (content.pattern === "form-section") {
-    slotLog.debug("SlotContentRenderer:form-section-render", {
+    slotLog2.debug("SlotContentRenderer:form-section-render", {
       contentId: content.id,
       sourceTrait: content.sourceTrait,
       entityRefId: refId(entityProp),
@@ -51757,6 +51770,7 @@ init_traitRegistry();
 init_verificationRegistry();
 var crossTraitLog = createLogger("almadar:ui:cross-trait");
 var flushLog = createLogger("almadar:ui:slot-flush");
+var stateLog = createLogger("almadar:ui:state-transitions");
 function toTraitDefinition(binding) {
   return {
     name: binding.trait.name,
@@ -52189,21 +52203,29 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
         const executor = new runtime.EffectExecutor({ handlers: trackingHandlers, bindings: bindingCtx, context: effectContext });
         try {
           await executor.executeAll(result.effects);
-          console.log(
-            "[TraitStateMachine] After executeAll, pendingSlots:",
-            Object.fromEntries(pendingSlots.entries())
-          );
+          stateLog.info("transition:render-ui-dispatched", {
+            traitName,
+            fromState: result.previousState,
+            toState: result.newState,
+            event: eventKey,
+            slotsTouched: Array.from(pendingSlots.keys()).join(","),
+            patternTypes: Array.from(pendingSlots.entries()).map(
+              ([slot, patterns]) => `${slot}:[${patterns.map((p2) => p2.pattern?.type ?? "null").join(",")}]`
+            ).join(";")
+          });
           void slotSource;
           for (const [slot, patterns] of pendingSlots) {
             flushSlot(traitName, slot, patterns);
           }
         } catch (error) {
-          console.error(
-            "[TraitStateMachine] Effect execution error:",
-            error,
-            "| effects:",
-            JSON.stringify(result.effects)
-          );
+          stateLog.error("transition:effect-error", {
+            traitName,
+            fromState: result.previousState,
+            toState: result.newState,
+            event: eventKey,
+            error: error instanceof Error ? error.message : String(error),
+            effectCount: result.effects.length
+          });
         }
       } else if (!result.executed) {
         if (result.guardResult === false) {
@@ -52349,13 +52371,20 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
         if (eventKey === "INIT" || eventKey === "LOAD" || eventKey === "$MOUNT") {
           continue;
         }
-        const unsub = eventBus.on(`UI:${orbitalName}.${traitName}.${eventKey}`, (event) => {
+        const selfBusKey = `UI:${orbitalName}.${traitName}.${eventKey}`;
+        crossTraitLog.debug("self:subscribe", { traitName, busKey: selfBusKey, eventKey });
+        const unsub = eventBus.on(selfBusKey, (event) => {
           if (event.source && event.source.fromBridge) {
+            crossTraitLog.debug("self:fire-skipped-bridge-echo", { traitName, busKey: selfBusKey, eventKey });
             return;
           }
+          crossTraitLog.info("self:fire", { traitName, busKey: selfBusKey, eventKey });
           enqueueAndDrain(eventKey, event.payload);
         });
-        unsubscribes.push(unsub);
+        unsubscribes.push(() => {
+          crossTraitLog.debug("self:unsubscribe", { traitName, busKey: selfBusKey, eventKey });
+          unsub();
+        });
       }
     }
     for (const binding of traitBindings) {
@@ -52373,18 +52402,23 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
         const sourceOrbital = listen.source?.orbital ?? ownOrbital;
         if (!sourceOrbital) continue;
         const busKey = `UI:${sourceOrbital}.${sourceTrait}.${listen.event}`;
-        crossTraitLog.debug("listen:subscribed", { busKey, targetTrait: binding.trait.name, triggers: listen.triggers });
+        crossTraitLog.debug("listen:subscribed", { busKey, targetTrait: binding.trait.name, sourceOrbital, sourceTrait, listenEvent: listen.event, triggers: listen.triggers });
         const unsub = eventBus.on(busKey, (event) => {
           crossTraitLog.info("listen:fired", { busKey, targetTrait: binding.trait.name, triggers: listen.triggers });
           enqueueAndDrain(listen.triggers, event.payload);
         });
-        unsubscribes.push(unsub);
+        unsubscribes.push(() => {
+          crossTraitLog.debug("listen:unsubscribe", { busKey, targetTrait: binding.trait.name, triggers: listen.triggers });
+          unsub();
+        });
       }
     }
     return () => {
+      crossTraitLog.debug("cleanup:start", { unsubscribeCount: unsubscribes.length });
       for (const unsub of unsubscribes) {
         unsub();
       }
+      crossTraitLog.debug("cleanup:done", {});
     };
   }, [traitBindings, eventBus, enqueueAndDrain]);
   return {

package/dist/avl/index.js

@@ -4302,6 +4302,13 @@ function useUISlotManager() {
           indexTraitRender(content.sourceTrait, content);
           notifyTraitSubscribers(content.sourceTrait, content);
         }
+        slotLog.info("slot:written", {
+          slot: config.target,
+          sourceKey,
+          sourceTrait: content.sourceTrait,
+          patternType: content.pattern,
+          priority: content.priority
+        });
         notifySubscribers(config.target, aggregateSlot(nextSources));
         return nextAll;
       });
@@ -4339,7 +4346,10 @@ function useUISlotManager() {
       const sourceKey = sourceTrait;
       setSources((prev) => {
         const slotSources = prev[slot];
-        if (!slotSources || !(sourceKey in slotSources)) return prev;
+        if (!slotSources || !(sourceKey in slotSources)) {
+          slotLog.debug("slot:clear-noop", { slot, sourceTrait, reason: !slotSources ? "no-slot" : "no-source" });
+          return prev;
+        }
         const content = slotSources[sourceKey];
         const timer = timersRef.current.get(content.id);
         if (timer) {
@@ -4353,6 +4363,7 @@ function useUISlotManager() {
         }
         const nextSources = { ...slotSources };
         delete nextSources[sourceKey];
+        slotLog.info("slot:cleared", { slot, sourceTrait, lastPatternType: content.pattern });
         notifySubscribers(slot, aggregateSlot(nextSources));
         return { ...prev, [slot]: nextSources };
       });
@@ -4471,10 +4482,12 @@ function useUISlotManager() {
     updateTraitContent
   };
 }
-var DEFAULT_SOURCE_KEY, MULTI_SOURCE_STACK_TRAIT, ALL_SLOTS, DEFAULT_SLOTS, DEFAULT_SOURCES, idCounter;
+var slotLog, DEFAULT_SOURCE_KEY, MULTI_SOURCE_STACK_TRAIT, ALL_SLOTS, DEFAULT_SLOTS, DEFAULT_SOURCES, idCounter;
 var init_useUISlots = __esm({
   "hooks/useUISlots.ts"() {
     "use client";
+    init_logger();
+    slotLog = createLogger("almadar:ui:useUISlots");
     DEFAULT_SOURCE_KEY = "__default__";
     MULTI_SOURCE_STACK_TRAIT = "__multi_source_stack__";
     ALL_SLOTS = [
@@ -5380,11 +5393,11 @@ function refId(obj) {
   refIds.set(obj, id);
   return id;
 }
-var slotLog, refIds, nextRefId;
+var slotLog2, refIds, nextRefId;
 var init_slot_types = __esm({
   "runtime/ui/slot-types.ts"() {
     init_logger();
-    slotLog = createLogger("almadar:ui:slot-render");
+    slotLog2 = createLogger("almadar:ui:slot-render");
     refIds = /* @__PURE__ */ new WeakMap();
     nextRefId = 1;
   }
@@ -46962,7 +46975,7 @@ function SlotContentRenderer({
 }) {
   const entityProp = content.props.entity;
   if (content.pattern === "form-section") {
-    slotLog.debug("SlotContentRenderer:form-section-render", {
+    slotLog2.debug("SlotContentRenderer:form-section-render", {
       contentId: content.id,
       sourceTrait: content.sourceTrait,
       entityRefId: refId(entityProp),
@@ -51711,6 +51724,7 @@ init_traitRegistry();
 init_verificationRegistry();
 var crossTraitLog = createLogger("almadar:ui:cross-trait");
 var flushLog = createLogger("almadar:ui:slot-flush");
+var stateLog = createLogger("almadar:ui:state-transitions");
 function toTraitDefinition(binding) {
   return {
     name: binding.trait.name,
@@ -52143,21 +52157,29 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
         const executor = new EffectExecutor({ handlers: trackingHandlers, bindings: bindingCtx, context: effectContext });
         try {
           await executor.executeAll(result.effects);
-          console.log(
-            "[TraitStateMachine] After executeAll, pendingSlots:",
-            Object.fromEntries(pendingSlots.entries())
-          );
+          stateLog.info("transition:render-ui-dispatched", {
+            traitName,
+            fromState: result.previousState,
+            toState: result.newState,
+            event: eventKey,
+            slotsTouched: Array.from(pendingSlots.keys()).join(","),
+            patternTypes: Array.from(pendingSlots.entries()).map(
+              ([slot, patterns]) => `${slot}:[${patterns.map((p2) => p2.pattern?.type ?? "null").join(",")}]`
+            ).join(";")
+          });
           void slotSource;
           for (const [slot, patterns] of pendingSlots) {
             flushSlot(traitName, slot, patterns);
           }
         } catch (error) {
-          console.error(
-            "[TraitStateMachine] Effect execution error:",
-            error,
-            "| effects:",
-            JSON.stringify(result.effects)
-          );
+          stateLog.error("transition:effect-error", {
+            traitName,
+            fromState: result.previousState,
+            toState: result.newState,
+            event: eventKey,
+            error: error instanceof Error ? error.message : String(error),
+            effectCount: result.effects.length
+          });
         }
       } else if (!result.executed) {
         if (result.guardResult === false) {
@@ -52303,13 +52325,20 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
         if (eventKey === "INIT" || eventKey === "LOAD" || eventKey === "$MOUNT") {
           continue;
         }
-        const unsub = eventBus.on(`UI:${orbitalName}.${traitName}.${eventKey}`, (event) => {
+        const selfBusKey = `UI:${orbitalName}.${traitName}.${eventKey}`;
+        crossTraitLog.debug("self:subscribe", { traitName, busKey: selfBusKey, eventKey });
+        const unsub = eventBus.on(selfBusKey, (event) => {
           if (event.source && event.source.fromBridge) {
+            crossTraitLog.debug("self:fire-skipped-bridge-echo", { traitName, busKey: selfBusKey, eventKey });
             return;
           }
+          crossTraitLog.info("self:fire", { traitName, busKey: selfBusKey, eventKey });
           enqueueAndDrain(eventKey, event.payload);
         });
-        unsubscribes.push(unsub);
+        unsubscribes.push(() => {
+          crossTraitLog.debug("self:unsubscribe", { traitName, busKey: selfBusKey, eventKey });
+          unsub();
+        });
       }
     }
     for (const binding of traitBindings) {
@@ -52327,18 +52356,23 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
         const sourceOrbital = listen.source?.orbital ?? ownOrbital;
         if (!sourceOrbital) continue;
         const busKey = `UI:${sourceOrbital}.${sourceTrait}.${listen.event}`;
-        crossTraitLog.debug("listen:subscribed", { busKey, targetTrait: binding.trait.name, triggers: listen.triggers });
+        crossTraitLog.debug("listen:subscribed", { busKey, targetTrait: binding.trait.name, sourceOrbital, sourceTrait, listenEvent: listen.event, triggers: listen.triggers });
         const unsub = eventBus.on(busKey, (event) => {
           crossTraitLog.info("listen:fired", { busKey, targetTrait: binding.trait.name, triggers: listen.triggers });
           enqueueAndDrain(listen.triggers, event.payload);
         });
-        unsubscribes.push(unsub);
+        unsubscribes.push(() => {
+          crossTraitLog.debug("listen:unsubscribe", { busKey, targetTrait: binding.trait.name, triggers: listen.triggers });
+          unsub();
+        });
       }
     }
     return () => {
+      crossTraitLog.debug("cleanup:start", { unsubscribeCount: unsubscribes.length });
       for (const unsub of unsubscribes) {
         unsub();
       }
+      crossTraitLog.debug("cleanup:done", {});
     };
   }, [traitBindings, eventBus, enqueueAndDrain]);
   return {

package/dist/components/index.cjs

@@ -40897,6 +40897,10 @@ function useDeepAgentGeneration() {
 
 // hooks/index.ts
 init_useEventBus();
+
+// hooks/useUISlots.ts
+init_logger();
+var slotLog2 = createLogger("almadar:ui:useUISlots");
 var DEFAULT_SOURCE_KEY = "__default__";
 var MULTI_SOURCE_STACK_TRAIT = "__multi_source_stack__";
 var ALL_SLOTS2 = [
@@ -41055,6 +41059,13 @@ function useUISlotManager() {
           indexTraitRender(content.sourceTrait, content);
           notifyTraitSubscribers(content.sourceTrait, content);
         }
+        slotLog2.info("slot:written", {
+          slot: config.target,
+          sourceKey,
+          sourceTrait: content.sourceTrait,
+          patternType: content.pattern,
+          priority: content.priority
+        });
         notifySubscribers(config.target, aggregateSlot(nextSources));
         return nextAll;
       });
@@ -41092,7 +41103,10 @@ function useUISlotManager() {
       const sourceKey = sourceTrait;
       setSources((prev) => {
         const slotSources = prev[slot];
-        if (!slotSources || !(sourceKey in slotSources)) return prev;
+        if (!slotSources || !(sourceKey in slotSources)) {
+          slotLog2.debug("slot:clear-noop", { slot, sourceTrait, reason: !slotSources ? "no-slot" : "no-source" });
+          return prev;
+        }
         const content = slotSources[sourceKey];
         const timer = timersRef.current.get(content.id);
         if (timer) {
@@ -41106,6 +41120,7 @@ function useUISlotManager() {
         }
         const nextSources = { ...slotSources };
         delete nextSources[sourceKey];
+        slotLog2.info("slot:cleared", { slot, sourceTrait, lastPatternType: content.pattern });
         notifySubscribers(slot, aggregateSlot(nextSources));
         return { ...prev, [slot]: nextSources };
       });

package/dist/components/index.js

@@ -40852,6 +40852,10 @@ function useDeepAgentGeneration() {
 
 // hooks/index.ts
 init_useEventBus();
+
+// hooks/useUISlots.ts
+init_logger();
+var slotLog2 = createLogger("almadar:ui:useUISlots");
 var DEFAULT_SOURCE_KEY = "__default__";
 var MULTI_SOURCE_STACK_TRAIT = "__multi_source_stack__";
 var ALL_SLOTS2 = [
@@ -41010,6 +41014,13 @@ function useUISlotManager() {
           indexTraitRender(content.sourceTrait, content);
           notifyTraitSubscribers(content.sourceTrait, content);
         }
+        slotLog2.info("slot:written", {
+          slot: config.target,
+          sourceKey,
+          sourceTrait: content.sourceTrait,
+          patternType: content.pattern,
+          priority: content.priority
+        });
         notifySubscribers(config.target, aggregateSlot(nextSources));
         return nextAll;
       });
@@ -41047,7 +41058,10 @@ function useUISlotManager() {
       const sourceKey = sourceTrait;
       setSources((prev) => {
         const slotSources = prev[slot];
-        if (!slotSources || !(sourceKey in slotSources)) return prev;
+        if (!slotSources || !(sourceKey in slotSources)) {
+          slotLog2.debug("slot:clear-noop", { slot, sourceTrait, reason: !slotSources ? "no-slot" : "no-source" });
+          return prev;
+        }
         const content = slotSources[sourceKey];
         const timer = timersRef.current.get(content.id);
         if (timer) {
@@ -41061,6 +41075,7 @@ function useUISlotManager() {
         }
         const nextSources = { ...slotSources };
         delete nextSources[sourceKey];
+        slotLog2.info("slot:cleared", { slot, sourceTrait, lastPatternType: content.pattern });
         notifySubscribers(slot, aggregateSlot(nextSources));
         return { ...prev, [slot]: nextSources };
       });

package/dist/context/index.cjs

@@ -3,6 +3,56 @@
 var react = require('react');
 var jsxRuntime = require('react/jsx-runtime');
 
+// lib/logger.ts
+var LEVEL_PRIORITY = { DEBUG: 0, INFO: 1, WARN: 2, ERROR: 3 };
+var ENV = typeof process !== "undefined" && process.env ? process.env : {};
+function envGet(key) {
+  return ENV[key] ?? ENV[`VITE_${key}`];
+}
+var NODE_ENV = envGet("NODE_ENV") ?? "development";
+var CONFIGURED_LEVEL = (envGet("LOG_LEVEL") ?? (NODE_ENV === "production" ? "info" : "debug")).toUpperCase();
+var MIN_PRIORITY = LEVEL_PRIORITY[CONFIGURED_LEVEL] ?? 0;
+var DEBUG_FILTER = (envGet("ALMADAR_DEBUG") ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+function matchesNamespace(namespace) {
+  if (DEBUG_FILTER.length === 0) return true;
+  return DEBUG_FILTER.some((pattern) => {
+    if (pattern === "*" || pattern === "almadar:*") return true;
+    if (pattern.endsWith(":*")) return namespace.startsWith(pattern.slice(0, -1));
+    return namespace === pattern;
+  });
+}
+function createLogger(namespace) {
+  const nsAllowed = matchesNamespace(namespace);
+  const log = (level, message, data, correlationId) => {
+    if (LEVEL_PRIORITY[level] < MIN_PRIORITY) return;
+    if (level === "DEBUG" && !nsAllowed) return;
+    const prefix = `[${namespace}]`;
+    const logData = correlationId ? { ...data, cid: correlationId } : data;
+    switch (level) {
+      case "DEBUG":
+        console.debug(prefix, message, logData ?? "");
+        break;
+      case "INFO":
+        console.info(prefix, message, logData ?? "");
+        break;
+      case "WARN":
+        console.warn(prefix, message, logData ?? "");
+        break;
+      case "ERROR":
+        console.error(prefix, message, logData ?? "");
+        break;
+    }
+  };
+  return {
+    debug: (msg, data, cid) => log("DEBUG", msg, data, cid),
+    info: (msg, data, cid) => log("INFO", msg, data, cid),
+    warn: (msg, data, cid) => log("WARN", msg, data, cid),
+    error: (msg, data, cid) => log("ERROR", msg, data, cid)
+  };
+}
+
+// hooks/useUISlots.ts
+var slotLog = createLogger("almadar:ui:useUISlots");
 var DEFAULT_SOURCE_KEY = "__default__";
 var MULTI_SOURCE_STACK_TRAIT = "__multi_source_stack__";
 var ALL_SLOTS = [
@@ -161,6 +211,13 @@ function useUISlotManager() {
           indexTraitRender(content.sourceTrait, content);
           notifyTraitSubscribers(content.sourceTrait, content);
         }
+        slotLog.info("slot:written", {
+          slot: config.target,
+          sourceKey,
+          sourceTrait: content.sourceTrait,
+          patternType: content.pattern,
+          priority: content.priority
+        });
         notifySubscribers(config.target, aggregateSlot(nextSources));
         return nextAll;
       });
@@ -198,7 +255,10 @@ function useUISlotManager() {
       const sourceKey = sourceTrait;
       setSources((prev) => {
         const slotSources = prev[slot];
-        if (!slotSources || !(sourceKey in slotSources)) return prev;
+        if (!slotSources || !(sourceKey in slotSources)) {
+          slotLog.debug("slot:clear-noop", { slot, sourceTrait, reason: !slotSources ? "no-slot" : "no-source" });
+          return prev;
+        }
         const content = slotSources[sourceKey];
         const timer = timersRef.current.get(content.id);
         if (timer) {
@@ -212,6 +272,7 @@ function useUISlotManager() {
         }
         const nextSources = { ...slotSources };
         delete nextSources[sourceKey];
+        slotLog.info("slot:cleared", { slot, sourceTrait, lastPatternType: content.pattern });
         notifySubscribers(slot, aggregateSlot(nextSources));
         return { ...prev, [slot]: nextSources };
       });

package/dist/context/index.js

@@ -1,6 +1,56 @@
 import { createContext, useMemo, useContext, useState, useEffect, useCallback, useRef } from 'react';
 import { jsx } from 'react/jsx-runtime';
 
+// lib/logger.ts
+var LEVEL_PRIORITY = { DEBUG: 0, INFO: 1, WARN: 2, ERROR: 3 };
+var ENV = typeof process !== "undefined" && process.env ? process.env : {};
+function envGet(key) {
+  return ENV[key] ?? ENV[`VITE_${key}`];
+}
+var NODE_ENV = envGet("NODE_ENV") ?? "development";
+var CONFIGURED_LEVEL = (envGet("LOG_LEVEL") ?? (NODE_ENV === "production" ? "info" : "debug")).toUpperCase();
+var MIN_PRIORITY = LEVEL_PRIORITY[CONFIGURED_LEVEL] ?? 0;
+var DEBUG_FILTER = (envGet("ALMADAR_DEBUG") ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+function matchesNamespace(namespace) {
+  if (DEBUG_FILTER.length === 0) return true;
+  return DEBUG_FILTER.some((pattern) => {
+    if (pattern === "*" || pattern === "almadar:*") return true;
+    if (pattern.endsWith(":*")) return namespace.startsWith(pattern.slice(0, -1));
+    return namespace === pattern;
+  });
+}
+function createLogger(namespace) {
+  const nsAllowed = matchesNamespace(namespace);
+  const log = (level, message, data, correlationId) => {
+    if (LEVEL_PRIORITY[level] < MIN_PRIORITY) return;
+    if (level === "DEBUG" && !nsAllowed) return;
+    const prefix = `[${namespace}]`;
+    const logData = correlationId ? { ...data, cid: correlationId } : data;
+    switch (level) {
+      case "DEBUG":
+        console.debug(prefix, message, logData ?? "");
+        break;
+      case "INFO":
+        console.info(prefix, message, logData ?? "");
+        break;
+      case "WARN":
+        console.warn(prefix, message, logData ?? "");
+        break;
+      case "ERROR":
+        console.error(prefix, message, logData ?? "");
+        break;
+    }
+  };
+  return {
+    debug: (msg, data, cid) => log("DEBUG", msg, data, cid),
+    info: (msg, data, cid) => log("INFO", msg, data, cid),
+    warn: (msg, data, cid) => log("WARN", msg, data, cid),
+    error: (msg, data, cid) => log("ERROR", msg, data, cid)
+  };
+}
+
+// hooks/useUISlots.ts
+var slotLog = createLogger("almadar:ui:useUISlots");
 var DEFAULT_SOURCE_KEY = "__default__";
 var MULTI_SOURCE_STACK_TRAIT = "__multi_source_stack__";
 var ALL_SLOTS = [
@@ -159,6 +209,13 @@ function useUISlotManager() {
           indexTraitRender(content.sourceTrait, content);
           notifyTraitSubscribers(content.sourceTrait, content);
         }
+        slotLog.info("slot:written", {
+          slot: config.target,
+          sourceKey,
+          sourceTrait: content.sourceTrait,
+          patternType: content.pattern,
+          priority: content.priority
+        });
         notifySubscribers(config.target, aggregateSlot(nextSources));
         return nextAll;
       });
@@ -196,7 +253,10 @@ function useUISlotManager() {
       const sourceKey = sourceTrait;
       setSources((prev) => {
         const slotSources = prev[slot];
-        if (!slotSources || !(sourceKey in slotSources)) return prev;
+        if (!slotSources || !(sourceKey in slotSources)) {
+          slotLog.debug("slot:clear-noop", { slot, sourceTrait, reason: !slotSources ? "no-slot" : "no-source" });
+          return prev;
+        }
         const content = slotSources[sourceKey];
         const timer = timersRef.current.get(content.id);
         if (timer) {
@@ -210,6 +270,7 @@ function useUISlotManager() {
         }
         const nextSources = { ...slotSources };
         delete nextSources[sourceKey];
+        slotLog.info("slot:cleared", { slot, sourceTrait, lastPatternType: content.pattern });
         notifySubscribers(slot, aggregateSlot(nextSources));
         return { ...prev, [slot]: nextSources };
       });

package/dist/hooks/index.cjs

@@ -1046,6 +1046,7 @@ function useEmitEvent() {
     [eventBus]
   );
 }
+var slotLog = createLogger("almadar:ui:useUISlots");
 var DEFAULT_SOURCE_KEY = "__default__";
 var MULTI_SOURCE_STACK_TRAIT = "__multi_source_stack__";
 var ALL_SLOTS = [
@@ -1204,6 +1205,13 @@ function useUISlotManager() {
           indexTraitRender(content.sourceTrait, content);
           notifyTraitSubscribers(content.sourceTrait, content);
         }
+        slotLog.info("slot:written", {
+          slot: config.target,
+          sourceKey,
+          sourceTrait: content.sourceTrait,
+          patternType: content.pattern,
+          priority: content.priority
+        });
         notifySubscribers(config.target, aggregateSlot(nextSources));
         return nextAll;
       });
@@ -1241,7 +1249,10 @@ function useUISlotManager() {
       const sourceKey = sourceTrait;
       setSources((prev) => {
         const slotSources = prev[slot];
-        if (!slotSources || !(sourceKey in slotSources)) return prev;
+        if (!slotSources || !(sourceKey in slotSources)) {
+          slotLog.debug("slot:clear-noop", { slot, sourceTrait, reason: !slotSources ? "no-slot" : "no-source" });
+          return prev;
+        }
         const content = slotSources[sourceKey];
         const timer = timersRef.current.get(content.id);
         if (timer) {
@@ -1255,6 +1266,7 @@ function useUISlotManager() {
         }
         const nextSources = { ...slotSources };
         delete nextSources[sourceKey];
+        slotLog.info("slot:cleared", { slot, sourceTrait, lastPatternType: content.pattern });
         notifySubscribers(slot, aggregateSlot(nextSources));
         return { ...prev, [slot]: nextSources };
       });

package/dist/hooks/index.js

@@ -1044,6 +1044,7 @@ function useEmitEvent() {
     [eventBus]
   );
 }
+var slotLog = createLogger("almadar:ui:useUISlots");
 var DEFAULT_SOURCE_KEY = "__default__";
 var MULTI_SOURCE_STACK_TRAIT = "__multi_source_stack__";
 var ALL_SLOTS = [
@@ -1202,6 +1203,13 @@ function useUISlotManager() {
           indexTraitRender(content.sourceTrait, content);
           notifyTraitSubscribers(content.sourceTrait, content);
         }
+        slotLog.info("slot:written", {
+          slot: config.target,
+          sourceKey,
+          sourceTrait: content.sourceTrait,
+          patternType: content.pattern,
+          priority: content.priority
+        });
         notifySubscribers(config.target, aggregateSlot(nextSources));
         return nextAll;
       });
@@ -1239,7 +1247,10 @@ function useUISlotManager() {
       const sourceKey = sourceTrait;
       setSources((prev) => {
         const slotSources = prev[slot];
-        if (!slotSources || !(sourceKey in slotSources)) return prev;
+        if (!slotSources || !(sourceKey in slotSources)) {
+          slotLog.debug("slot:clear-noop", { slot, sourceTrait, reason: !slotSources ? "no-slot" : "no-source" });
+          return prev;
+        }
         const content = slotSources[sourceKey];
         const timer = timersRef.current.get(content.id);
         if (timer) {
@@ -1253,6 +1264,7 @@ function useUISlotManager() {
         }
         const nextSources = { ...slotSources };
         delete nextSources[sourceKey];
+        slotLog.info("slot:cleared", { slot, sourceTrait, lastPatternType: content.pattern });
         notifySubscribers(slot, aggregateSlot(nextSources));
         return { ...prev, [slot]: nextSources };
       });

package/dist/runtime/index.cjs

@@ -2086,11 +2086,11 @@ function refId(obj) {
   refIds.set(obj, id);
   return id;
 }
-var slotLog, refIds, nextRefId;
+var slotLog2, refIds, nextRefId;
 var init_slot_types = __esm({
   "runtime/ui/slot-types.ts"() {
     init_logger();
-    slotLog = createLogger("almadar:ui:slot-render");
+    slotLog2 = createLogger("almadar:ui:slot-render");
     refIds = /* @__PURE__ */ new WeakMap();
     nextRefId = 1;
   }
@@ -37880,7 +37880,7 @@ function SlotContentRenderer({
 }) {
   const entityProp = content.props.entity;
   if (content.pattern === "form-section") {
-    slotLog.debug("SlotContentRenderer:form-section-render", {
+    slotLog2.debug("SlotContentRenderer:form-section-render", {
       contentId: content.id,
       sourceTrait: content.sourceTrait,
       entityRefId: refId(entityProp),
@@ -38091,6 +38091,10 @@ var init_UISlotRenderer = __esm({
 
 // hooks/index.ts
 init_useEventBus();
+
+// hooks/useUISlots.ts
+init_logger();
+createLogger("almadar:ui:useUISlots");
 var ALL_SLOTS = [
   "main",
   "sidebar",
@@ -38293,6 +38297,7 @@ init_traitRegistry();
 init_verificationRegistry();
 var crossTraitLog = createLogger("almadar:ui:cross-trait");
 var flushLog = createLogger("almadar:ui:slot-flush");
+var stateLog = createLogger("almadar:ui:state-transitions");
 function toTraitDefinition(binding) {
   return {
     name: binding.trait.name,
@@ -38725,21 +38730,29 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
         const executor = new runtime.EffectExecutor({ handlers: trackingHandlers, bindings: bindingCtx, context: effectContext });
         try {
           await executor.executeAll(result.effects);
-          console.log(
-            "[TraitStateMachine] After executeAll, pendingSlots:",
-            Object.fromEntries(pendingSlots.entries())
-          );
+          stateLog.info("transition:render-ui-dispatched", {
+            traitName,
+            fromState: result.previousState,
+            toState: result.newState,
+            event: eventKey,
+            slotsTouched: Array.from(pendingSlots.keys()).join(","),
+            patternTypes: Array.from(pendingSlots.entries()).map(
+              ([slot, patterns]) => `${slot}:[${patterns.map((p2) => p2.pattern?.type ?? "null").join(",")}]`
+            ).join(";")
+          });
           void slotSource;
           for (const [slot, patterns] of pendingSlots) {
             flushSlot(traitName, slot, patterns);
           }
         } catch (error) {
-          console.error(
-            "[TraitStateMachine] Effect execution error:",
-            error,
-            "| effects:",
-            JSON.stringify(result.effects)
-          );
+          stateLog.error("transition:effect-error", {
+            traitName,
+            fromState: result.previousState,
+            toState: result.newState,
+            event: eventKey,
+            error: error instanceof Error ? error.message : String(error),
+            effectCount: result.effects.length
+          });
         }
       } else if (!result.executed) {
         if (result.guardResult === false) {
@@ -38885,13 +38898,20 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
         if (eventKey === "INIT" || eventKey === "LOAD" || eventKey === "$MOUNT") {
           continue;
         }
-        const unsub = eventBus.on(`UI:${orbitalName}.${traitName}.${eventKey}`, (event) => {
+        const selfBusKey = `UI:${orbitalName}.${traitName}.${eventKey}`;
+        crossTraitLog.debug("self:subscribe", { traitName, busKey: selfBusKey, eventKey });
+        const unsub = eventBus.on(selfBusKey, (event) => {
           if (event.source && event.source.fromBridge) {
+            crossTraitLog.debug("self:fire-skipped-bridge-echo", { traitName, busKey: selfBusKey, eventKey });
             return;
           }
+          crossTraitLog.info("self:fire", { traitName, busKey: selfBusKey, eventKey });
           enqueueAndDrain(eventKey, event.payload);
         });
-        unsubscribes.push(unsub);
+        unsubscribes.push(() => {
+          crossTraitLog.debug("self:unsubscribe", { traitName, busKey: selfBusKey, eventKey });
+          unsub();
+        });
       }
     }
     for (const binding of traitBindings) {
@@ -38909,18 +38929,23 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
         const sourceOrbital = listen.source?.orbital ?? ownOrbital;
         if (!sourceOrbital) continue;
         const busKey = `UI:${sourceOrbital}.${sourceTrait}.${listen.event}`;
-        crossTraitLog.debug("listen:subscribed", { busKey, targetTrait: binding.trait.name, triggers: listen.triggers });
+        crossTraitLog.debug("listen:subscribed", { busKey, targetTrait: binding.trait.name, sourceOrbital, sourceTrait, listenEvent: listen.event, triggers: listen.triggers });
         const unsub = eventBus.on(busKey, (event) => {
           crossTraitLog.info("listen:fired", { busKey, targetTrait: binding.trait.name, triggers: listen.triggers });
           enqueueAndDrain(listen.triggers, event.payload);
         });
-        unsubscribes.push(unsub);
+        unsubscribes.push(() => {
+          crossTraitLog.debug("listen:unsubscribe", { busKey, targetTrait: binding.trait.name, triggers: listen.triggers });
+          unsub();
+        });
       }
     }
     return () => {
+      crossTraitLog.debug("cleanup:start", { unsubscribeCount: unsubscribes.length });
       for (const unsub of unsubscribes) {
         unsub();
       }
+      crossTraitLog.debug("cleanup:done", {});
     };
   }, [traitBindings, eventBus, enqueueAndDrain]);
   return {

package/dist/runtime/index.js

@@ -2041,11 +2041,11 @@ function refId(obj) {
   refIds.set(obj, id);
   return id;
 }
-var slotLog, refIds, nextRefId;
+var slotLog2, refIds, nextRefId;
 var init_slot_types = __esm({
   "runtime/ui/slot-types.ts"() {
     init_logger();
-    slotLog = createLogger("almadar:ui:slot-render");
+    slotLog2 = createLogger("almadar:ui:slot-render");
     refIds = /* @__PURE__ */ new WeakMap();
     nextRefId = 1;
   }
@@ -37835,7 +37835,7 @@ function SlotContentRenderer({
 }) {
   const entityProp = content.props.entity;
   if (content.pattern === "form-section") {
-    slotLog.debug("SlotContentRenderer:form-section-render", {
+    slotLog2.debug("SlotContentRenderer:form-section-render", {
       contentId: content.id,
       sourceTrait: content.sourceTrait,
       entityRefId: refId(entityProp),
@@ -38046,6 +38046,10 @@ var init_UISlotRenderer = __esm({
 
 // hooks/index.ts
 init_useEventBus();
+
+// hooks/useUISlots.ts
+init_logger();
+createLogger("almadar:ui:useUISlots");
 var ALL_SLOTS = [
   "main",
   "sidebar",
@@ -38248,6 +38252,7 @@ init_traitRegistry();
 init_verificationRegistry();
 var crossTraitLog = createLogger("almadar:ui:cross-trait");
 var flushLog = createLogger("almadar:ui:slot-flush");
+var stateLog = createLogger("almadar:ui:state-transitions");
 function toTraitDefinition(binding) {
   return {
     name: binding.trait.name,
@@ -38680,21 +38685,29 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
         const executor = new EffectExecutor({ handlers: trackingHandlers, bindings: bindingCtx, context: effectContext });
         try {
           await executor.executeAll(result.effects);
-          console.log(
-            "[TraitStateMachine] After executeAll, pendingSlots:",
-            Object.fromEntries(pendingSlots.entries())
-          );
+          stateLog.info("transition:render-ui-dispatched", {
+            traitName,
+            fromState: result.previousState,
+            toState: result.newState,
+            event: eventKey,
+            slotsTouched: Array.from(pendingSlots.keys()).join(","),
+            patternTypes: Array.from(pendingSlots.entries()).map(
+              ([slot, patterns]) => `${slot}:[${patterns.map((p2) => p2.pattern?.type ?? "null").join(",")}]`
+            ).join(";")
+          });
           void slotSource;
           for (const [slot, patterns] of pendingSlots) {
             flushSlot(traitName, slot, patterns);
           }
         } catch (error) {
-          console.error(
-            "[TraitStateMachine] Effect execution error:",
-            error,
-            "| effects:",
-            JSON.stringify(result.effects)
-          );
+          stateLog.error("transition:effect-error", {
+            traitName,
+            fromState: result.previousState,
+            toState: result.newState,
+            event: eventKey,
+            error: error instanceof Error ? error.message : String(error),
+            effectCount: result.effects.length
+          });
         }
       } else if (!result.executed) {
         if (result.guardResult === false) {
@@ -38840,13 +38853,20 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
         if (eventKey === "INIT" || eventKey === "LOAD" || eventKey === "$MOUNT") {
           continue;
         }
-        const unsub = eventBus.on(`UI:${orbitalName}.${traitName}.${eventKey}`, (event) => {
+        const selfBusKey = `UI:${orbitalName}.${traitName}.${eventKey}`;
+        crossTraitLog.debug("self:subscribe", { traitName, busKey: selfBusKey, eventKey });
+        const unsub = eventBus.on(selfBusKey, (event) => {
           if (event.source && event.source.fromBridge) {
+            crossTraitLog.debug("self:fire-skipped-bridge-echo", { traitName, busKey: selfBusKey, eventKey });
             return;
           }
+          crossTraitLog.info("self:fire", { traitName, busKey: selfBusKey, eventKey });
           enqueueAndDrain(eventKey, event.payload);
         });
-        unsubscribes.push(unsub);
+        unsubscribes.push(() => {
+          crossTraitLog.debug("self:unsubscribe", { traitName, busKey: selfBusKey, eventKey });
+          unsub();
+        });
       }
     }
     for (const binding of traitBindings) {
@@ -38864,18 +38884,23 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
         const sourceOrbital = listen.source?.orbital ?? ownOrbital;
         if (!sourceOrbital) continue;
         const busKey = `UI:${sourceOrbital}.${sourceTrait}.${listen.event}`;
-        crossTraitLog.debug("listen:subscribed", { busKey, targetTrait: binding.trait.name, triggers: listen.triggers });
+        crossTraitLog.debug("listen:subscribed", { busKey, targetTrait: binding.trait.name, sourceOrbital, sourceTrait, listenEvent: listen.event, triggers: listen.triggers });
         const unsub = eventBus.on(busKey, (event) => {
           crossTraitLog.info("listen:fired", { busKey, targetTrait: binding.trait.name, triggers: listen.triggers });
           enqueueAndDrain(listen.triggers, event.payload);
         });
-        unsubscribes.push(unsub);
+        unsubscribes.push(() => {
+          crossTraitLog.debug("listen:unsubscribe", { busKey, targetTrait: binding.trait.name, triggers: listen.triggers });
+          unsub();
+        });
       }
     }
     return () => {
+      crossTraitLog.debug("cleanup:start", { unsubscribeCount: unsubscribes.length });
       for (const unsub of unsubscribes) {
         unsub();
       }
+      crossTraitLog.debug("cleanup:done", {});
     };
   }, [traitBindings, eventBus, enqueueAndDrain]);
   return {

package/package.json

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