@almadar/ui 5.9.7 → 5.9.9

package/dist/avl/index.cjs

@@ -14619,7 +14619,7 @@ var init_MapView = __esm({
         shadowSize: [41, 41]
       });
       L.Marker.prototype.options.icon = defaultIcon;
-      const { useEffect: useEffect89, useRef: useRef88, useCallback: useCallback129, useState: useState124 } = React98__namespace.default;
+      const { useEffect: useEffect89, useRef: useRef88, useCallback: useCallback130, useState: useState124 } = React98__namespace.default;
       const { Typography: Typography2 } = await Promise.resolve().then(() => (init_Typography(), Typography_exports));
       const { useEventBus: useEventBus3 } = await Promise.resolve().then(() => (init_useEventBus(), useEventBus_exports));
       function MapUpdater({ centerLat, centerLng, zoom }) {
@@ -14665,7 +14665,7 @@ var init_MapView = __esm({
       }) {
         const eventBus = useEventBus3();
         const [clickedPosition, setClickedPosition] = useState124(null);
-        const handleMapClick = useCallback129((lat, lng) => {
+        const handleMapClick = useCallback130((lat, lng) => {
           if (showClickedPin) {
             setClickedPosition({ lat, lng });
           }
@@ -14674,7 +14674,7 @@ var init_MapView = __esm({
             eventBus.emit(`UI:${mapClickEvent}`, { latitude: lat, longitude: lng });
           }
         }, [onMapClick, mapClickEvent, eventBus, showClickedPin]);
-        const handleMarkerClick = useCallback129((marker) => {
+        const handleMarkerClick = useCallback130((marker) => {
           onMarkerClick?.(marker);
           if (markerClickEvent) {
             eventBus.emit(`UI:${markerClickEvent}`, { ...marker });
@@ -30399,12 +30399,15 @@ function GameCanvas2D({
   tickEvent,
   drawEvent,
   fps = 60,
+  backgroundImage,
+  assetBaseUrl = "",
   className
 }) {
   const canvasRef = React98__namespace.useRef(null);
   const rafRef = React98__namespace.useRef(0);
   const frameRef = React98__namespace.useRef(0);
   const lastTimeRef = React98__namespace.useRef(0);
+  const imageCache = React98__namespace.useRef(/* @__PURE__ */ new Map());
   const emit = useEmitEvent();
   const onDrawRef = React98__namespace.useRef(onDraw);
   onDrawRef.current = onDraw;
@@ -30416,6 +30419,18 @@ function GameCanvas2D({
   drawEventRef.current = drawEvent;
   const emitRef = React98__namespace.useRef(emit);
   emitRef.current = emit;
+  const loadImage = React98__namespace.useCallback((url) => {
+    const fullUrl = url.startsWith("http") ? url : `${assetBaseUrl}${url}`;
+    const cached = imageCache.current.get(fullUrl);
+    if (cached?.complete && cached.naturalWidth > 0) return cached;
+    if (!cached) {
+      const img = new Image();
+      img.crossOrigin = "anonymous";
+      img.src = fullUrl;
+      imageCache.current.set(fullUrl, img);
+    }
+    return null;
+  }, [assetBaseUrl]);
   React98__namespace.useEffect(() => {
     const canvas = canvasRef.current;
     if (!canvas) return;
@@ -30437,6 +30452,12 @@ function GameCanvas2D({
         if (tickEventRef.current) {
           emitRef.current(tickEventRef.current, { dt, frame });
         }
+        if (backgroundImage) {
+          const bgImg = loadImage(backgroundImage);
+          if (bgImg) {
+            ctx.drawImage(bgImg, 0, 0, width, height);
+          }
+        }
         onDrawRef.current?.(ctx, frame);
         if (drawEventRef.current) {
           emitRef.current(drawEventRef.current, { frame });
@@ -60012,6 +60033,16 @@ function collectTraitRefsFromEffects(effects, into) {
     }
   }
 }
+function collectTraitRefsFromResolvedTrait(trait) {
+  const out = /* @__PURE__ */ new Set();
+  for (const transition of trait.transitions ?? []) {
+    collectTraitRefsFromEffects(transition.effects, out);
+  }
+  for (const tick of trait.ticks ?? []) {
+    collectTraitRefsFromEffects(tick.effects, out);
+  }
+  return out;
+}
 function collectEmbeddedTraits(schema) {
   const out = /* @__PURE__ */ new Set();
   if (!schema?.orbitals) return out;
@@ -60902,6 +60933,40 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
   };
 }
 
+// runtime/orbitalsByTrait.ts
+function buildOrbitalsByTrait(schema, resolvedPages = []) {
+  const map = {};
+  if (!schema?.orbitals) return map;
+  const pagePathToOrbital = {};
+  for (const orb of schema.orbitals) {
+    for (const traitRef of orb.traits ?? []) {
+      let traitName;
+      if (typeof traitRef === "string") {
+        const parts = traitRef.split(".");
+        traitName = parts[parts.length - 1];
+      } else if (typeof traitRef.ref === "string") {
+        const parts = traitRef.ref.split(".");
+        traitName = traitRef.name ?? parts[parts.length - 1];
+      } else if (typeof traitRef.name === "string") {
+        traitName = traitRef.name;
+      }
+      if (traitName) map[traitName] = orb.name;
+    }
+    for (const pg of orb.pages ?? []) {
+      const path = typeof pg === "string" ? pg : pg?.path;
+      if (path) pagePathToOrbital[path] = orb.name;
+    }
+  }
+  for (const page of resolvedPages) {
+    const orbital = page.path ? pagePathToOrbital[page.path] : void 0;
+    if (!orbital) continue;
+    for (const traitName of page.traitNames) {
+      if (traitName && !(traitName in map)) map[traitName] = orbital;
+    }
+  }
+  return map;
+}
+
 // runtime/OrbPreview.tsx
 init_EntitySchemaContext();
 
@@ -61637,50 +61702,64 @@ function TraitInitializer({ traits: traits2, orbitalNames, onNavigate, onLocalFa
   return null;
 }
 function SchemaRunner({ schema, serverUrl, transport, mockData, pageName, onNavigate, onLocalFallback, persistence }) {
-  const { traits: traits2, allEntities, ir } = useResolvedSchema(schema, pageName);
+  const { traits: traits2, allEntities, allTraits, ir } = useResolvedSchema(schema, pageName);
   const allPageTraits = React98.useMemo(() => {
-    if (pageName && traits2.length > 0) return traits2;
-    if (!ir?.pages || ir.pages.size <= 1) return traits2;
-    const firstPage = ir.pages.values().next().value;
-    if (!firstPage) return traits2;
-    const firstPageTraits = [];
-    const seen = /* @__PURE__ */ new Set();
-    for (const binding of firstPage.traits) {
-      const name = binding.trait.name;
-      if (name && !seen.has(name)) {
-        seen.add(name);
-        firstPageTraits.push(binding);
-      }
-    }
-    return firstPageTraits.length > 0 ? firstPageTraits : traits2;
-  }, [ir, traits2, pageName]);
+    let base;
+    if (pageName && traits2.length > 0) {
+      base = traits2;
+    } else if (!ir?.pages || ir.pages.size <= 1) {
+      base = traits2;
+    } else {
+      const firstPage = ir.pages.values().next().value;
+      if (!firstPage) {
+        base = traits2;
+      } else {
+        const firstPageTraits = [];
+        const seen = /* @__PURE__ */ new Set();
+        for (const binding of firstPage.traits) {
+          const name = binding.trait.name;
+          if (name && !seen.has(name)) {
+            seen.add(name);
+            firstPageTraits.push(binding);
+          }
+        }
+        base = firstPageTraits.length > 0 ? firstPageTraits : traits2;
+      }
+    }
+    const byName = new Set(base.map((b) => b.trait.name));
+    const extra = [];
+    const queue = [...base];
+    while (queue.length > 0) {
+      const binding = queue.shift();
+      if (!binding) continue;
+      for (const refName of collectTraitRefsFromResolvedTrait(binding.trait)) {
+        if (byName.has(refName)) continue;
+        const rt = allTraits.get(refName);
+        if (!rt) continue;
+        byName.add(refName);
+        const sibling = { trait: rt, linkedEntity: rt.linkedEntity };
+        extra.push(sibling);
+        queue.push(sibling);
+      }
+    }
+    return extra.length > 0 ? [...base, ...extra] : base;
+  }, [ir, traits2, pageName, allTraits]);
   React98.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 = React98.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 orbitalsByTrait = React98.useMemo(
+    () => buildOrbitalsByTrait(
+      schema,
+      ir ? Array.from(ir.pages.values()).map((p2) => ({
+        path: p2.path,
+        traitNames: p2.traits.map((b) => b.trait.name)
+      })) : []
+    ),
+    [schema, ir]
+  );
   const traitLinkedEntitiesMap = React98.useMemo(() => {
     const map = /* @__PURE__ */ new Map();
     if (ir) {

package/dist/avl/index.js

@@ -14570,7 +14570,7 @@ var init_MapView = __esm({
         shadowSize: [41, 41]
       });
       L.Marker.prototype.options.icon = defaultIcon;
-      const { useEffect: useEffect89, useRef: useRef88, useCallback: useCallback129, useState: useState124 } = React98__default;
+      const { useEffect: useEffect89, useRef: useRef88, useCallback: useCallback130, useState: useState124 } = React98__default;
       const { Typography: Typography2 } = await Promise.resolve().then(() => (init_Typography(), Typography_exports));
       const { useEventBus: useEventBus3 } = await Promise.resolve().then(() => (init_useEventBus(), useEventBus_exports));
       function MapUpdater({ centerLat, centerLng, zoom }) {
@@ -14616,7 +14616,7 @@ var init_MapView = __esm({
       }) {
         const eventBus = useEventBus3();
         const [clickedPosition, setClickedPosition] = useState124(null);
-        const handleMapClick = useCallback129((lat, lng) => {
+        const handleMapClick = useCallback130((lat, lng) => {
           if (showClickedPin) {
             setClickedPosition({ lat, lng });
           }
@@ -14625,7 +14625,7 @@ var init_MapView = __esm({
             eventBus.emit(`UI:${mapClickEvent}`, { latitude: lat, longitude: lng });
           }
         }, [onMapClick, mapClickEvent, eventBus, showClickedPin]);
-        const handleMarkerClick = useCallback129((marker) => {
+        const handleMarkerClick = useCallback130((marker) => {
           onMarkerClick?.(marker);
           if (markerClickEvent) {
             eventBus.emit(`UI:${markerClickEvent}`, { ...marker });
@@ -30350,12 +30350,15 @@ function GameCanvas2D({
   tickEvent,
   drawEvent,
   fps = 60,
+  backgroundImage,
+  assetBaseUrl = "",
   className
 }) {
   const canvasRef = React98.useRef(null);
   const rafRef = React98.useRef(0);
   const frameRef = React98.useRef(0);
   const lastTimeRef = React98.useRef(0);
+  const imageCache = React98.useRef(/* @__PURE__ */ new Map());
   const emit = useEmitEvent();
   const onDrawRef = React98.useRef(onDraw);
   onDrawRef.current = onDraw;
@@ -30367,6 +30370,18 @@ function GameCanvas2D({
   drawEventRef.current = drawEvent;
   const emitRef = React98.useRef(emit);
   emitRef.current = emit;
+  const loadImage = React98.useCallback((url) => {
+    const fullUrl = url.startsWith("http") ? url : `${assetBaseUrl}${url}`;
+    const cached = imageCache.current.get(fullUrl);
+    if (cached?.complete && cached.naturalWidth > 0) return cached;
+    if (!cached) {
+      const img = new Image();
+      img.crossOrigin = "anonymous";
+      img.src = fullUrl;
+      imageCache.current.set(fullUrl, img);
+    }
+    return null;
+  }, [assetBaseUrl]);
   React98.useEffect(() => {
     const canvas = canvasRef.current;
     if (!canvas) return;
@@ -30388,6 +30403,12 @@ function GameCanvas2D({
         if (tickEventRef.current) {
           emitRef.current(tickEventRef.current, { dt, frame });
         }
+        if (backgroundImage) {
+          const bgImg = loadImage(backgroundImage);
+          if (bgImg) {
+            ctx.drawImage(bgImg, 0, 0, width, height);
+          }
+        }
         onDrawRef.current?.(ctx, frame);
         if (drawEventRef.current) {
           emitRef.current(drawEventRef.current, { frame });
@@ -59963,6 +59984,16 @@ function collectTraitRefsFromEffects(effects, into) {
     }
   }
 }
+function collectTraitRefsFromResolvedTrait(trait) {
+  const out = /* @__PURE__ */ new Set();
+  for (const transition of trait.transitions ?? []) {
+    collectTraitRefsFromEffects(transition.effects, out);
+  }
+  for (const tick of trait.ticks ?? []) {
+    collectTraitRefsFromEffects(tick.effects, out);
+  }
+  return out;
+}
 function collectEmbeddedTraits(schema) {
   const out = /* @__PURE__ */ new Set();
   if (!schema?.orbitals) return out;
@@ -60853,6 +60884,40 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
   };
 }
 
+// runtime/orbitalsByTrait.ts
+function buildOrbitalsByTrait(schema, resolvedPages = []) {
+  const map = {};
+  if (!schema?.orbitals) return map;
+  const pagePathToOrbital = {};
+  for (const orb of schema.orbitals) {
+    for (const traitRef of orb.traits ?? []) {
+      let traitName;
+      if (typeof traitRef === "string") {
+        const parts = traitRef.split(".");
+        traitName = parts[parts.length - 1];
+      } else if (typeof traitRef.ref === "string") {
+        const parts = traitRef.ref.split(".");
+        traitName = traitRef.name ?? parts[parts.length - 1];
+      } else if (typeof traitRef.name === "string") {
+        traitName = traitRef.name;
+      }
+      if (traitName) map[traitName] = orb.name;
+    }
+    for (const pg of orb.pages ?? []) {
+      const path = typeof pg === "string" ? pg : pg?.path;
+      if (path) pagePathToOrbital[path] = orb.name;
+    }
+  }
+  for (const page of resolvedPages) {
+    const orbital = page.path ? pagePathToOrbital[page.path] : void 0;
+    if (!orbital) continue;
+    for (const traitName of page.traitNames) {
+      if (traitName && !(traitName in map)) map[traitName] = orbital;
+    }
+  }
+  return map;
+}
+
 // runtime/OrbPreview.tsx
 init_EntitySchemaContext();
 
@@ -61588,50 +61653,64 @@ function TraitInitializer({ traits: traits2, orbitalNames, onNavigate, onLocalFa
   return null;
 }
 function SchemaRunner({ schema, serverUrl, transport, mockData, pageName, onNavigate, onLocalFallback, persistence }) {
-  const { traits: traits2, allEntities, ir } = useResolvedSchema(schema, pageName);
+  const { traits: traits2, allEntities, allTraits, ir } = useResolvedSchema(schema, pageName);
   const allPageTraits = useMemo(() => {
-    if (pageName && traits2.length > 0) return traits2;
-    if (!ir?.pages || ir.pages.size <= 1) return traits2;
-    const firstPage = ir.pages.values().next().value;
-    if (!firstPage) return traits2;
-    const firstPageTraits = [];
-    const seen = /* @__PURE__ */ new Set();
-    for (const binding of firstPage.traits) {
-      const name = binding.trait.name;
-      if (name && !seen.has(name)) {
-        seen.add(name);
-        firstPageTraits.push(binding);
-      }
-    }
-    return firstPageTraits.length > 0 ? firstPageTraits : traits2;
-  }, [ir, traits2, pageName]);
+    let base;
+    if (pageName && traits2.length > 0) {
+      base = traits2;
+    } else if (!ir?.pages || ir.pages.size <= 1) {
+      base = traits2;
+    } else {
+      const firstPage = ir.pages.values().next().value;
+      if (!firstPage) {
+        base = traits2;
+      } else {
+        const firstPageTraits = [];
+        const seen = /* @__PURE__ */ new Set();
+        for (const binding of firstPage.traits) {
+          const name = binding.trait.name;
+          if (name && !seen.has(name)) {
+            seen.add(name);
+            firstPageTraits.push(binding);
+          }
+        }
+        base = firstPageTraits.length > 0 ? firstPageTraits : traits2;
+      }
+    }
+    const byName = new Set(base.map((b) => b.trait.name));
+    const extra = [];
+    const queue = [...base];
+    while (queue.length > 0) {
+      const binding = queue.shift();
+      if (!binding) continue;
+      for (const refName of collectTraitRefsFromResolvedTrait(binding.trait)) {
+        if (byName.has(refName)) continue;
+        const rt = allTraits.get(refName);
+        if (!rt) continue;
+        byName.add(refName);
+        const sibling = { trait: rt, linkedEntity: rt.linkedEntity };
+        extra.push(sibling);
+        queue.push(sibling);
+      }
+    }
+    return extra.length > 0 ? [...base, ...extra] : base;
+  }, [ir, traits2, pageName, allTraits]);
   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 orbitalsByTrait = useMemo(
+    () => buildOrbitalsByTrait(
+      schema,
+      ir ? Array.from(ir.pages.values()).map((p2) => ({
+        path: p2.path,
+        traitNames: p2.traits.map((b) => b.trait.name)
+      })) : []
+    ),
+    [schema, ir]
+  );
   const traitLinkedEntitiesMap = useMemo(() => {
     const map = /* @__PURE__ */ new Map();
     if (ir) {

package/dist/components/index.cjs

@@ -8676,7 +8676,7 @@ var init_MapView = __esm({
         shadowSize: [41, 41]
       });
       L.Marker.prototype.options.icon = defaultIcon;
-      const { useEffect: useEffect72, useRef: useRef66, useCallback: useCallback127, useState: useState110 } = React80__namespace.default;
+      const { useEffect: useEffect72, useRef: useRef66, useCallback: useCallback128, useState: useState110 } = React80__namespace.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 }) {
@@ -8722,7 +8722,7 @@ var init_MapView = __esm({
       }) {
         const eventBus = useEventBus2();
         const [clickedPosition, setClickedPosition] = useState110(null);
-        const handleMapClick = useCallback127((lat, lng) => {
+        const handleMapClick = useCallback128((lat, lng) => {
           if (showClickedPin) {
             setClickedPosition({ lat, lng });
           }
@@ -8731,7 +8731,7 @@ var init_MapView = __esm({
             eventBus.emit(`UI:${mapClickEvent}`, { latitude: lat, longitude: lng });
           }
         }, [onMapClick, mapClickEvent, eventBus, showClickedPin]);
-        const handleMarkerClick = useCallback127((marker) => {
+        const handleMarkerClick = useCallback128((marker) => {
           onMarkerClick?.(marker);
           if (markerClickEvent) {
             eventBus.emit(`UI:${markerClickEvent}`, { ...marker });
@@ -25784,12 +25784,15 @@ function GameCanvas2D({
   tickEvent,
   drawEvent,
   fps = 60,
+  backgroundImage,
+  assetBaseUrl = "",
   className
 }) {
   const canvasRef = React80__namespace.useRef(null);
   const rafRef = React80__namespace.useRef(0);
   const frameRef = React80__namespace.useRef(0);
   const lastTimeRef = React80__namespace.useRef(0);
+  const imageCache = React80__namespace.useRef(/* @__PURE__ */ new Map());
   const emit = useEmitEvent();
   const onDrawRef = React80__namespace.useRef(onDraw);
   onDrawRef.current = onDraw;
@@ -25801,6 +25804,18 @@ function GameCanvas2D({
   drawEventRef.current = drawEvent;
   const emitRef = React80__namespace.useRef(emit);
   emitRef.current = emit;
+  const loadImage = React80__namespace.useCallback((url) => {
+    const fullUrl = url.startsWith("http") ? url : `${assetBaseUrl}${url}`;
+    const cached = imageCache.current.get(fullUrl);
+    if (cached?.complete && cached.naturalWidth > 0) return cached;
+    if (!cached) {
+      const img = new Image();
+      img.crossOrigin = "anonymous";
+      img.src = fullUrl;
+      imageCache.current.set(fullUrl, img);
+    }
+    return null;
+  }, [assetBaseUrl]);
   React80__namespace.useEffect(() => {
     const canvas = canvasRef.current;
     if (!canvas) return;
@@ -25822,6 +25837,12 @@ function GameCanvas2D({
         if (tickEventRef.current) {
           emitRef.current(tickEventRef.current, { dt, frame });
         }
+        if (backgroundImage) {
+          const bgImg = loadImage(backgroundImage);
+          if (bgImg) {
+            ctx.drawImage(bgImg, 0, 0, width, height);
+          }
+        }
         onDrawRef.current?.(ctx, frame);
         if (drawEventRef.current) {
           emitRef.current(drawEventRef.current, { frame });

package/dist/components/index.js

@@ -8627,7 +8627,7 @@ var init_MapView = __esm({
         shadowSize: [41, 41]
       });
       L.Marker.prototype.options.icon = defaultIcon;
-      const { useEffect: useEffect72, useRef: useRef66, useCallback: useCallback127, useState: useState110 } = React80__default;
+      const { useEffect: useEffect72, useRef: useRef66, useCallback: useCallback128, useState: useState110 } = React80__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 }) {
@@ -8673,7 +8673,7 @@ var init_MapView = __esm({
       }) {
         const eventBus = useEventBus2();
         const [clickedPosition, setClickedPosition] = useState110(null);
-        const handleMapClick = useCallback127((lat, lng) => {
+        const handleMapClick = useCallback128((lat, lng) => {
           if (showClickedPin) {
             setClickedPosition({ lat, lng });
           }
@@ -8682,7 +8682,7 @@ var init_MapView = __esm({
             eventBus.emit(`UI:${mapClickEvent}`, { latitude: lat, longitude: lng });
           }
         }, [onMapClick, mapClickEvent, eventBus, showClickedPin]);
-        const handleMarkerClick = useCallback127((marker) => {
+        const handleMarkerClick = useCallback128((marker) => {
           onMarkerClick?.(marker);
           if (markerClickEvent) {
             eventBus.emit(`UI:${markerClickEvent}`, { ...marker });
@@ -25735,12 +25735,15 @@ function GameCanvas2D({
   tickEvent,
   drawEvent,
   fps = 60,
+  backgroundImage,
+  assetBaseUrl = "",
   className
 }) {
   const canvasRef = React80.useRef(null);
   const rafRef = React80.useRef(0);
   const frameRef = React80.useRef(0);
   const lastTimeRef = React80.useRef(0);
+  const imageCache = React80.useRef(/* @__PURE__ */ new Map());
   const emit = useEmitEvent();
   const onDrawRef = React80.useRef(onDraw);
   onDrawRef.current = onDraw;
@@ -25752,6 +25755,18 @@ function GameCanvas2D({
   drawEventRef.current = drawEvent;
   const emitRef = React80.useRef(emit);
   emitRef.current = emit;
+  const loadImage = React80.useCallback((url) => {
+    const fullUrl = url.startsWith("http") ? url : `${assetBaseUrl}${url}`;
+    const cached = imageCache.current.get(fullUrl);
+    if (cached?.complete && cached.naturalWidth > 0) return cached;
+    if (!cached) {
+      const img = new Image();
+      img.crossOrigin = "anonymous";
+      img.src = fullUrl;
+      imageCache.current.set(fullUrl, img);
+    }
+    return null;
+  }, [assetBaseUrl]);
   React80.useEffect(() => {
     const canvas = canvasRef.current;
     if (!canvas) return;
@@ -25773,6 +25788,12 @@ function GameCanvas2D({
         if (tickEventRef.current) {
           emitRef.current(tickEventRef.current, { dt, frame });
         }
+        if (backgroundImage) {
+          const bgImg = loadImage(backgroundImage);
+          if (bgImg) {
+            ctx.drawImage(bgImg, 0, 0, width, height);
+          }
+        }
         onDrawRef.current?.(ctx, frame);
         if (drawEventRef.current) {
           emitRef.current(drawEventRef.current, { frame });

package/dist/components/molecules/game/GameCanvas2D.d.ts

@@ -13,10 +13,14 @@ export interface GameCanvas2DProps {
     drawEvent?: string;
     /** Target frames per second */
     fps?: number;
+    /** Background image URL */
+    backgroundImage?: string;
+    /** Base URL prefix for asset URLs */
+    assetBaseUrl?: string;
     /** Additional CSS classes */
     className?: string;
 }
-export declare function GameCanvas2D({ width, height, onDraw, onTick, tickEvent, drawEvent, fps, className, }: GameCanvas2DProps): import("react/jsx-runtime").JSX.Element;
+export declare function GameCanvas2D({ width, height, onDraw, onTick, tickEvent, drawEvent, fps, backgroundImage, assetBaseUrl, className, }: GameCanvas2DProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace GameCanvas2D {
     var displayName: string;
 }

package/dist/providers/index.cjs

@@ -10244,7 +10244,7 @@ var init_MapView = __esm({
         shadowSize: [41, 41]
       });
       L.Marker.prototype.options.icon = defaultIcon;
-      const { useEffect: useEffect69, useRef: useRef65, useCallback: useCallback113, useState: useState99 } = React86__namespace.default;
+      const { useEffect: useEffect69, useRef: useRef65, useCallback: useCallback114, useState: useState99 } = React86__namespace.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 }) {
@@ -10290,7 +10290,7 @@ var init_MapView = __esm({
       }) {
         const eventBus = useEventBus2();
         const [clickedPosition, setClickedPosition] = useState99(null);
-        const handleMapClick = useCallback113((lat, lng) => {
+        const handleMapClick = useCallback114((lat, lng) => {
           if (showClickedPin) {
             setClickedPosition({ lat, lng });
           }
@@ -10299,7 +10299,7 @@ var init_MapView = __esm({
             eventBus.emit(`UI:${mapClickEvent}`, { latitude: lat, longitude: lng });
           }
         }, [onMapClick, mapClickEvent, eventBus, showClickedPin]);
-        const handleMarkerClick = useCallback113((marker) => {
+        const handleMarkerClick = useCallback114((marker) => {
           onMarkerClick?.(marker);
           if (markerClickEvent) {
             eventBus.emit(`UI:${markerClickEvent}`, { ...marker });
@@ -26811,12 +26811,15 @@ function GameCanvas2D({
   tickEvent,
   drawEvent,
   fps = 60,
+  backgroundImage,
+  assetBaseUrl = "",
   className
 }) {
   const canvasRef = React86__namespace.useRef(null);
   const rafRef = React86__namespace.useRef(0);
   const frameRef = React86__namespace.useRef(0);
   const lastTimeRef = React86__namespace.useRef(0);
+  const imageCache = React86__namespace.useRef(/* @__PURE__ */ new Map());
   const emit = useEmitEvent();
   const onDrawRef = React86__namespace.useRef(onDraw);
   onDrawRef.current = onDraw;
@@ -26828,6 +26831,18 @@ function GameCanvas2D({
   drawEventRef.current = drawEvent;
   const emitRef = React86__namespace.useRef(emit);
   emitRef.current = emit;
+  const loadImage = React86__namespace.useCallback((url) => {
+    const fullUrl = url.startsWith("http") ? url : `${assetBaseUrl}${url}`;
+    const cached = imageCache.current.get(fullUrl);
+    if (cached?.complete && cached.naturalWidth > 0) return cached;
+    if (!cached) {
+      const img = new Image();
+      img.crossOrigin = "anonymous";
+      img.src = fullUrl;
+      imageCache.current.set(fullUrl, img);
+    }
+    return null;
+  }, [assetBaseUrl]);
   React86__namespace.useEffect(() => {
     const canvas = canvasRef.current;
     if (!canvas) return;
@@ -26849,6 +26864,12 @@ function GameCanvas2D({
         if (tickEventRef.current) {
           emitRef.current(tickEventRef.current, { dt, frame });
         }
+        if (backgroundImage) {
+          const bgImg = loadImage(backgroundImage);
+          if (bgImg) {
+            ctx.drawImage(bgImg, 0, 0, width, height);
+          }
+        }
         onDrawRef.current?.(ctx, frame);
         if (drawEventRef.current) {
           emitRef.current(drawEventRef.current, { frame });

package/dist/providers/index.js

@@ -10195,7 +10195,7 @@ var init_MapView = __esm({
         shadowSize: [41, 41]
       });
       L.Marker.prototype.options.icon = defaultIcon;
-      const { useEffect: useEffect69, useRef: useRef65, useCallback: useCallback113, useState: useState99 } = React86__default;
+      const { useEffect: useEffect69, useRef: useRef65, useCallback: useCallback114, useState: useState99 } = React86__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 }) {
@@ -10241,7 +10241,7 @@ var init_MapView = __esm({
       }) {
         const eventBus = useEventBus2();
         const [clickedPosition, setClickedPosition] = useState99(null);
-        const handleMapClick = useCallback113((lat, lng) => {
+        const handleMapClick = useCallback114((lat, lng) => {
           if (showClickedPin) {
             setClickedPosition({ lat, lng });
           }
@@ -10250,7 +10250,7 @@ var init_MapView = __esm({
             eventBus.emit(`UI:${mapClickEvent}`, { latitude: lat, longitude: lng });
           }
         }, [onMapClick, mapClickEvent, eventBus, showClickedPin]);
-        const handleMarkerClick = useCallback113((marker) => {
+        const handleMarkerClick = useCallback114((marker) => {
           onMarkerClick?.(marker);
           if (markerClickEvent) {
             eventBus.emit(`UI:${markerClickEvent}`, { ...marker });
@@ -26762,12 +26762,15 @@ function GameCanvas2D({
   tickEvent,
   drawEvent,
   fps = 60,
+  backgroundImage,
+  assetBaseUrl = "",
   className
 }) {
   const canvasRef = React86.useRef(null);
   const rafRef = React86.useRef(0);
   const frameRef = React86.useRef(0);
   const lastTimeRef = React86.useRef(0);
+  const imageCache = React86.useRef(/* @__PURE__ */ new Map());
   const emit = useEmitEvent();
   const onDrawRef = React86.useRef(onDraw);
   onDrawRef.current = onDraw;
@@ -26779,6 +26782,18 @@ function GameCanvas2D({
   drawEventRef.current = drawEvent;
   const emitRef = React86.useRef(emit);
   emitRef.current = emit;
+  const loadImage = React86.useCallback((url) => {
+    const fullUrl = url.startsWith("http") ? url : `${assetBaseUrl}${url}`;
+    const cached = imageCache.current.get(fullUrl);
+    if (cached?.complete && cached.naturalWidth > 0) return cached;
+    if (!cached) {
+      const img = new Image();
+      img.crossOrigin = "anonymous";
+      img.src = fullUrl;
+      imageCache.current.set(fullUrl, img);
+    }
+    return null;
+  }, [assetBaseUrl]);
   React86.useEffect(() => {
     const canvas = canvasRef.current;
     if (!canvas) return;
@@ -26800,6 +26815,12 @@ function GameCanvas2D({
         if (tickEventRef.current) {
           emitRef.current(tickEventRef.current, { dt, frame });
         }
+        if (backgroundImage) {
+          const bgImg = loadImage(backgroundImage);
+          if (bgImg) {
+            ctx.drawImage(bgImg, 0, 0, width, height);
+          }
+        }
         onDrawRef.current?.(ctx, frame);
         if (drawEventRef.current) {
           emitRef.current(drawEventRef.current, { frame });

package/dist/runtime/embedded-traits.d.ts

@@ -21,7 +21,14 @@
  *
  * @packageDocumentation
  */
-import type { OrbitalSchema } from '@almadar/core';
+import type { OrbitalSchema, ResolvedTrait } from '@almadar/core';
+/**
+ * Collect the `@trait.X` names referenced by a single resolved trait's
+ * render-ui effects (transitions + initial + ticks). Used to pull embed-routed
+ * sibling traits into a page's state-machine binding set so their own state
+ * machines register + subscribe (otherwise their fetch-success is never heard).
+ */
+export declare function collectTraitRefsFromResolvedTrait(trait: ResolvedTrait): Set<string>;
 /**
  * Build the flat set of trait names that are referenced via `@trait.X`
  * by at least one trait's render-ui in the resolved schema.

package/dist/runtime/index.cjs

@@ -10132,7 +10132,7 @@ var init_MapView = __esm({
         shadowSize: [41, 41]
       });
       L.Marker.prototype.options.icon = defaultIcon;
-      const { useEffect: useEffect70, useRef: useRef65, useCallback: useCallback113, useState: useState102 } = React85__namespace.default;
+      const { useEffect: useEffect70, useRef: useRef65, useCallback: useCallback114, useState: useState102 } = React85__namespace.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 }) {
@@ -10178,7 +10178,7 @@ var init_MapView = __esm({
       }) {
         const eventBus = useEventBus2();
         const [clickedPosition, setClickedPosition] = useState102(null);
-        const handleMapClick = useCallback113((lat, lng) => {
+        const handleMapClick = useCallback114((lat, lng) => {
           if (showClickedPin) {
             setClickedPosition({ lat, lng });
           }
@@ -10187,7 +10187,7 @@ var init_MapView = __esm({
             eventBus.emit(`UI:${mapClickEvent}`, { latitude: lat, longitude: lng });
           }
         }, [onMapClick, mapClickEvent, eventBus, showClickedPin]);
-        const handleMarkerClick = useCallback113((marker) => {
+        const handleMarkerClick = useCallback114((marker) => {
           onMarkerClick?.(marker);
           if (markerClickEvent) {
             eventBus.emit(`UI:${markerClickEvent}`, { ...marker });
@@ -26516,12 +26516,15 @@ function GameCanvas2D({
   tickEvent,
   drawEvent,
   fps = 60,
+  backgroundImage,
+  assetBaseUrl = "",
   className
 }) {
   const canvasRef = React85__namespace.useRef(null);
   const rafRef = React85__namespace.useRef(0);
   const frameRef = React85__namespace.useRef(0);
   const lastTimeRef = React85__namespace.useRef(0);
+  const imageCache = React85__namespace.useRef(/* @__PURE__ */ new Map());
   const emit = useEmitEvent();
   const onDrawRef = React85__namespace.useRef(onDraw);
   onDrawRef.current = onDraw;
@@ -26533,6 +26536,18 @@ function GameCanvas2D({
   drawEventRef.current = drawEvent;
   const emitRef = React85__namespace.useRef(emit);
   emitRef.current = emit;
+  const loadImage = React85__namespace.useCallback((url) => {
+    const fullUrl = url.startsWith("http") ? url : `${assetBaseUrl}${url}`;
+    const cached = imageCache.current.get(fullUrl);
+    if (cached?.complete && cached.naturalWidth > 0) return cached;
+    if (!cached) {
+      const img = new Image();
+      img.crossOrigin = "anonymous";
+      img.src = fullUrl;
+      imageCache.current.set(fullUrl, img);
+    }
+    return null;
+  }, [assetBaseUrl]);
   React85__namespace.useEffect(() => {
     const canvas = canvasRef.current;
     if (!canvas) return;
@@ -26554,6 +26569,12 @@ function GameCanvas2D({
         if (tickEventRef.current) {
           emitRef.current(tickEventRef.current, { dt, frame });
         }
+        if (backgroundImage) {
+          const bgImg = loadImage(backgroundImage);
+          if (bgImg) {
+            ctx.drawImage(bgImg, 0, 0, width, height);
+          }
+        }
         onDrawRef.current?.(ctx, frame);
         if (drawEventRef.current) {
           emitRef.current(drawEventRef.current, { frame });
@@ -48512,6 +48533,16 @@ function collectTraitRefsFromEffects(effects, into) {
     }
   }
 }
+function collectTraitRefsFromResolvedTrait(trait) {
+  const out = /* @__PURE__ */ new Set();
+  for (const transition of trait.transitions ?? []) {
+    collectTraitRefsFromEffects(transition.effects, out);
+  }
+  for (const tick of trait.ticks ?? []) {
+    collectTraitRefsFromEffects(tick.effects, out);
+  }
+  return out;
+}
 function collectEmbeddedTraits(schema) {
   const out = /* @__PURE__ */ new Set();
   if (!schema?.orbitals) return out;
@@ -48544,6 +48575,40 @@ function collectEmbeddedTraits(schema) {
   return out;
 }
 
+// runtime/orbitalsByTrait.ts
+function buildOrbitalsByTrait(schema, resolvedPages = []) {
+  const map = {};
+  if (!schema?.orbitals) return map;
+  const pagePathToOrbital = {};
+  for (const orb of schema.orbitals) {
+    for (const traitRef of orb.traits ?? []) {
+      let traitName;
+      if (typeof traitRef === "string") {
+        const parts = traitRef.split(".");
+        traitName = parts[parts.length - 1];
+      } else if (typeof traitRef.ref === "string") {
+        const parts = traitRef.ref.split(".");
+        traitName = traitRef.name ?? parts[parts.length - 1];
+      } else if (typeof traitRef.name === "string") {
+        traitName = traitRef.name;
+      }
+      if (traitName) map[traitName] = orb.name;
+    }
+    for (const pg of orb.pages ?? []) {
+      const path = typeof pg === "string" ? pg : pg?.path;
+      if (path) pagePathToOrbital[path] = orb.name;
+    }
+  }
+  for (const page of resolvedPages) {
+    const orbital = page.path ? pagePathToOrbital[page.path] : void 0;
+    if (!orbital) continue;
+    for (const traitName of page.traitNames) {
+      if (traitName && !(traitName in map)) map[traitName] = orbital;
+    }
+  }
+  return map;
+}
+
 // runtime/OrbPreview.tsx
 init_EntitySchemaContext();
 
@@ -49316,50 +49381,64 @@ function TraitInitializer({ traits: traits2, orbitalNames, onNavigate, onLocalFa
   return null;
 }
 function SchemaRunner({ schema, serverUrl, transport, mockData, pageName, onNavigate, onLocalFallback, persistence }) {
-  const { traits: traits2, allEntities, ir } = useResolvedSchema(schema, pageName);
+  const { traits: traits2, allEntities, allTraits, ir } = useResolvedSchema(schema, pageName);
   const allPageTraits = React85.useMemo(() => {
-    if (pageName && traits2.length > 0) return traits2;
-    if (!ir?.pages || ir.pages.size <= 1) return traits2;
-    const firstPage = ir.pages.values().next().value;
-    if (!firstPage) return traits2;
-    const firstPageTraits = [];
-    const seen = /* @__PURE__ */ new Set();
-    for (const binding of firstPage.traits) {
-      const name = binding.trait.name;
-      if (name && !seen.has(name)) {
-        seen.add(name);
-        firstPageTraits.push(binding);
-      }
-    }
-    return firstPageTraits.length > 0 ? firstPageTraits : traits2;
-  }, [ir, traits2, pageName]);
+    let base;
+    if (pageName && traits2.length > 0) {
+      base = traits2;
+    } else if (!ir?.pages || ir.pages.size <= 1) {
+      base = traits2;
+    } else {
+      const firstPage = ir.pages.values().next().value;
+      if (!firstPage) {
+        base = traits2;
+      } else {
+        const firstPageTraits = [];
+        const seen = /* @__PURE__ */ new Set();
+        for (const binding of firstPage.traits) {
+          const name = binding.trait.name;
+          if (name && !seen.has(name)) {
+            seen.add(name);
+            firstPageTraits.push(binding);
+          }
+        }
+        base = firstPageTraits.length > 0 ? firstPageTraits : traits2;
+      }
+    }
+    const byName = new Set(base.map((b) => b.trait.name));
+    const extra = [];
+    const queue = [...base];
+    while (queue.length > 0) {
+      const binding = queue.shift();
+      if (!binding) continue;
+      for (const refName of collectTraitRefsFromResolvedTrait(binding.trait)) {
+        if (byName.has(refName)) continue;
+        const rt = allTraits.get(refName);
+        if (!rt) continue;
+        byName.add(refName);
+        const sibling = { trait: rt, linkedEntity: rt.linkedEntity };
+        extra.push(sibling);
+        queue.push(sibling);
+      }
+    }
+    return extra.length > 0 ? [...base, ...extra] : base;
+  }, [ir, traits2, pageName, allTraits]);
   React85.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 = React85.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 orbitalsByTrait = React85.useMemo(
+    () => buildOrbitalsByTrait(
+      schema,
+      ir ? Array.from(ir.pages.values()).map((p2) => ({
+        path: p2.path,
+        traitNames: p2.traits.map((b) => b.trait.name)
+      })) : []
+    ),
+    [schema, ir]
+  );
   const traitLinkedEntitiesMap = React85.useMemo(() => {
     const map = /* @__PURE__ */ new Map();
     if (ir) {

package/dist/runtime/index.js

@@ -10083,7 +10083,7 @@ var init_MapView = __esm({
         shadowSize: [41, 41]
       });
       L.Marker.prototype.options.icon = defaultIcon;
-      const { useEffect: useEffect70, useRef: useRef65, useCallback: useCallback113, useState: useState102 } = React85__default;
+      const { useEffect: useEffect70, useRef: useRef65, useCallback: useCallback114, useState: useState102 } = React85__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 }) {
@@ -10129,7 +10129,7 @@ var init_MapView = __esm({
       }) {
         const eventBus = useEventBus2();
         const [clickedPosition, setClickedPosition] = useState102(null);
-        const handleMapClick = useCallback113((lat, lng) => {
+        const handleMapClick = useCallback114((lat, lng) => {
           if (showClickedPin) {
             setClickedPosition({ lat, lng });
           }
@@ -10138,7 +10138,7 @@ var init_MapView = __esm({
             eventBus.emit(`UI:${mapClickEvent}`, { latitude: lat, longitude: lng });
           }
         }, [onMapClick, mapClickEvent, eventBus, showClickedPin]);
-        const handleMarkerClick = useCallback113((marker) => {
+        const handleMarkerClick = useCallback114((marker) => {
           onMarkerClick?.(marker);
           if (markerClickEvent) {
             eventBus.emit(`UI:${markerClickEvent}`, { ...marker });
@@ -26467,12 +26467,15 @@ function GameCanvas2D({
   tickEvent,
   drawEvent,
   fps = 60,
+  backgroundImage,
+  assetBaseUrl = "",
   className
 }) {
   const canvasRef = React85.useRef(null);
   const rafRef = React85.useRef(0);
   const frameRef = React85.useRef(0);
   const lastTimeRef = React85.useRef(0);
+  const imageCache = React85.useRef(/* @__PURE__ */ new Map());
   const emit = useEmitEvent();
   const onDrawRef = React85.useRef(onDraw);
   onDrawRef.current = onDraw;
@@ -26484,6 +26487,18 @@ function GameCanvas2D({
   drawEventRef.current = drawEvent;
   const emitRef = React85.useRef(emit);
   emitRef.current = emit;
+  const loadImage = React85.useCallback((url) => {
+    const fullUrl = url.startsWith("http") ? url : `${assetBaseUrl}${url}`;
+    const cached = imageCache.current.get(fullUrl);
+    if (cached?.complete && cached.naturalWidth > 0) return cached;
+    if (!cached) {
+      const img = new Image();
+      img.crossOrigin = "anonymous";
+      img.src = fullUrl;
+      imageCache.current.set(fullUrl, img);
+    }
+    return null;
+  }, [assetBaseUrl]);
   React85.useEffect(() => {
     const canvas = canvasRef.current;
     if (!canvas) return;
@@ -26505,6 +26520,12 @@ function GameCanvas2D({
         if (tickEventRef.current) {
           emitRef.current(tickEventRef.current, { dt, frame });
         }
+        if (backgroundImage) {
+          const bgImg = loadImage(backgroundImage);
+          if (bgImg) {
+            ctx.drawImage(bgImg, 0, 0, width, height);
+          }
+        }
         onDrawRef.current?.(ctx, frame);
         if (drawEventRef.current) {
           emitRef.current(drawEventRef.current, { frame });
@@ -48463,6 +48484,16 @@ function collectTraitRefsFromEffects(effects, into) {
     }
   }
 }
+function collectTraitRefsFromResolvedTrait(trait) {
+  const out = /* @__PURE__ */ new Set();
+  for (const transition of trait.transitions ?? []) {
+    collectTraitRefsFromEffects(transition.effects, out);
+  }
+  for (const tick of trait.ticks ?? []) {
+    collectTraitRefsFromEffects(tick.effects, out);
+  }
+  return out;
+}
 function collectEmbeddedTraits(schema) {
   const out = /* @__PURE__ */ new Set();
   if (!schema?.orbitals) return out;
@@ -48495,6 +48526,40 @@ function collectEmbeddedTraits(schema) {
   return out;
 }
 
+// runtime/orbitalsByTrait.ts
+function buildOrbitalsByTrait(schema, resolvedPages = []) {
+  const map = {};
+  if (!schema?.orbitals) return map;
+  const pagePathToOrbital = {};
+  for (const orb of schema.orbitals) {
+    for (const traitRef of orb.traits ?? []) {
+      let traitName;
+      if (typeof traitRef === "string") {
+        const parts = traitRef.split(".");
+        traitName = parts[parts.length - 1];
+      } else if (typeof traitRef.ref === "string") {
+        const parts = traitRef.ref.split(".");
+        traitName = traitRef.name ?? parts[parts.length - 1];
+      } else if (typeof traitRef.name === "string") {
+        traitName = traitRef.name;
+      }
+      if (traitName) map[traitName] = orb.name;
+    }
+    for (const pg of orb.pages ?? []) {
+      const path = typeof pg === "string" ? pg : pg?.path;
+      if (path) pagePathToOrbital[path] = orb.name;
+    }
+  }
+  for (const page of resolvedPages) {
+    const orbital = page.path ? pagePathToOrbital[page.path] : void 0;
+    if (!orbital) continue;
+    for (const traitName of page.traitNames) {
+      if (traitName && !(traitName in map)) map[traitName] = orbital;
+    }
+  }
+  return map;
+}
+
 // runtime/OrbPreview.tsx
 init_EntitySchemaContext();
 
@@ -49267,50 +49332,64 @@ function TraitInitializer({ traits: traits2, orbitalNames, onNavigate, onLocalFa
   return null;
 }
 function SchemaRunner({ schema, serverUrl, transport, mockData, pageName, onNavigate, onLocalFallback, persistence }) {
-  const { traits: traits2, allEntities, ir } = useResolvedSchema(schema, pageName);
+  const { traits: traits2, allEntities, allTraits, ir } = useResolvedSchema(schema, pageName);
   const allPageTraits = useMemo(() => {
-    if (pageName && traits2.length > 0) return traits2;
-    if (!ir?.pages || ir.pages.size <= 1) return traits2;
-    const firstPage = ir.pages.values().next().value;
-    if (!firstPage) return traits2;
-    const firstPageTraits = [];
-    const seen = /* @__PURE__ */ new Set();
-    for (const binding of firstPage.traits) {
-      const name = binding.trait.name;
-      if (name && !seen.has(name)) {
-        seen.add(name);
-        firstPageTraits.push(binding);
-      }
-    }
-    return firstPageTraits.length > 0 ? firstPageTraits : traits2;
-  }, [ir, traits2, pageName]);
+    let base;
+    if (pageName && traits2.length > 0) {
+      base = traits2;
+    } else if (!ir?.pages || ir.pages.size <= 1) {
+      base = traits2;
+    } else {
+      const firstPage = ir.pages.values().next().value;
+      if (!firstPage) {
+        base = traits2;
+      } else {
+        const firstPageTraits = [];
+        const seen = /* @__PURE__ */ new Set();
+        for (const binding of firstPage.traits) {
+          const name = binding.trait.name;
+          if (name && !seen.has(name)) {
+            seen.add(name);
+            firstPageTraits.push(binding);
+          }
+        }
+        base = firstPageTraits.length > 0 ? firstPageTraits : traits2;
+      }
+    }
+    const byName = new Set(base.map((b) => b.trait.name));
+    const extra = [];
+    const queue = [...base];
+    while (queue.length > 0) {
+      const binding = queue.shift();
+      if (!binding) continue;
+      for (const refName of collectTraitRefsFromResolvedTrait(binding.trait)) {
+        if (byName.has(refName)) continue;
+        const rt = allTraits.get(refName);
+        if (!rt) continue;
+        byName.add(refName);
+        const sibling = { trait: rt, linkedEntity: rt.linkedEntity };
+        extra.push(sibling);
+        queue.push(sibling);
+      }
+    }
+    return extra.length > 0 ? [...base, ...extra] : base;
+  }, [ir, traits2, pageName, allTraits]);
   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 orbitalsByTrait = useMemo(
+    () => buildOrbitalsByTrait(
+      schema,
+      ir ? Array.from(ir.pages.values()).map((p2) => ({
+        path: p2.path,
+        traitNames: p2.traits.map((b) => b.trait.name)
+      })) : []
+    ),
+    [schema, ir]
+  );
   const traitLinkedEntitiesMap = useMemo(() => {
     const map = /* @__PURE__ */ new Map();
     if (ir) {

package/dist/runtime/orbitalsByTrait.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Build the `trait name → owning orbital` map used to form the qualified
+ * `UI:<orbital>.<trait>.<event>` bus keys that trait state machines subscribe
+ * to. Pure + dependency-free so it can be unit-tested without a React render.
+ *
+ * Critically, it backfills from the RESOLVED page bindings, not just the source
+ * `schema.orbitals[].traits`. An auto-pulled sibling trait (e.g. an embedded
+ * `@trait.X` calendar lifted into the orbital by the compiler's sibling-pull)
+ * is absent from the source orbital's `traits[]`, so a source-only map misses
+ * it — leaving its self-subscription unregistered and its own fetch-success
+ * (e.g. `CalendarEventLoaded`) unheard, so the trait sticks in `loading`. A
+ * pulled sibling lands in the same orbital as the page that references it, so
+ * we backfill from the resolved page's owning orbital. Source-declared mappings
+ * win; the IR only fills gaps.
+ */
+export interface OrbitalsByTraitSchema {
+    orbitals?: ReadonlyArray<{
+        name: string;
+        traits?: ReadonlyArray<string | {
+            ref?: string;
+            name?: string;
+        }>;
+        pages?: ReadonlyArray<string | {
+            path?: string;
+        }>;
+    }>;
+}
+export interface ResolvedPageTraits {
+    /** Page route path, matched against the source orbital's page paths. */
+    path?: string;
+    /** Resolved trait names mounted on the page (includes pulled siblings). */
+    traitNames: readonly string[];
+}
+export declare function buildOrbitalsByTrait(schema: OrbitalsByTraitSchema | undefined, resolvedPages?: ReadonlyArray<ResolvedPageTraits>): Record<string, string>;

package/package.json

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