@almadar/ui 5.9.8 → 5.9.10

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;
@@ -61671,23 +61702,48 @@ 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;
@@ -61876,11 +61932,13 @@ function OrbPreview({
     return match?.page.name;
   }, [pages, initialPagePath]);
   const [currentPage, setCurrentPage] = React98.useState(initialPageName);
+  const prevInitialPagePathRef = React98.useRef(initialPagePath);
   React98.useEffect(() => {
-    if (initialPageName && initialPageName !== currentPage) {
+    if (prevInitialPagePathRef.current !== initialPagePath) {
+      prevInitialPagePathRef.current = initialPagePath;
       setCurrentPage(initialPageName);
     }
-  }, [initialPageName, currentPage]);
+  }, [initialPagePath, initialPageName]);
   const handleNavigate = React98.useCallback((path) => {
     const match = pages.find(({ page }) => page.path === path);
     navLog.debug("handleNavigate", () => ({

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;
@@ -61622,23 +61653,48 @@ 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;
@@ -61827,11 +61883,13 @@ function OrbPreview({
     return match?.page.name;
   }, [pages, initialPagePath]);
   const [currentPage, setCurrentPage] = useState(initialPageName);
+  const prevInitialPagePathRef = useRef(initialPagePath);
   useEffect(() => {
-    if (initialPageName && initialPageName !== currentPage) {
+    if (prevInitialPagePathRef.current !== initialPagePath) {
+      prevInitialPagePathRef.current = initialPagePath;
       setCurrentPage(initialPageName);
     }
-  }, [initialPageName, currentPage]);
+  }, [initialPagePath, initialPageName]);
   const handleNavigate = useCallback((path) => {
     const match = pages.find(({ page }) => page.path === path);
     navLog.debug("handleNavigate", () => ({

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;
@@ -49350,23 +49381,48 @@ 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;
@@ -49555,11 +49611,13 @@ function OrbPreview({
     return match?.page.name;
   }, [pages, initialPagePath]);
   const [currentPage, setCurrentPage] = React85.useState(initialPageName);
+  const prevInitialPagePathRef = React85.useRef(initialPagePath);
   React85.useEffect(() => {
-    if (initialPageName && initialPageName !== currentPage) {
+    if (prevInitialPagePathRef.current !== initialPagePath) {
+      prevInitialPagePathRef.current = initialPagePath;
       setCurrentPage(initialPageName);
     }
-  }, [initialPageName, currentPage]);
+  }, [initialPagePath, initialPageName]);
   const handleNavigate = React85.useCallback((path) => {
     const match = pages.find(({ page }) => page.path === path);
     navLog.debug("handleNavigate", () => ({

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;
@@ -49301,23 +49332,48 @@ 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;
@@ -49506,11 +49562,13 @@ function OrbPreview({
     return match?.page.name;
   }, [pages, initialPagePath]);
   const [currentPage, setCurrentPage] = useState(initialPageName);
+  const prevInitialPagePathRef = useRef(initialPagePath);
   useEffect(() => {
-    if (initialPageName && initialPageName !== currentPage) {
+    if (prevInitialPagePathRef.current !== initialPagePath) {
+      prevInitialPagePathRef.current = initialPagePath;
       setCurrentPage(initialPageName);
     }
-  }, [initialPageName, currentPage]);
+  }, [initialPagePath, initialPageName]);
   const handleNavigate = useCallback((path) => {
     const match = pages.find(({ page }) => page.path === path);
     navLog.debug("handleNavigate", () => ({

package/package.json

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