@almadar/ui 4.6.13 → 4.7.0

package/dist/runtime/index.js

@@ -1071,13 +1071,23 @@ function SlotsProvider({ children }) {
   const setSlotPatterns = useCallback((slot, patterns, source) => {
     const sourceKey = source?.trait ?? DEFAULT_SOURCE_KEY;
     const entityProp = patterns[0]?.pattern && typeof patterns[0].pattern === "object" ? patterns[0].pattern.entity : void 0;
+    const firstPatternType = patterns[0]?.pattern && typeof patterns[0].pattern === "object" ? patterns[0].pattern.type : void 0;
     slotLog.debug("setSlotPatterns", {
       slot,
       sourceKey,
       patternCount: patterns.length,
-      firstPatternType: patterns[0]?.pattern && typeof patterns[0].pattern === "object" ? patterns[0].pattern.type : void 0,
+      firstPatternType,
       entityRefId: refId(entityProp)
     });
+    if (source?.trait) {
+      xOrbitalLog.info("slot-set", {
+        slot,
+        sourceTrait: source.trait,
+        patternCount: patterns.length,
+        firstPatternType,
+        state: source.state
+      });
+    }
     setSlots((prev) => {
       const prevSlot = prev[slot] ?? {};
       return {
@@ -1099,6 +1109,7 @@ function SlotsProvider({ children }) {
     });
   }, []);
   const clearSlotForSource = useCallback((slot, sourceTrait) => {
+    xOrbitalLog.info("slot-clear-source", { slot, sourceTrait });
     setSlots((prev) => {
       const existing = prev[slot];
       if (!existing || !(sourceTrait in existing)) return prev;
@@ -1139,11 +1150,12 @@ function useSlotsActions() {
   }
   return actions;
 }
-var slotLog, refIds, nextRefId, DEFAULT_SOURCE_KEY, SlotsStateContext, SlotsActionsContext;
+var slotLog, xOrbitalLog, refIds, nextRefId, DEFAULT_SOURCE_KEY, SlotsStateContext, SlotsActionsContext;
 var init_SlotsContext = __esm({
   "runtime/ui/SlotsContext.tsx"() {
     init_logger();
     slotLog = createLogger("almadar:ui:slot-render");
+    xOrbitalLog = createLogger("almadar:runtime:cross-orbital");
     refIds = /* @__PURE__ */ new WeakMap();
     nextRefId = 1;
     DEFAULT_SOURCE_KEY = "__default__";
@@ -8137,7 +8149,7 @@ var init_MapView = __esm({
         shadowSize: [41, 41]
       });
       L.Marker.prototype.options.icon = defaultIcon;
-      const { useEffect: useEffect68, useRef: useRef65, useCallback: useCallback110, useState: useState103 } = React115__default;
+      const { useEffect: useEffect68, useRef: useRef65, useCallback: useCallback110, useState: useState102 } = React115__default;
       const { Typography: Typography2 } = await Promise.resolve().then(() => (init_Typography(), Typography_exports));
       const { useEventBus: useEventBus2 } = await Promise.resolve().then(() => (init_useEventBus(), useEventBus_exports));
       function MapUpdater({ centerLat, centerLng, zoom }) {
@@ -8181,7 +8193,7 @@ var init_MapView = __esm({
         showAttribution = true
       }) {
         const eventBus = useEventBus2();
-        const [clickedPosition, setClickedPosition] = useState103(null);
+        const [clickedPosition, setClickedPosition] = useState102(null);
         const handleMapClick = useCallback110((lat, lng) => {
           if (showClickedPin) {
             setClickedPosition({ lat, lng });
@@ -38134,6 +38146,7 @@ function useTraitStateMachine(traitBindings, slotsActions, options) {
   const eventBus = useEventBus();
   const { entities } = useEntitySchema();
   const traitConfigsByName = options?.traitConfigsByName;
+  const orbitalsByTrait = options?.orbitalsByTrait;
   const manager = useMemo(() => {
     const traitDefs = traitBindings.map(toTraitDefinition);
     const m = new StateMachineManager(traitDefs);
@@ -38346,24 +38359,7 @@ function useTraitStateMachine(traitBindings, slotsActions, options) {
     const actions = slotsActionsRef.current;
     console.log("[TraitStateMachine] Processing event:", normalizedEvent, "payload:", payload);
     const bindingMap = new Map(bindings.map((b) => [b.trait.name, b]));
-    for (const traitName of bindingMap.keys()) {
-      const traitState = currentManager.getState(traitName);
-      eventBus.emit(`${traitName}:DISPATCH`, {
-        event: normalizedEvent,
-        payload,
-        currentState: traitState?.currentState
-      });
-    }
     const results = currentManager.sendEvent(normalizedEvent, payload);
-    for (const { traitName, result } of results) {
-      const suffix = result.executed ? "SUCCESS" : "ERROR";
-      eventBus.emit(`${traitName}:${normalizedEvent}:${suffix}`, {
-        event: normalizedEvent,
-        payload,
-        newState: result.newState,
-        currentState: result.previousState
-      });
-    }
     const emittedByTrait = /* @__PURE__ */ new Map();
     for (const { traitName, result } of results) {
       const binding = bindingMap.get(traitName);
@@ -38599,7 +38595,10 @@ function useTraitStateMachine(traitBindings, slotsActions, options) {
     if (!LIFECYCLE_EVENTS.has(normalizedEvent)) {
       for (const { traitName, result } of results) {
         if (!result.executed) continue;
-        eventBus.emit(normalizedEvent, payload, {
+        const orbitalName = orbitalsByTrait?.[traitName];
+        if (!orbitalName) continue;
+        eventBus.emit(`UI:${orbitalName}.${traitName}.${normalizedEvent}`, payload, {
+          orbital: orbitalName,
           trait: traitName,
           fromBridge: true
         });
@@ -38610,7 +38609,13 @@ function useTraitStateMachine(traitBindings, slotsActions, options) {
     }
     const onEventProcessed = optionsRef.current?.onEventProcessed;
     if (onEventProcessed) {
-      await onEventProcessed(normalizedEvent, payload);
+      const dispatchedOrbitals = /* @__PURE__ */ new Set();
+      for (const { traitName, result } of results) {
+        if (!result.executed) continue;
+        const orbital = orbitalsByTrait?.[traitName];
+        if (orbital) dispatchedOrbitals.add(orbital);
+      }
+      await onEventProcessed(normalizedEvent, payload, dispatchedOrbitals);
     }
   }, [entities, eventBus]);
   const drainEventQueue = useCallback(async () => {
@@ -38654,26 +38659,34 @@ function useTraitStateMachine(traitBindings, slotsActions, options) {
     }
     console.log("[TraitStateMachine] Subscribing to events:", Array.from(allEvents));
     const unsubscribes = [];
-    for (const eventKey of allEvents) {
-      if (eventKey === "INIT" || eventKey === "LOAD" || eventKey === "$MOUNT") {
-        continue;
+    for (const binding of traitBindings) {
+      const traitName = binding.trait.name;
+      const orbitalName = orbitalsByTrait?.[traitName];
+      if (!orbitalName) continue;
+      for (const transition of binding.trait.transitions) {
+        const eventKey = transition.event;
+        if (eventKey === "INIT" || eventKey === "LOAD" || eventKey === "$MOUNT") {
+          continue;
+        }
+        const unsub = eventBus.on(`UI:${orbitalName}.${traitName}.${eventKey}`, (event) => {
+          if (event.source && event.source.fromBridge) {
+            return;
+          }
+          enqueueAndDrain(eventKey, event.payload);
+        });
+        unsubscribes.push(unsub);
       }
-      const unsub = eventBus.on(`UI:${eventKey}`, (event) => {
-        console.log("[TraitStateMachine] Received event:", `UI:${eventKey}`, event);
-        enqueueAndDrain(eventKey, event.payload);
-      });
-      unsubscribes.push(unsub);
     }
     for (const binding of traitBindings) {
+      const ownOrbital = orbitalsByTrait?.[binding.trait.name];
       const listens = binding.trait.listens ?? [];
       for (const listen of listens) {
-        const expectedTrait = listen.source?.trait;
-        const unsub = eventBus.on(listen.event, (event) => {
-          if (expectedTrait) {
-            const emitTrait = event.source?.trait;
-            if (emitTrait !== expectedTrait) return;
-          }
-          console.log("[TraitStateMachine] listens", binding.trait.name, listen.event, "\u2192", listen.triggers, "from", event.source?.trait);
+        const sourceTrait = listen.source?.trait;
+        if (!sourceTrait) continue;
+        const sourceOrbital = listen.source?.orbital ?? ownOrbital;
+        if (!sourceOrbital) continue;
+        const busKey = `UI:${sourceOrbital}.${sourceTrait}.${listen.event}`;
+        const unsub = eventBus.on(busKey, (event) => {
           enqueueAndDrain(listen.triggers, event.payload);
         });
         unsubscribes.push(unsub);
@@ -38820,6 +38833,8 @@ init_EntitySchemaContext();
 
 // runtime/ServerBridge.tsx
 init_useEventBus();
+init_logger();
+var xOrbitalLog2 = createLogger("almadar:runtime:cross-orbital");
 var ServerBridgeContext = createContext(null);
 function useServerBridge() {
   const ctx = useContext(ServerBridgeContext);
@@ -38897,8 +38912,22 @@ function ServerBridgeProvider({
         }
         if (result.emittedEvents) {
           for (const emitted of result.emittedEvents) {
-            eventBus.emit(`UI:${emitted.event}`, emitted.payload);
-            eventBus.emit(emitted.event, emitted.payload);
+            const evTrait = emitted.source?.trait;
+            if (!evTrait) {
+              xOrbitalLog2.warn("emit:dropped-no-source", {
+                event: emitted.event,
+                dispatchOrbital: orbitalName
+              });
+              continue;
+            }
+            const key = emitted.source?.orbital ? `UI:${emitted.source.orbital}.${evTrait}.${emitted.event}` : `UI:${evTrait}.${emitted.event}`;
+            xOrbitalLog2.info("emit:rebroadcast", {
+              busKey: key,
+              sourceOrbital: emitted.source?.orbital,
+              sourceTrait: evTrait,
+              dispatchOrbital: orbitalName
+            });
+            eventBus.emit(key, emitted.payload);
           }
         }
       } else if (result.error) {
@@ -39019,6 +39048,10 @@ function prepareSchemaForPreview(input) {
   const schema = adjustSchemaForMockData(parsed, mockData);
   return { schema, mockData };
 }
+
+// runtime/OrbPreview.tsx
+init_logger();
+var xOrbitalLog3 = createLogger("almadar:runtime:cross-orbital");
 function normalizeChild(child) {
   if (typeof child === "string") return child;
   if (child === null || typeof child !== "object" || Array.isArray(child)) {
@@ -39098,6 +39131,11 @@ function applyServerEffects(effects, uiSlots, onNavigate) {
       const patternRecord = eff.pattern;
       const { type: patternType, children, ...inlineProps } = patternRecord;
       const normalizedChildren = Array.isArray(children) ? children.map((c) => normalizeChild(c)) : children;
+      xOrbitalLog3.info("slot-write", {
+        slot: eff.slot,
+        sourceTrait: eff.traitName ?? "server",
+        patternType: typeof patternType === "string" ? patternType : void 0
+      });
       uiSlots.render({
         target: eff.slot,
         pattern: patternType,
@@ -39112,19 +39150,26 @@ function applyServerEffects(effects, uiSlots, onNavigate) {
     }
   }
 }
-function TraitInitializer({ traits: traits2, orbitalNames, onNavigate, onLocalFallback, persistence, traitConfigsByName }) {
+function TraitInitializer({ traits: traits2, orbitalNames, onNavigate, onLocalFallback, persistence, traitConfigsByName, orbitalsByTrait }) {
   const slotsActions = useSlotsActions();
   const bridge = useServerBridge();
   const uiSlots = useUISlots();
-  const onEventProcessed = useCallback(async (event, payload) => {
+  const onEventProcessed = useCallback(async (event, payload, dispatchedOrbitals) => {
     if (!bridge.connected || !orbitalNames?.length) return;
-    for (const name of orbitalNames) {
+    const targets = dispatchedOrbitals && dispatchedOrbitals.size > 0 ? orbitalNames.filter((n) => dispatchedOrbitals.has(n)) : orbitalNames;
+    xOrbitalLog3.info("TraitInitializer:fanout", {
+      event,
+      sentTo: targets,
+      skipped: orbitalNames.filter((n) => !targets.includes(n)),
+      dispatchedOrbitalsSize: dispatchedOrbitals?.size ?? 0
+    });
+    for (const name of targets) {
       const { effects, meta } = await bridge.sendEvent(name, event, payload);
       recordServerResponse(name, event, meta);
       applyServerEffects(effects, uiSlots, onNavigate);
     }
   }, [bridge.connected, bridge.sendEvent, orbitalNames, uiSlots, onNavigate]);
-  const opts = orbitalNames ? { onEventProcessed, navigate: onNavigate, traitConfigsByName } : { navigate: onNavigate, persistence, traitConfigsByName };
+  const opts = orbitalNames ? { onEventProcessed, navigate: onNavigate, traitConfigsByName, orbitalsByTrait } : { navigate: onNavigate, persistence, traitConfigsByName, orbitalsByTrait };
   const { sendEvent } = useTraitStateMachine(traits2, slotsActions, opts);
   const initSentRef = useRef(false);
   useEffect(() => {
@@ -39174,27 +39219,68 @@ function SchemaRunner({ schema, serverUrl, mockData, pageName, onNavigate, onLoc
   const allPageTraits = useMemo(() => {
     if (pageName && traits2.length > 0) return traits2;
     if (!ir?.pages || ir.pages.size <= 1) return traits2;
-    const combined = [];
+    const firstPage = ir.pages.values().next().value;
+    if (!firstPage) return traits2;
+    const firstPageTraits = [];
     const seen = /* @__PURE__ */ new Set();
-    for (const page of ir.pages.values()) {
-      for (const t of page.traits) {
-        const binding = t;
-        const traitObj = binding.trait;
-        const name = traitObj?.name ?? binding.name ?? "";
-        if (name && !seen.has(name)) {
-          seen.add(name);
-          combined.push(t);
-        }
+    for (const binding of firstPage.traits) {
+      const name = binding.trait.name;
+      if (name && !seen.has(name)) {
+        seen.add(name);
+        firstPageTraits.push(binding);
       }
     }
-    return combined.length > 0 ? combined : traits2;
+    return firstPageTraits.length > 0 ? firstPageTraits : traits2;
   }, [ir, traits2, pageName]);
-  const orbitalNames = useMemo(() => {
+  useMemo(() => {
     const parsed = schema;
     const orbitals = parsed?.orbitals;
     if (!orbitals) return [];
     return orbitals.filter((o) => typeof o.name === "string").map((o) => o.name);
   }, [schema]);
+  const orbitalsByTrait = useMemo(() => {
+    const map = {};
+    const parsed = schema;
+    if (!parsed?.orbitals) return map;
+    for (const orb of parsed.orbitals) {
+      for (const traitRef of orb.traits) {
+        let traitName;
+        if (typeof traitRef === "string") {
+          const parts = traitRef.split(".");
+          traitName = parts[parts.length - 1];
+        } else if ("ref" in traitRef && typeof traitRef.ref === "string") {
+          const parts = traitRef.ref.split(".");
+          traitName = traitRef.name ?? parts[parts.length - 1];
+        } else if ("name" in traitRef && typeof traitRef.name === "string") {
+          traitName = traitRef.name;
+        }
+        if (traitName) map[traitName] = orb.name;
+      }
+    }
+    return map;
+  }, [schema]);
+  const pageOrbitalNames = useMemo(() => {
+    const set = /* @__PURE__ */ new Set();
+    for (const binding of allPageTraits) {
+      const orb = orbitalsByTrait[binding.trait.name];
+      if (orb) set.add(orb);
+    }
+    return Array.from(set);
+  }, [allPageTraits, orbitalsByTrait]);
+  useEffect(() => {
+    const traitNames = allPageTraits.map((b) => b.trait.name);
+    const orbitalsByTraitForPage = {};
+    for (const name of traitNames) {
+      const orb = orbitalsByTrait[name];
+      if (orb) orbitalsByTraitForPage[name] = orb;
+    }
+    xOrbitalLog3.info("SchemaRunner:mount", {
+      pageName,
+      traitNames,
+      orbitalsByTraitForPage,
+      pageOrbitalNames: pageOrbitalNames.join(",")
+    });
+  }, [pageName, allPageTraits, orbitalsByTrait, pageOrbitalNames]);
   const traitConfigsByName = useMemo(() => {
     const map = {};
     const parsed = schema;
@@ -39235,8 +39321,9 @@ function SchemaRunner({ schema, serverUrl, mockData, pageName, onNavigate, onLoc
           TraitInitializer,
           {
             traits: allPageTraits,
-            orbitalNames: serverUrl ? orbitalNames : void 0,
+            orbitalNames: serverUrl ? pageOrbitalNames : void 0,
             traitConfigsByName,
+            orbitalsByTrait,
             onNavigate,
             onLocalFallback,
             persistence
@@ -39258,7 +39345,8 @@ function OrbPreview({
   autoMock = false,
   height = "400px",
   className,
-  serverUrl
+  serverUrl,
+  initialPagePath
 }) {
   const [localFallback, setLocalFallback] = useState(false);
   const eventBus = useEventBus();
@@ -39304,7 +39392,17 @@ function OrbPreview({
       return [];
     }
   }, [parsedSchema]);
-  const [currentPage, setCurrentPage] = useState(void 0);
+  const initialPageName = useMemo(() => {
+    if (!initialPagePath) return void 0;
+    const match = pages.find(({ page }) => page.path === initialPagePath);
+    return match?.page.name;
+  }, [pages, initialPagePath]);
+  const [currentPage, setCurrentPage] = useState(initialPageName);
+  useEffect(() => {
+    if (initialPageName && initialPageName !== currentPage) {
+      setCurrentPage(initialPageName);
+    }
+  }, [initialPageName, currentPage]);
   const handleNavigate = useCallback((path) => {
     const match = pages.find(({ page }) => page.path === path);
     if (match) {

package/dist/runtime/useTraitStateMachine.d.ts

@@ -32,8 +32,18 @@ export interface TraitStateMachineResult {
     canHandleEvent: (traitName: string, eventKey: string) => boolean;
 }
 export interface UseTraitStateMachineOptions {
-    /** Callback invoked after each event is processed (for server forwarding) */
-    onEventProcessed?: (eventKey: string, payload?: EventPayload) => void | Promise<void>;
+    /**
+     * Callback invoked after each event is processed (for server forwarding).
+     *
+     * `dispatchedOrbitals` is the set of orbital names whose traits actually
+     * executed a transition for this event. The server-bridge fan-out should
+     * be scoped to this set; sending the event to other orbitals fires
+     * same-named transitions in unrelated orbitals and stacks their UI into
+     * the wrong slot (gap #11 in `docs/Almadar_Std_Verification.md`). Empty
+     * set means no local transition matched — leave the legacy fallback to
+     * the consumer.
+     */
+    onEventProcessed?: (eventKey: string, payload?: EventPayload, dispatchedOrbitals?: Set<string>) => void | Promise<void>;
     /** Router navigate function for navigate effects */
     navigate?: (path: string, params?: Record<string, unknown>) => void;
     /** Notification function for notify effects */
@@ -57,6 +67,15 @@ export interface UseTraitStateMachineOptions {
      * caller assembles this map from the orbital schema directly.
      */
     traitConfigsByName?: Record<string, import('@almadar/core').TraitConfig>;
+    /**
+     * Trait → orbital map built from `schema.orbitals[].traits[]` by the
+     * caller. Threaded down so bus emits (`UI:Orbital.Trait.Event`) and
+     * subscriptions can carry the qualified `Orbital.Trait` scope —
+     * gap #13 unification. Same mechanism as `traitConfigsByName`: the
+     * orbital boundary doesn't propagate through `@almadar/core`'s
+     * `ResolvedTraitBinding`, so the caller assembles the map directly.
+     */
+    orbitalsByTrait?: Record<string, string>;
 }
 /**
  * useTraitStateMachine - Manages state machines for multiple traits

package/package.json

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