@almadar/ui 2.46.1 → 2.47.1

package/dist/hooks/index.js

@@ -866,6 +866,67 @@ function useDeepAgentGeneration() {
     submitInterruptDecisions
   };
 }
+
+// lib/logger.ts
+var LEVEL_PRIORITY = { DEBUG: 0, INFO: 1, WARN: 2, ERROR: 3 };
+var ENV = typeof process !== "undefined" && process.env ? process.env : {};
+var VITE_ENV = typeof globalThis !== "undefined" && globalThis.__vite_env__ ? globalThis.__vite_env__ : {};
+function getViteEnv(key) {
+  try {
+    const meta = import.meta;
+    return meta?.env?.[key];
+  } catch {
+    return void 0;
+  }
+}
+function envGet(key, viteKey) {
+  return ENV[key] ?? (viteKey ? getViteEnv(viteKey) : void 0) ?? VITE_ENV[viteKey ?? key];
+}
+var NODE_ENV = envGet("NODE_ENV", "VITE_NODE_ENV") ?? "development";
+var CONFIGURED_LEVEL = (envGet("LOG_LEVEL", "VITE_LOG_LEVEL") ?? (NODE_ENV === "production" ? "info" : "debug")).toUpperCase();
+var MIN_PRIORITY = LEVEL_PRIORITY[CONFIGURED_LEVEL] ?? 0;
+var DEBUG_FILTER = (envGet("ALMADAR_DEBUG", "VITE_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 log2 = (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) => log2("DEBUG", msg, data, cid),
+    info: (msg, data, cid) => log2("INFO", msg, data, cid),
+    warn: (msg, data, cid) => log2("WARN", msg, data, cid),
+    error: (msg, data, cid) => log2("ERROR", msg, data, cid)
+  };
+}
+
+// hooks/useEventBus.ts
+var log = createLogger("almadar:eventbus");
+var subLog = createLogger("almadar:eventbus:subscribe");
 function getGlobalEventBus() {
   if (typeof window !== "undefined") {
     return window.__kflowEventBus ?? null;
@@ -882,6 +943,7 @@ var fallbackEventBus = {
       timestamp: Date.now()
     };
     const handlers = fallbackListeners.get(type);
+    log.debug("emit", { type, payloadKeys: payload ? Object.keys(payload).length : 0, listenerCount: (handlers?.size ?? 0) + fallbackAnyListeners.size });
     if (handlers) {
       handlers.forEach((handler) => {
         try {
@@ -904,6 +966,7 @@ var fallbackEventBus = {
       fallbackListeners.set(type, /* @__PURE__ */ new Set());
     }
     fallbackListeners.get(type).add(listener);
+    subLog.debug("subscribe", { type, totalListeners: fallbackListeners.get(type).size });
     return () => {
       const handlers = fallbackListeners.get(type);
       if (handlers) {
@@ -927,6 +990,7 @@ var fallbackEventBus = {
   },
   onAny: (listener) => {
     fallbackAnyListeners.add(listener);
+    subLog.debug("subscribe:any", { totalAnyListeners: fallbackAnyListeners.size });
     return () => {
       fallbackAnyListeners.delete(listener);
     };
@@ -1106,31 +1170,7 @@ function useUISlotManager() {
 var SelectionContext = createContext(null);
 
 // hooks/useUIEvents.ts
-var UI_EVENT_MAP = {
-  // Form/CRUD events
-  "UI:SAVE": "SAVE",
-  "UI:CANCEL": "CANCEL",
-  "UI:CLOSE": "CLOSE",
-  "UI:VIEW": "VIEW",
-  "UI:EDIT": "EDIT",
-  "UI:DELETE": "DELETE",
-  "UI:CREATE": "CREATE",
-  "UI:SELECT": "SELECT",
-  "UI:DESELECT": "DESELECT",
-  "UI:SUBMIT": "SAVE",
-  "UI:UPDATE_STATUS": "UPDATE_STATUS",
-  "UI:SEARCH": "SEARCH",
-  "UI:CLEAR_SEARCH": "CLEAR_SEARCH",
-  "UI:ADD": "CREATE",
-  // Game events (for closed circuit with GameMenu, GamePauseOverlay, GameOverScreen)
-  "UI:PAUSE": "PAUSE",
-  "UI:RESUME": "RESUME",
-  "UI:RESTART": "RESTART",
-  "UI:GAME_OVER": "GAME_OVER",
-  "UI:START": "START",
-  "UI:QUIT": "QUIT",
-  "UI:INIT": "INIT"
-};
+var UI_PREFIX = "UI:";
 function useUIEvents(dispatch, validEvents, eventBusInstance) {
   const defaultEventBus = useEventBus();
   const eventBus = eventBusInstance ?? defaultEventBus;
@@ -1142,15 +1182,18 @@ function useUIEvents(dispatch, validEvents, eventBusInstance) {
   );
   useEffect(() => {
     const unsubscribes = [];
-    Object.entries(UI_EVENT_MAP).forEach(([uiEvent, smEvent]) => {
-      const handler = (event) => {
-        if (!stableValidEvents || stableValidEvents.includes(smEvent)) {
+    if (stableValidEvents) {
+      for (const smEvent of stableValidEvents) {
+        const prefixedHandler = (event) => {
           dispatch(smEvent, event.payload);
-        }
-      };
-      const unsubscribe = eventBus.on(uiEvent, handler);
-      unsubscribes.push(unsubscribe);
-    });
+        };
+        unsubscribes.push(eventBus.on(`${UI_PREFIX}${smEvent}`, prefixedHandler));
+        const directHandler = (event) => {
+          dispatch(smEvent, event.payload);
+        };
+        unsubscribes.push(eventBus.on(smEvent, directHandler));
+      }
+    }
     const genericHandler = (event) => {
       const eventName = event.payload?.event;
       if (eventName) {
@@ -1160,30 +1203,11 @@ function useUIEvents(dispatch, validEvents, eventBusInstance) {
         }
       }
     };
-    const genericUnsubscribe = eventBus.on("UI:DISPATCH", genericHandler);
-    unsubscribes.push(genericUnsubscribe);
-    if (stableValidEvents) {
-      stableValidEvents.forEach((smEvent) => {
-        const uiPrefixedEvent = `UI:${smEvent}`;
-        const alreadyMapped = Object.keys(UI_EVENT_MAP).includes(uiPrefixedEvent);
-        if (!alreadyMapped) {
-          const directHandler = (event) => {
-            dispatch(smEvent, event.payload);
-          };
-          const unsubscribePrefixed = eventBus.on(
-            uiPrefixedEvent,
-            directHandler
-          );
-          unsubscribes.push(unsubscribePrefixed);
-          const unsubscribeDirect = eventBus.on(smEvent, directHandler);
-          unsubscribes.push(unsubscribeDirect);
-        }
-      });
-    }
+    unsubscribes.push(eventBus.on(`${UI_PREFIX}DISPATCH`, genericHandler));
     return () => {
-      unsubscribes.forEach((unsub) => {
+      for (const unsub of unsubscribes) {
         if (typeof unsub === "function") unsub();
-      });
+      }
     };
   }, [eventBus, dispatch, stableValidEvents]);
 }
@@ -1605,21 +1629,21 @@ function useOrbitalMutations(entityName, orbitalName, options) {
     update: options?.events?.update || ENTITY_EVENTS.UPDATE,
     delete: options?.events?.delete || ENTITY_EVENTS.DELETE
   };
-  const log = (message, data) => {
+  const log2 = (message, data) => {
     if (options?.debug) {
       console.log(`[useOrbitalMutations:${orbitalName}] ${message}`, data ?? "");
     }
   };
   const createMutation = useMutation({
     mutationFn: async (data) => {
-      log("Creating entity", data);
+      log2("Creating entity", data);
       return sendOrbitalEvent(orbitalName, {
         event: events.create,
         payload: { data, entityType: entityName }
       });
     },
     onSuccess: (response) => {
-      log("Create succeeded", response);
+      log2("Create succeeded", response);
       queryClient.invalidateQueries({ queryKey: entityDataKeys.list(entityName) });
     },
     onError: (error) => {
@@ -1631,7 +1655,7 @@ function useOrbitalMutations(entityName, orbitalName, options) {
       id,
       data
     }) => {
-      log(`Updating entity ${id}`, data);
+      log2(`Updating entity ${id}`, data);
       return sendOrbitalEvent(orbitalName, {
         event: events.update,
         entityId: id,
@@ -1639,7 +1663,7 @@ function useOrbitalMutations(entityName, orbitalName, options) {
       });
     },
     onSuccess: (response, variables) => {
-      log("Update succeeded", response);
+      log2("Update succeeded", response);
       queryClient.invalidateQueries({ queryKey: entityDataKeys.list(entityName) });
       queryClient.invalidateQueries({
         queryKey: entityDataKeys.detail(entityName, variables.id)
@@ -1651,7 +1675,7 @@ function useOrbitalMutations(entityName, orbitalName, options) {
   });
   const deleteMutation = useMutation({
     mutationFn: async (id) => {
-      log(`Deleting entity ${id}`);
+      log2(`Deleting entity ${id}`);
       return sendOrbitalEvent(orbitalName, {
         event: events.delete,
         entityId: id,
@@ -1659,7 +1683,7 @@ function useOrbitalMutations(entityName, orbitalName, options) {
       });
     },
     onSuccess: (response, id) => {
-      log("Delete succeeded", response);
+      log2("Delete succeeded", response);
       queryClient.invalidateQueries({ queryKey: entityDataKeys.list(entityName) });
       queryClient.removeQueries({ queryKey: entityDataKeys.detail(entityName, id) });
     },

package/dist/lib/index.cjs

@@ -3,6 +3,7 @@
 var clsx = require('clsx');
 var tailwindMerge = require('tailwind-merge');
 
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 function cn(...inputs) {
   return tailwindMerge.twMerge(clsx.clsx(inputs));
 }
@@ -427,7 +428,69 @@ function clearTraits() {
   notifyListeners4();
 }
 
+// lib/logger.ts
+var LEVEL_PRIORITY = { DEBUG: 0, INFO: 1, WARN: 2, ERROR: 3 };
+var ENV = typeof process !== "undefined" && process.env ? process.env : {};
+var VITE_ENV = typeof globalThis !== "undefined" && globalThis.__vite_env__ ? globalThis.__vite_env__ : {};
+function getViteEnv(key) {
+  try {
+    const meta = ({ url: (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)) });
+    return meta?.env?.[key];
+  } catch {
+    return void 0;
+  }
+}
+function envGet(key, viteKey) {
+  return ENV[key] ?? (viteKey ? getViteEnv(viteKey) : void 0) ?? VITE_ENV[viteKey ?? key];
+}
+var NODE_ENV = envGet("NODE_ENV", "VITE_NODE_ENV") ?? "development";
+var CONFIGURED_LEVEL = (envGet("LOG_LEVEL", "VITE_LOG_LEVEL") ?? (NODE_ENV === "production" ? "info" : "debug")).toUpperCase();
+var MIN_PRIORITY = LEVEL_PRIORITY[CONFIGURED_LEVEL] ?? 0;
+var DEBUG_FILTER = (envGet("ALMADAR_DEBUG", "VITE_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 log2 = (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) => log2("DEBUG", msg, data, cid),
+    info: (msg, data, cid) => log2("INFO", msg, data, cid),
+    warn: (msg, data, cid) => log2("WARN", msg, data, cid),
+    error: (msg, data, cid) => log2("ERROR", msg, data, cid)
+  };
+}
+var _cidCounter = 0;
+function generateCorrelationId() {
+  return `evt-${Date.now()}-${++_cidCounter}`;
+}
+
 // lib/verificationRegistry.ts
+var log = createLogger("almadar:bridge");
 var MAX_TRANSITIONS = 500;
 function getState() {
   if (typeof window !== "undefined") {
@@ -471,6 +534,7 @@ function recordTransition(trace) {
     ...trace,
     id: `t-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`
   };
+  log.info("transition:recorded", { trait: trace.traitName, from: trace.from, to: trace.to, event: trace.event, effectCount: trace.effects.length });
   getState().transitions.push(entry);
   if (getState().transitions.length > MAX_TRANSITIONS) {
     getState().transitions.shift();
@@ -620,10 +684,12 @@ function waitForTransition(event, timeoutMs = 1e4) {
 }
 function bindEventBus(eventBus) {
   if (typeof window === "undefined") return;
+  log.info("bindEventBus", { hasOnAny: !!eventBus.onAny });
   exposeOnWindow();
   if (window.__orbitalVerification) {
     window.__orbitalVerification.sendEvent = (event, payload) => {
       const prefixed = event.startsWith("UI:") ? event : `UI:${event}`;
+      log.debug("sendEvent", { event: prefixed, payloadKeys: payload ? Object.keys(payload) : [] });
       eventBus.emit(prefixed, payload);
     };
     const eventLog = [];
@@ -1461,6 +1527,7 @@ exports.clearTicks = clearTicks;
 exports.clearTraits = clearTraits;
 exports.clearVerification = clearVerification;
 exports.cn = cn;
+exports.createLogger = createLogger;
 exports.debug = debug;
 exports.debugCollision = debugCollision;
 exports.debugError = debugError;
@@ -1477,6 +1544,7 @@ exports.extractOutputsFromTransitions = extractOutputsFromTransitions;
 exports.extractStateMachine = extractStateMachine;
 exports.formatGuard = formatGuard;
 exports.formatNestedFieldLabel = formatNestedFieldLabel;
+exports.generateCorrelationId = generateCorrelationId;
 exports.getAllChecks = getAllChecks;
 exports.getAllTicks = getAllTicks;
 exports.getAllTraits = getAllTraits;

package/dist/lib/index.d.ts

@@ -16,3 +16,4 @@ export * from './verificationRegistry';
 export * from './getNestedValue';
 export * from './visualizer';
 export * from './parseContentSegments';
+export * from './logger';

package/dist/lib/index.js

@@ -425,7 +425,69 @@ function clearTraits() {
   notifyListeners4();
 }
 
+// lib/logger.ts
+var LEVEL_PRIORITY = { DEBUG: 0, INFO: 1, WARN: 2, ERROR: 3 };
+var ENV = typeof process !== "undefined" && process.env ? process.env : {};
+var VITE_ENV = typeof globalThis !== "undefined" && globalThis.__vite_env__ ? globalThis.__vite_env__ : {};
+function getViteEnv(key) {
+  try {
+    const meta = import.meta;
+    return meta?.env?.[key];
+  } catch {
+    return void 0;
+  }
+}
+function envGet(key, viteKey) {
+  return ENV[key] ?? (viteKey ? getViteEnv(viteKey) : void 0) ?? VITE_ENV[viteKey ?? key];
+}
+var NODE_ENV = envGet("NODE_ENV", "VITE_NODE_ENV") ?? "development";
+var CONFIGURED_LEVEL = (envGet("LOG_LEVEL", "VITE_LOG_LEVEL") ?? (NODE_ENV === "production" ? "info" : "debug")).toUpperCase();
+var MIN_PRIORITY = LEVEL_PRIORITY[CONFIGURED_LEVEL] ?? 0;
+var DEBUG_FILTER = (envGet("ALMADAR_DEBUG", "VITE_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 log2 = (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) => log2("DEBUG", msg, data, cid),
+    info: (msg, data, cid) => log2("INFO", msg, data, cid),
+    warn: (msg, data, cid) => log2("WARN", msg, data, cid),
+    error: (msg, data, cid) => log2("ERROR", msg, data, cid)
+  };
+}
+var _cidCounter = 0;
+function generateCorrelationId() {
+  return `evt-${Date.now()}-${++_cidCounter}`;
+}
+
 // lib/verificationRegistry.ts
+var log = createLogger("almadar:bridge");
 var MAX_TRANSITIONS = 500;
 function getState() {
   if (typeof window !== "undefined") {
@@ -469,6 +531,7 @@ function recordTransition(trace) {
     ...trace,
     id: `t-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`
   };
+  log.info("transition:recorded", { trait: trace.traitName, from: trace.from, to: trace.to, event: trace.event, effectCount: trace.effects.length });
   getState().transitions.push(entry);
   if (getState().transitions.length > MAX_TRANSITIONS) {
     getState().transitions.shift();
@@ -618,10 +681,12 @@ function waitForTransition(event, timeoutMs = 1e4) {
 }
 function bindEventBus(eventBus) {
   if (typeof window === "undefined") return;
+  log.info("bindEventBus", { hasOnAny: !!eventBus.onAny });
   exposeOnWindow();
   if (window.__orbitalVerification) {
     window.__orbitalVerification.sendEvent = (event, payload) => {
       const prefixed = event.startsWith("UI:") ? event : `UI:${event}`;
+      log.debug("sendEvent", { event: prefixed, payloadKeys: payload ? Object.keys(payload) : [] });
       eventBus.emit(prefixed, payload);
     };
     const eventLog = [];
@@ -1446,4 +1511,4 @@ function parseContentSegments(content) {
   return segments;
 }
 
-export { ApiError, DEFAULT_CONFIG, apiClient, bindCanvasCapture, bindEventBus, bindTraitStateGetter, clearDebugEvents, clearEntityProvider, clearGuardHistory, clearTicks, clearTraits, clearVerification, cn, debug, debugCollision, debugError, debugGameState, debugGroup, debugGroupEnd, debugInput, debugPhysics, debugTable, debugTime, debugTimeEnd, debugWarn, extractOutputsFromTransitions, extractStateMachine, formatGuard, formatNestedFieldLabel, getAllChecks, getAllTicks, getAllTraits, getBridgeHealth, getDebugEvents, getEffectSummary, getEntitiesByType, getEntityById, getEntitySnapshot, getEventsBySource, getEventsByType, getGuardEvaluationsForTrait, getGuardHistory, getNestedValue, getRecentEvents, getRecentGuardEvaluations, getSnapshot, getSummary, getTick, getTrait, getTransitions, getTransitionsForTrait, initDebugShortcut, isDebugEnabled, logDebugEvent, logEffectExecuted, logError, logEventFired, logInfo, logStateChange, logWarning, onDebugToggle, parseContentSegments, parseMarkdownWithCodeBlocks, recordGuardEvaluation, recordServerResponse, recordTransition, registerCheck, registerTick, registerTrait, renderStateMachineToDomData, renderStateMachineToSvg, setDebugEnabled, setEntityProvider, setTickActive, subscribeToDebugEvents, subscribeToGuardChanges, subscribeToTickChanges, subscribeToTraitChanges, subscribeToVerification, toggleDebug, unregisterTick, unregisterTrait, updateAssetStatus, updateBridgeHealth, updateCheck, updateGuardResult, updateTickExecution, updateTraitState, waitForTransition };
+export { ApiError, DEFAULT_CONFIG, apiClient, bindCanvasCapture, bindEventBus, bindTraitStateGetter, clearDebugEvents, clearEntityProvider, clearGuardHistory, clearTicks, clearTraits, clearVerification, cn, createLogger, debug, debugCollision, debugError, debugGameState, debugGroup, debugGroupEnd, debugInput, debugPhysics, debugTable, debugTime, debugTimeEnd, debugWarn, extractOutputsFromTransitions, extractStateMachine, formatGuard, formatNestedFieldLabel, generateCorrelationId, getAllChecks, getAllTicks, getAllTraits, getBridgeHealth, getDebugEvents, getEffectSummary, getEntitiesByType, getEntityById, getEntitySnapshot, getEventsBySource, getEventsByType, getGuardEvaluationsForTrait, getGuardHistory, getNestedValue, getRecentEvents, getRecentGuardEvaluations, getSnapshot, getSummary, getTick, getTrait, getTransitions, getTransitionsForTrait, initDebugShortcut, isDebugEnabled, logDebugEvent, logEffectExecuted, logError, logEventFired, logInfo, logStateChange, logWarning, onDebugToggle, parseContentSegments, parseMarkdownWithCodeBlocks, recordGuardEvaluation, recordServerResponse, recordTransition, registerCheck, registerTick, registerTrait, renderStateMachineToDomData, renderStateMachineToSvg, setDebugEnabled, setEntityProvider, setTickActive, subscribeToDebugEvents, subscribeToGuardChanges, subscribeToTickChanges, subscribeToTraitChanges, subscribeToVerification, toggleDebug, unregisterTick, unregisterTrait, updateAssetStatus, updateBridgeHealth, updateCheck, updateGuardResult, updateTickExecution, updateTraitState, waitForTransition };

package/dist/lib/logger.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Almadar Structured Logger
+ *
+ * Namespace-based logging with level gating and correlation IDs.
+ * Pure TypeScript, zero React dependencies. Works in Node.js, Vite, and browser.
+ *
+ * @packageDocumentation
+ */
+export interface Logger {
+    debug: (msg: string, data?: Record<string, unknown>, cid?: string) => void;
+    info: (msg: string, data?: Record<string, unknown>, cid?: string) => void;
+    warn: (msg: string, data?: Record<string, unknown>, cid?: string) => void;
+    error: (msg: string, data?: Record<string, unknown>, cid?: string) => void;
+}
+export declare function createLogger(namespace: string): Logger;
+export declare function generateCorrelationId(): string;

package/dist/marketing/index.cjs

@@ -4,6 +4,7 @@ var React5 = require('react');
 var jsxRuntime = require('react/jsx-runtime');
 var LucideIcons = require('lucide-react');
 
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
 function _interopNamespace(e) {
@@ -2506,9 +2507,70 @@ var twMerge = /* @__PURE__ */ createTailwindMerge(getDefaultConfig);
 function cn(...inputs) {
   return twMerge(clsx(inputs));
 }
+
+// lib/logger.ts
+var LEVEL_PRIORITY = { DEBUG: 0, INFO: 1, WARN: 2, ERROR: 3 };
+var ENV = typeof process !== "undefined" && process.env ? process.env : {};
+var VITE_ENV = typeof globalThis !== "undefined" && globalThis.__vite_env__ ? globalThis.__vite_env__ : {};
+function getViteEnv(key) {
+  try {
+    const meta = ({ url: (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)) });
+    return meta?.env?.[key];
+  } catch {
+    return void 0;
+  }
+}
+function envGet(key, viteKey) {
+  return ENV[key] ?? (viteKey ? getViteEnv(viteKey) : void 0) ?? VITE_ENV[viteKey ?? key];
+}
+var NODE_ENV = envGet("NODE_ENV", "VITE_NODE_ENV") ?? "development";
+var CONFIGURED_LEVEL = (envGet("LOG_LEVEL", "VITE_LOG_LEVEL") ?? (NODE_ENV === "production" ? "info" : "debug")).toUpperCase();
+var MIN_PRIORITY = LEVEL_PRIORITY[CONFIGURED_LEVEL] ?? 0;
+var DEBUG_FILTER = (envGet("ALMADAR_DEBUG", "VITE_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 log2 = (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) => log2("DEBUG", msg, data, cid),
+    info: (msg, data, cid) => log2("INFO", msg, data, cid),
+    warn: (msg, data, cid) => log2("WARN", msg, data, cid),
+    error: (msg, data, cid) => log2("ERROR", msg, data, cid)
+  };
+}
+createLogger("almadar:eventbus");
+createLogger("almadar:eventbus:subscribe");
 var EventBusContext = React5.createContext(null);
 
 // hooks/useEventBus.ts
+var log = createLogger("almadar:eventbus");
+var subLog2 = createLogger("almadar:eventbus:subscribe");
 function getGlobalEventBus() {
   if (typeof window !== "undefined") {
     return window.__kflowEventBus ?? null;
@@ -2525,6 +2587,7 @@ var fallbackEventBus = {
       timestamp: Date.now()
     };
     const handlers = fallbackListeners.get(type);
+    log.debug("emit", { type, payloadKeys: payload ? Object.keys(payload).length : 0, listenerCount: (handlers?.size ?? 0) + fallbackAnyListeners.size });
     if (handlers) {
       handlers.forEach((handler) => {
         try {
@@ -2547,6 +2610,7 @@ var fallbackEventBus = {
       fallbackListeners.set(type, /* @__PURE__ */ new Set());
     }
     fallbackListeners.get(type).add(listener);
+    subLog2.debug("subscribe", { type, totalListeners: fallbackListeners.get(type).size });
     return () => {
       const handlers = fallbackListeners.get(type);
       if (handlers) {
@@ -2570,6 +2634,7 @@ var fallbackEventBus = {
   },
   onAny: (listener) => {
     fallbackAnyListeners.add(listener);
+    subLog2.debug("subscribe:any", { totalAnyListeners: fallbackAnyListeners.size });
     return () => {
       fallbackAnyListeners.delete(listener);
     };

package/dist/marketing/index.js

@@ -2482,9 +2482,70 @@ var twMerge = /* @__PURE__ */ createTailwindMerge(getDefaultConfig);
 function cn(...inputs) {
   return twMerge(clsx(inputs));
 }
+
+// lib/logger.ts
+var LEVEL_PRIORITY = { DEBUG: 0, INFO: 1, WARN: 2, ERROR: 3 };
+var ENV = typeof process !== "undefined" && process.env ? process.env : {};
+var VITE_ENV = typeof globalThis !== "undefined" && globalThis.__vite_env__ ? globalThis.__vite_env__ : {};
+function getViteEnv(key) {
+  try {
+    const meta = import.meta;
+    return meta?.env?.[key];
+  } catch {
+    return void 0;
+  }
+}
+function envGet(key, viteKey) {
+  return ENV[key] ?? (viteKey ? getViteEnv(viteKey) : void 0) ?? VITE_ENV[viteKey ?? key];
+}
+var NODE_ENV = envGet("NODE_ENV", "VITE_NODE_ENV") ?? "development";
+var CONFIGURED_LEVEL = (envGet("LOG_LEVEL", "VITE_LOG_LEVEL") ?? (NODE_ENV === "production" ? "info" : "debug")).toUpperCase();
+var MIN_PRIORITY = LEVEL_PRIORITY[CONFIGURED_LEVEL] ?? 0;
+var DEBUG_FILTER = (envGet("ALMADAR_DEBUG", "VITE_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 log2 = (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) => log2("DEBUG", msg, data, cid),
+    info: (msg, data, cid) => log2("INFO", msg, data, cid),
+    warn: (msg, data, cid) => log2("WARN", msg, data, cid),
+    error: (msg, data, cid) => log2("ERROR", msg, data, cid)
+  };
+}
+createLogger("almadar:eventbus");
+createLogger("almadar:eventbus:subscribe");
 var EventBusContext = createContext(null);
 
 // hooks/useEventBus.ts
+var log = createLogger("almadar:eventbus");
+var subLog2 = createLogger("almadar:eventbus:subscribe");
 function getGlobalEventBus() {
   if (typeof window !== "undefined") {
     return window.__kflowEventBus ?? null;
@@ -2501,6 +2562,7 @@ var fallbackEventBus = {
       timestamp: Date.now()
     };
     const handlers = fallbackListeners.get(type);
+    log.debug("emit", { type, payloadKeys: payload ? Object.keys(payload).length : 0, listenerCount: (handlers?.size ?? 0) + fallbackAnyListeners.size });
     if (handlers) {
       handlers.forEach((handler) => {
         try {
@@ -2523,6 +2585,7 @@ var fallbackEventBus = {
       fallbackListeners.set(type, /* @__PURE__ */ new Set());
     }
     fallbackListeners.get(type).add(listener);
+    subLog2.debug("subscribe", { type, totalListeners: fallbackListeners.get(type).size });
     return () => {
       const handlers = fallbackListeners.get(type);
       if (handlers) {
@@ -2546,6 +2609,7 @@ var fallbackEventBus = {
   },
   onAny: (listener) => {
     fallbackAnyListeners.add(listener);
+    subLog2.debug("subscribe:any", { totalAnyListeners: fallbackAnyListeners.size });
     return () => {
       fallbackAnyListeners.delete(listener);
     };