@almadar/ui 5.152.0 → 5.154.0

package/dist/providers/index.js

@@ -1,6 +1,6 @@
 import * as React87 from 'react';
 import React87__default, { createContext, useContext, useMemo, useRef, useEffect, useCallback, Suspense, useState, useSyncExternalStore, useLayoutEffect, lazy, useId } from 'react';
-import { EventBusContext, useTraitScopeChain, useEntitySchemaOptional, useEntityBindingSnapshot, useTraitScope, TraitScopeProvider, useCurrentPagePath, useGameAudioContextOptional } from '@almadar/ui/providers';
+import { EventBusContext, useTraitScopeChain, useEntitySchemaOptional, useEntityBindingSnapshot, useTraitScope, TraitScopeProvider, useNavStack, useCurrentPagePath, useGameAudioContextOptional, matchPathAmong } from '@almadar/ui/providers';
 import { createLogger, isLogLevelEnabled } from '@almadar/logger';
 import { createContextFromBindings, interpolateValue } from '@almadar/runtime';
 import { ANONYMOUS_USER, isRenderBindingMarker, isFileValue, isInlineTrait, ANIMATION_NAMES } from '@almadar/core';
@@ -16,7 +16,7 @@ import { useUISlots, ThemeProvider, useTheme } from '@almadar/ui/context';
 export { DesignThemeProvider, useDesignTheme } from '@almadar/ui/context';
 import { evaluate, createMinimalContext } from '@almadar/evaluator';
 import { wrapCallbackForEvent } from '@almadar/runtime/ui';
-import { Link, Outlet, useLocation } from 'react-router-dom';
+import { useLocation, useNavigate, Link, Outlet } from 'react-router-dom';
 import ELK from 'elkjs/lib/elk.bundled.js';
 import SyntaxHighlighter from 'react-syntax-highlighter/dist/esm/prism-light.js';
 import dark from 'react-syntax-highlighter/dist/esm/styles/prism/vsc-dark-plus.js';
@@ -5729,27 +5729,61 @@ var init_InfiniteScrollSentinel = __esm({
     InfiniteScrollSentinel.displayName = "InfiniteScrollSentinel";
   }
 });
-function createParticles(count) {
-  return Array.from({ length: count }, () => {
-    particleIdCounter += 1;
-    return {
-      id: particleIdCounter,
-      color: CONFETTI_COLORS[Math.floor(Math.random() * CONFETTI_COLORS.length)],
-      left: 30 + Math.random() * 40,
-      delay: Math.random() * 300,
-      angle: Math.random() * 360,
-      distance: 40 + Math.random() * 80,
-      rotation: Math.random() * 720 - 360,
-      size: 4 + Math.random() * 6
-    };
-  });
+
+// components/core/atoms/fx.ts
+function resolveFxView(item, presets) {
+  const row = presets?.find((p) => p.type === item.type);
+  if (!row) return item;
+  return {
+    ...item,
+    space: item.space ?? row.space,
+    effect: item.effect ?? row.effect,
+    color: item.color ?? row.color,
+    size: item.size ?? row.size,
+    vx: item.vx ?? row.vx,
+    vy: item.vy ?? row.vy,
+    vz: item.vz ?? row.vz,
+    particleCount: item.particleCount ?? row.particleCount,
+    shape: row.shape,
+    count: row.count,
+    glow: row.glow,
+    gravity: row.gravity,
+    color2: row.color2
+  };
 }
-var CONFETTI_COLORS, particleIdCounter, ConfettiEffect;
-var init_ConfettiEffect = __esm({
-  "components/core/atoms/ConfettiEffect.tsx"() {
-    "use client";
-    init_cn();
-    init_Box();
+function fxLifecycle(item, epochNowMs, tickMs) {
+  const maxTtl = Math.max(item.maxTtl ?? item.ttl, item.ttl, 1);
+  const lifeMs = maxTtl * tickMs;
+  const ageMs = item.bornAt !== void 0 && epochNowMs > 0 ? Math.max(0, epochNowMs - item.bornAt) : (1 - item.ttl / maxTtl) * lifeMs;
+  const progress = Math.min(1, Math.max(0, ageMs / lifeMs));
+  return { lifeMs, ageMs, progress, fade: 1 - progress };
+}
+function fxHash01(seed, salt) {
+  let h = 2166136261 ^ salt;
+  for (let i = 0; i < seed.length; i++) {
+    h ^= seed.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  h ^= h >>> 13;
+  h = Math.imul(h, 1274126177);
+  h ^= h >>> 16;
+  return (h >>> 0) / 4294967296;
+}
+function createConfettiParticles(count, seed) {
+  return Array.from({ length: count }, (_, i) => ({
+    id: i,
+    color: CONFETTI_COLORS[Math.floor(fxHash01(seed, i * 7 + 1) * CONFETTI_COLORS.length)],
+    left: 30 + fxHash01(seed, i * 7 + 2) * 40,
+    delay: fxHash01(seed, i * 7 + 3) * 300,
+    angle: fxHash01(seed, i * 7 + 4) * 360,
+    distance: 40 + fxHash01(seed, i * 7 + 5) * 80,
+    rotation: fxHash01(seed, i * 7 + 6) * 720 - 360,
+    size: 4 + fxHash01(seed, i * 7 + 7) * 6
+  }));
+}
+var CONFETTI_COLORS, CONFETTI_BURST_KEYFRAMES;
+var init_fx = __esm({
+  "components/core/atoms/fx.ts"() {
     CONFETTI_COLORS = [
       "var(--color-primary)",
       "var(--color-success)",
@@ -5758,7 +5792,30 @@ var init_ConfettiEffect = __esm({
       "gold",
       "dodgerblue"
     ];
-    particleIdCounter = 0;
+    CONFETTI_BURST_KEYFRAMES = `
+@keyframes confetti-burst {
+  0% {
+    opacity: 1;
+    transform: translate(0, 0) rotate(0deg) scale(1);
+  }
+  70% {
+    opacity: 1;
+  }
+  100% {
+    opacity: 0;
+    transform: translate(var(--confetti-tx), var(--confetti-ty)) rotate(var(--confetti-rotate)) scale(0.5);
+  }
+}
+`;
+  }
+});
+var ConfettiEffect;
+var init_ConfettiEffect = __esm({
+  "components/core/atoms/ConfettiEffect.tsx"() {
+    "use client";
+    init_cn();
+    init_Box();
+    init_fx();
     ConfettiEffect = ({
       trigger,
       duration = 2e3,
@@ -5767,11 +5824,13 @@ var init_ConfettiEffect = __esm({
     }) => {
       const [particles, setParticles] = useState([]);
       const previousTriggerRef = useRef(false);
+      const burstRef = useRef(0);
       useEffect(() => {
         const wasFalse = !previousTriggerRef.current;
         previousTriggerRef.current = trigger;
         if (trigger && wasFalse) {
-          const newParticles = createParticles(particleCount);
+          burstRef.current += 1;
+          const newParticles = createConfettiParticles(particleCount, `confetti-${burstRef.current}`);
           setParticles(newParticles);
           const timer = window.setTimeout(() => {
             setParticles([]);
@@ -5819,21 +5878,7 @@ var init_ConfettiEffect = __esm({
                 p.id
               );
             }),
-            /* @__PURE__ */ jsx("style", { children: `
-        @keyframes confetti-burst {
-          0% {
-            opacity: 1;
-            transform: translate(0, 0) rotate(0deg) scale(1);
-          }
-          70% {
-            opacity: 1;
-          }
-          100% {
-            opacity: 0;
-            transform: translate(var(--confetti-tx), var(--confetti-ty)) rotate(var(--confetti-rotate)) scale(0.5);
-          }
-        }
-      ` })
+            /* @__PURE__ */ jsx("style", { children: CONFETTI_BURST_KEYFRAMES })
           ]
         }
       );
@@ -9390,7 +9435,7 @@ var init_DrawShape = __esm({
           const cx = p.x + (node.offsetX ?? 0) * tw;
           const cy = p.y + (node.offsetY ?? 0) * tw;
           const rx = (node.radiusX ?? 0) * tw;
-          const ry = (node.radiusY ?? rx) * tw;
+          const ry = (node.radiusY ?? node.radiusX ?? 0) * tw;
           if (pxFill) painter.fillEllipse(cx, cy, rx, ry, pxFill);
           if (patFill) painter.fillEllipse(cx, cy, rx, ry, patFill);
           if (pxStroke) painter.strokeEllipse(cx, cy, rx, ry, pxStroke, strokePx);
@@ -9580,6 +9625,172 @@ var init_DrawTextLayer = __esm({
     };
   }
 });
+
+// components/game/molecules/DrawFxLayer.tsx
+function fxPosition(view, dim, ageSec) {
+  const g = view.gravity ?? 0;
+  const fall = 0.5 * g * ageSec * ageSec;
+  {
+    const base2 = view.position ?? { x: view.x, y: view.z ?? view.y ?? 0 };
+    if (!Number.isFinite(base2.x) || !Number.isFinite(base2.y)) return void 0;
+    return {
+      x: base2.x + (view.vx ?? 0) * ageSec,
+      y: base2.y + (view.vz ?? 0) * ageSec + fall
+    };
+  }
+}
+function sparkShape(view, pos, i, fade, progress) {
+  const size = view.size ?? 0.5;
+  const angle = fxHash01(view.id, i * 3) * Math.PI * 2;
+  const dist = size * (0.4 + 0.6 * fxHash01(view.id, i * 3 + 1)) * easeOut2(progress);
+  const r = size * (0.06 + 0.06 * fxHash01(view.id, i * 3 + 2));
+  const color = view.color ?? DEFAULT_SPARK_COLOR;
+  return {
+    type: "draw-shape",
+    shape: "ellipse",
+    position: { ...pos, x: pos.x + Math.cos(angle) * dist, y: pos.y + Math.sin(angle) * dist },
+    anchor: "center",
+    radiusX: r,
+    fill: color,
+    blendMode: "lighter",
+    opacity: fade,
+    ...view.glow ? { shadow: { color, blur: view.glow } } : {}
+  };
+}
+function proceduralShapes(view, pos, fade, progress) {
+  const size = view.size ?? 0.5;
+  const color = view.color ?? DEFAULT_SPARK_COLOR;
+  switch (view.shape ?? "spark") {
+    case "ring": {
+      return [
+        {
+          type: "draw-shape",
+          shape: "ellipse",
+          position: pos,
+          anchor: "center",
+          radiusX: size * easeOut2(progress),
+          stroke: view.color2 ?? color,
+          strokeWidth: 2,
+          blendMode: "lighter",
+          opacity: fade,
+          ...view.glow ? { shadow: { color, blur: view.glow } } : {}
+        }
+      ];
+    }
+    case "puff": {
+      const count = view.count ?? 3;
+      return Array.from({ length: count }, (_, i) => {
+        const angle = fxHash01(view.id, i * 5) * Math.PI * 2;
+        const drift = size * 0.3 * fxHash01(view.id, i * 5 + 1) * easeOut2(progress);
+        return {
+          type: "draw-shape",
+          shape: "ellipse",
+          position: { ...pos, x: pos.x + Math.cos(angle) * drift, y: pos.y + Math.sin(angle) * drift },
+          anchor: "center",
+          radiusX: size * (0.15 + 0.35 * progress) * (0.7 + 0.6 * fxHash01(view.id, i * 5 + 2)),
+          fill: i === 0 && view.color2 ? view.color2 : color,
+          opacity: fade * 0.6,
+          ...view.glow ? { shadow: { color, blur: view.glow } } : {}
+        };
+      });
+    }
+    case "streak": {
+      const count = view.count ?? 5;
+      return Array.from({ length: count }, (_, i) => {
+        const angle = fxHash01(view.id, i * 3) * Math.PI * 2;
+        const inner = size * (0.2 + 0.8 * easeOut2(progress)) * (0.6 + 0.4 * fxHash01(view.id, i * 3 + 1));
+        const len = size * 0.35;
+        return {
+          type: "draw-shape",
+          shape: "ellipse",
+          position: pos,
+          anchor: "center",
+          offsetX: inner + len / 2,
+          offsetY: 0,
+          radiusX: len / 2,
+          radiusY: size * 0.04,
+          rotate: angle,
+          fill: color,
+          blendMode: "lighter",
+          opacity: fade,
+          ...view.glow ? { shadow: { color, blur: view.glow } } : {}
+        };
+      });
+    }
+    default: {
+      const count = view.count ?? 6;
+      return Array.from({ length: count }, (_, i) => sparkShape(view, pos, i, fade, progress));
+    }
+  }
+}
+function expandFxItem(view, node, epochNowMs, dim) {
+  if (view.space === "screen") return [];
+  const tickMs = node.tickMs ?? DEFAULT_TICK_MS;
+  const { ageMs, progress, fade } = fxLifecycle(view, epochNowMs, tickMs);
+  if (progress >= 1) return [];
+  const pos = fxPosition(view, dim, ageMs / 1e3);
+  if (!pos) return [];
+  const out = [];
+  const artItems = node.art?.[view.type]?.["idle"];
+  const sprite = node.sprites?.[view.type];
+  if (Array.isArray(artItems)) {
+    out.push({
+      type: "draw-group",
+      position: pos,
+      opacity: fade,
+      ...view.size !== void 0 ? { scale: view.size } : {},
+      items: artItems
+    });
+  } else if (sprite?.url) {
+    const spriteSize = view.size ?? 0.6;
+    out.push({
+      type: "draw-sprite",
+      position: pos,
+      asset: sprite,
+      anchor: "center",
+      width: spriteSize,
+      height: spriteSize,
+      opacity: fade
+    });
+  } else {
+    out.push(...proceduralShapes(view, pos, fade, progress));
+  }
+  if (view.message) {
+    const text = {
+      type: "draw-text",
+      text: view.message,
+      position: pos,
+      offsetY: -(0.15 + 0.55 * progress),
+      color: view.color ?? node.textColor ?? DEFAULT_TEXT_COLOR,
+      opacity: fade
+    };
+    out.push(text);
+  }
+  return out;
+}
+function expandFxLayer(node, epochNowMs, dim) {
+  if (!Array.isArray(node.items)) return [];
+  const out = [];
+  for (const item of node.items) {
+    if (!item || typeof item.id !== "string") continue;
+    out.push(...expandFxItem(resolveFxView(item, node.presets), node, epochNowMs, dim));
+  }
+  return out;
+}
+function DrawFxLayer(_props) {
+  return null;
+}
+var DEFAULT_TICK_MS, DEFAULT_TEXT_COLOR, DEFAULT_SPARK_COLOR, easeOut2;
+var init_DrawFxLayer = __esm({
+  "components/game/molecules/DrawFxLayer.tsx"() {
+    "use client";
+    init_fx();
+    DEFAULT_TICK_MS = 500;
+    DEFAULT_TEXT_COLOR = "#ffe066";
+    DEFAULT_SPARK_COLOR = "#ffffff";
+    easeOut2 = (t) => 1 - (1 - t) * (1 - t);
+  }
+});
 function paintDrawable(painter, node, dctx) {
   switch (node.type) {
     case "draw-sprite":
@@ -9627,6 +9838,11 @@ function paintDrawable(painter, node, dctx) {
     case "draw-text-layer":
       paintTextLayer(painter, node, dctx);
       break;
+    case "draw-fx-layer": {
+      const epochNow = dctx.time > 0 && typeof performance !== "undefined" ? performance.timeOrigin + dctx.time : 0;
+      for (const child of expandFxLayer(node, epochNow, "2d")) paintDrawable(painter, child, dctx);
+      break;
+    }
   }
 }
 var paint2dLog, warnedUnsupported2d, warnUnsupported2d;
@@ -9641,6 +9857,7 @@ var init_paintDispatch = __esm({
     init_DrawSpriteLayer();
     init_DrawShapeLayer();
     init_DrawTextLayer();
+    init_DrawFxLayer();
     paint2dLog = createLogger("almadar:ui:drawable-2d");
     warnedUnsupported2d = /* @__PURE__ */ new Set();
     warnUnsupported2d = (kind) => {
@@ -9889,6 +10106,7 @@ function Canvas2D({
       return isAnimatedGroup(node) || Array.isArray(node.items) && node.items.some(drawableIsAnimated);
     if (node.type === "draw-shape-layer") return Array.isArray(node.items) && node.items.some(isAnimatedShape);
     if (node.type === "draw-sprite-layer") return Array.isArray(node.items) && node.items.some(isAnimatedSprite);
+    if (node.type === "draw-fx-layer") return Array.isArray(node.items) && node.items.length > 0;
     return false;
   };
   const animRafRef = useRef(0);
@@ -21108,17 +21326,27 @@ var init_Breadcrumb = __esm({
     init_useEventBus();
     Breadcrumb = ({
       items,
+      fromNavStack = false,
+      itemEvent,
       separator = "chevron-right",
       maxItems,
       className
     }) => {
       const eventBus = useEventBus();
       const { t } = useTranslate();
-      const displayItems = maxItems && items.length > maxItems ? [
-        ...items.slice(0, 1),
+      const navStack = useNavStack();
+      const sourceItems = fromNavStack ? navStack.entries.map((entry, i) => ({
+        label: entry.label,
+        path: entry.href,
+        isCurrent: i === navStack.entries.length - 1,
+        event: itemEvent
+      })) : items ?? [];
+      if (fromNavStack && sourceItems.length === 0) return null;
+      const displayItems = maxItems && sourceItems.length > maxItems ? [
+        ...sourceItems.slice(0, 1),
         { label: "...", isCurrent: false },
-        ...items.slice(-maxItems + 1)
-      ] : items;
+        ...sourceItems.slice(-maxItems + 1)
+      ] : sourceItems;
       return /* @__PURE__ */ jsx(
         "nav",
         {
@@ -21128,7 +21356,7 @@ var init_Breadcrumb = __esm({
             const isLast = index === displayItems.length - 1;
             const isEllipsis = item.label === "...";
             return /* @__PURE__ */ jsxs("li", { className: "flex items-center gap-2", children: [
-              isEllipsis ? /* @__PURE__ */ jsx(Typography, { variant: "small", color: "muted", children: item.label }) : item.href || item.path ? /* @__PURE__ */ jsxs(
+              isEllipsis ? /* @__PURE__ */ jsx(Typography, { variant: "small", color: "muted", children: item.label }) : (item.href || item.path) && !item.event && !fromNavStack ? /* @__PURE__ */ jsxs(
                 "a",
                 {
                   href: item.href || item.path,
@@ -21154,7 +21382,12 @@ var init_Breadcrumb = __esm({
                 {
                   type: "button",
                   onClick: () => {
-                    if (item.event) eventBus.emit(`UI:${item.event}`, { label: item.label });
+                    const href = item.path ?? item.href;
+                    if (item.event) {
+                      eventBus.emit(`UI:${item.event}`, { label: item.label, href, index });
+                    } else if (fromNavStack && href) {
+                      navStack.goTo(href);
+                    }
                     item.onClick?.();
                   },
                   className: cn(
@@ -28128,6 +28361,196 @@ var init_PageTransition = __esm({
     PageTransition.displayName = "PageTransition";
   }
 });
+function ConfettiBurst({ item, lifeMs }) {
+  const particles = createConfettiParticles(item.particleCount ?? 30, item.id);
+  const left = (item.x ?? 0.5) * 100;
+  const top = (item.z ?? item.y ?? 0.4) * 100;
+  return /* @__PURE__ */ jsx(Box, { position: "absolute", style: { left: `${left}%`, top: `${top}%` }, children: particles.map((p) => {
+    const rad = p.angle * Math.PI / 180;
+    const tx = Math.cos(rad) * p.distance * (item.size ?? 1);
+    const ty = Math.sin(rad) * p.distance * (item.size ?? 1) - 20;
+    return /* @__PURE__ */ jsx(
+      Box,
+      {
+        className: "absolute rounded-sm",
+        style: {
+          left: (p.left - 50) * 2,
+          top: -10,
+          width: p.size,
+          height: p.size,
+          backgroundColor: item.color ?? p.color,
+          animation: `confetti-burst ${Math.max(lifeMs - p.delay, 200)}ms ease-out ${p.delay}ms forwards`,
+          opacity: 0,
+          "--confetti-tx": `${tx}px`,
+          "--confetti-ty": `${ty}px`,
+          "--confetti-rotate": `${p.rotation}deg`
+        }
+      },
+      p.id
+    );
+  }) });
+}
+function SparkleBurst({ item, lifeMs }) {
+  const count = item.particleCount ?? 8;
+  const scale = item.size ?? 1;
+  const left = (item.x ?? 0.5) * 100;
+  const top = (item.z ?? item.y ?? 0.4) * 100;
+  return /* @__PURE__ */ jsx(Box, { position: "absolute", style: { left: `${left}%`, top: `${top}%` }, children: Array.from({ length: count }, (_, i) => {
+    const dx = (fxHash01(item.id, i * 4) - 0.5) * 160 * scale;
+    const dy = (fxHash01(item.id, i * 4 + 1) - 0.5) * 120 * scale;
+    const dot = (4 + fxHash01(item.id, i * 4 + 2) * 5) * scale;
+    const delay = fxHash01(item.id, i * 4 + 3) * lifeMs * 0.4;
+    return /* @__PURE__ */ jsx(
+      Box,
+      {
+        className: "absolute rounded-full",
+        style: {
+          left: dx,
+          top: dy,
+          width: dot,
+          height: dot,
+          backgroundColor: item.color ?? "gold",
+          opacity: 0,
+          animation: `fx-overlay-sparkle ${Math.max(lifeMs - delay, 200)}ms ease-in-out ${delay}ms forwards`
+        }
+      },
+      i
+    );
+  }) });
+}
+function OverlayFxNode({ item, tickMs }) {
+  const lifeMs = lifeMsOf(item, tickMs);
+  switch (item.effect ?? "sparkle") {
+    case "confetti":
+      return /* @__PURE__ */ jsx(ConfettiBurst, { item, lifeMs });
+    case "flash":
+      return /* @__PURE__ */ jsx(
+        Box,
+        {
+          position: "absolute",
+          className: "inset-0",
+          style: {
+            backgroundColor: item.color ?? "#ffffff",
+            opacity: 0,
+            animation: `fx-overlay-flash ${lifeMs}ms ease-out forwards`
+          }
+        }
+      );
+    case "streak-glow":
+      return /* @__PURE__ */ jsx(
+        Box,
+        {
+          position: "absolute",
+          className: "inset-0",
+          style: {
+            boxShadow: `inset 0 0 ${60 * (item.size ?? 1)}px ${item.color ?? "var(--color-warning)"}`,
+            opacity: 0,
+            animation: `fx-overlay-glow ${lifeMs}ms ease-in-out forwards`
+          }
+        }
+      );
+    case "float-text": {
+      if (!item.message) return null;
+      return /* @__PURE__ */ jsx(
+        Box,
+        {
+          position: "absolute",
+          style: {
+            left: `${(item.x ?? 0.5) * 100}%`,
+            top: `${(item.z ?? item.y ?? 0.4) * 100}%`,
+            color: item.color ?? "var(--color-success)",
+            fontWeight: 700,
+            fontSize: 16 * (item.size ?? 1),
+            textShadow: "0 1px 2px rgba(0,0,0,0.4)",
+            opacity: 0,
+            animation: `fx-overlay-float ${lifeMs}ms ease-out forwards`,
+            whiteSpace: "nowrap"
+          },
+          children: item.message
+        }
+      );
+    }
+    case "shake":
+      return null;
+    default:
+      return /* @__PURE__ */ jsx(SparkleBurst, { item, lifeMs });
+  }
+}
+var DEFAULT_TICK_MS2, FX_OVERLAY_KEYFRAMES, lifeMsOf, FxOverlay;
+var init_FxOverlay = __esm({
+  "components/core/molecules/FxOverlay.tsx"() {
+    "use client";
+    init_cn();
+    init_Box();
+    init_fx();
+    DEFAULT_TICK_MS2 = 500;
+    FX_OVERLAY_KEYFRAMES = `
+${CONFETTI_BURST_KEYFRAMES}
+@keyframes fx-overlay-flash {
+  0% { opacity: 0.75; }
+  100% { opacity: 0; }
+}
+@keyframes fx-overlay-glow {
+  0% { opacity: 0.9; }
+  60% { opacity: 0.6; }
+  100% { opacity: 0; }
+}
+@keyframes fx-overlay-sparkle {
+  0% { opacity: 0; transform: scale(0); }
+  30% { opacity: 1; transform: scale(1); }
+  100% { opacity: 0; transform: scale(0.3); }
+}
+@keyframes fx-overlay-float {
+  0% { opacity: 0; transform: translate(-50%, 8px); }
+  15% { opacity: 1; }
+  100% { opacity: 0; transform: translate(-50%, -40px); }
+}
+@keyframes fx-overlay-shake {
+  0% { transform: translateX(0); }
+  15% { transform: translateX(-6px); }
+  30% { transform: translateX(5px); }
+  45% { transform: translateX(-4px); }
+  60% { transform: translateX(3px); }
+  75% { transform: translateX(-2px); }
+  100% { transform: translateX(0); }
+}
+`;
+    lifeMsOf = (it, tickMs) => Math.max(it.maxTtl ?? it.ttl, it.ttl, 1) * tickMs;
+    FxOverlay = ({ items, tickMs = DEFAULT_TICK_MS2, children, className }) => {
+      const screenItems = (Array.isArray(items) ? items : []).filter(
+        (it) => Boolean(it) && typeof it.id === "string" && it.space !== "world"
+      );
+      const shakeItem = [...screenItems].reverse().find((it) => it.effect === "shake");
+      const overlay = /* @__PURE__ */ jsxs(
+        Box,
+        {
+          position: "absolute",
+          className: cn("inset-0 pointer-events-none overflow-hidden z-50", !children && className),
+          "aria-hidden": "true",
+          children: [
+            screenItems.map((it) => /* @__PURE__ */ jsx(OverlayFxNode, { item: it, tickMs }, it.id)),
+            /* @__PURE__ */ jsx("style", { children: FX_OVERLAY_KEYFRAMES })
+          ]
+        }
+      );
+      if (children !== void 0 && children !== null) {
+        return /* @__PURE__ */ jsxs(Box, { position: "relative", className, children: [
+          /* @__PURE__ */ jsx(
+            Box,
+            {
+              style: shakeItem ? { animation: `fx-overlay-shake ${Math.min(lifeMsOf(shakeItem, tickMs), 600)}ms ease-in-out` } : void 0,
+              children
+            },
+            shakeItem?.id ?? "steady"
+          ),
+          overlay
+        ] });
+      }
+      return overlay;
+    };
+    FxOverlay.displayName = "FxOverlay";
+  }
+});
 function computePopoverStyle(position, triggerRect, popoverWidth) {
   if (position === "left" || position === "right") {
     return {
@@ -30133,7 +30556,7 @@ var init_MathCanvas = __esm({
               x: mapX((first.x + last.x) / 2),
               y: (mapY(region.samples[mid].y) + mapY(baseline)) / 2,
               text: region.label,
-              color: "#111827",
+              color,
               fontSize: 11
             });
           }
@@ -30166,14 +30589,14 @@ var init_MathCanvas = __esm({
             const px = mapX(guide.at);
             out.push({ type: "line", x1: px, y1: margin, x2: px, y2: height - margin, color, dash });
             if (guide.label) {
-              out.push({ type: "text", x: px + 4, y: margin + 10, text: guide.label, color: "#111827", fontSize: 11 });
+              out.push({ type: "text", x: px + 4, y: margin + 10, text: guide.label, color, fontSize: 11 });
             }
           } else {
             if (guide.at < yMin || guide.at > yMax) continue;
             const py = mapY(guide.at);
             out.push({ type: "line", x1: margin, y1: py, x2: width - margin, y2: py, color, dash });
             if (guide.label) {
-              out.push({ type: "text", x: width - margin - 4, y: py - 8, text: guide.label, color: "#111827", fontSize: 11, align: "right" });
+              out.push({ type: "text", x: width - margin - 4, y: py - 8, text: guide.label, color, fontSize: 11, align: "right" });
             }
           }
         }
@@ -30239,7 +30662,7 @@ var init_MathCanvas = __esm({
               x: (x1 + x2) / 2,
               y: xAxisY - peak - 8,
               text: hop.label,
-              color: "#111827",
+              color,
               fontSize: 10,
               align: "center"
             });
@@ -30266,7 +30689,7 @@ var init_MathCanvas = __esm({
               x: mapX(angle.x + 1.35 * radius * Math.cos(rad)),
               y: mapY(angle.y + 1.35 * radius * Math.sin(rad)),
               text: angle.label,
-              color: "#111827",
+              color,
               fontSize: 11,
               align: "center"
             });
@@ -30284,7 +30707,7 @@ var init_MathCanvas = __esm({
             fill: isOpen ? "#ffffff" : p.color ?? "#dc2626"
           });
           if (p.label) {
-            out.push({ type: "text", x: mapX(p.x) + 8, y: mapY(p.y) - 8, text: p.label, color: "#111827", fontSize: 12 });
+            out.push({ type: "text", x: mapX(p.x) + 8, y: mapY(p.y) - 8, text: p.label, color: p.color ?? "#111827", fontSize: 12 });
           }
         }
         for (const v of vectors) {
@@ -30295,7 +30718,7 @@ var init_MathCanvas = __esm({
           const y2 = mapY(v.y + v.vy);
           out.push({ type: "arrow", x1, y1, x2, y2, color: v.color ?? "#7c3aed", lineWidth: 2 });
           if (v.label) {
-            out.push({ type: "text", x: x2 + 6, y: y2 - 6, text: v.label, color: "#111827", fontSize: 12 });
+            out.push({ type: "text", x: x2 + 6, y: y2 - 6, text: v.label, color: v.color ?? "#7c3aed", fontSize: 12 });
           }
         }
         out.push(...shapes);
@@ -31559,13 +31982,13 @@ var init_MapView = __esm({
         shadowSize: [41, 41]
       });
       L.Marker.prototype.options.icon = defaultIcon;
-      const { useEffect: useEffect64, useRef: useRef63, useCallback: useCallback96, useState: useState94 } = React87__default;
+      const { useEffect: useEffect65, useRef: useRef64, useCallback: useCallback97, useState: useState95 } = React87__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 }) {
         const map = useMap();
-        const prevRef = useRef63({ centerLat, centerLng, zoom });
-        useEffect64(() => {
+        const prevRef = useRef64({ centerLat, centerLng, zoom });
+        useEffect65(() => {
           const prev = prevRef.current;
           if (prev.centerLat !== centerLat || prev.centerLng !== centerLng || prev.zoom !== zoom) {
             map.setView([centerLat, centerLng], zoom);
@@ -31576,7 +31999,7 @@ var init_MapView = __esm({
       }
       function MapClickHandler({ onMapClick }) {
         const map = useMap();
-        useEffect64(() => {
+        useEffect65(() => {
           if (!onMapClick) return;
           const handler = (e) => {
             onMapClick(e.latlng.lat, e.latlng.lng);
@@ -31604,8 +32027,8 @@ var init_MapView = __esm({
         showAttribution = true
       }) {
         const eventBus = useEventBus2();
-        const [clickedPosition, setClickedPosition] = useState94(null);
-        const handleMapClick = useCallback96((lat, lng) => {
+        const [clickedPosition, setClickedPosition] = useState95(null);
+        const handleMapClick = useCallback97((lat, lng) => {
           if (showClickedPin) {
             setClickedPosition({ lat, lng });
           }
@@ -31614,7 +32037,7 @@ var init_MapView = __esm({
             eventBus.emit(`UI:${mapClickEvent}`, { latitude: lat, longitude: lng });
           }
         }, [onMapClick, mapClickEvent, eventBus, showClickedPin]);
-        const handleMarkerClick = useCallback96((marker) => {
+        const handleMarkerClick = useCallback97((marker) => {
           onMarkerClick?.(marker);
           if (markerClickEvent) {
             eventBus.emit(`UI:${markerClickEvent}`, { ...marker });
@@ -41846,6 +42269,7 @@ var init_DetailPanel = __esm({
     init_Box();
     init_Stack();
     init_SimpleGrid();
+    init_Menu();
     init_LoadingState();
     init_ErrorState();
     init_EmptyState();
@@ -41863,6 +42287,7 @@ var init_DetailPanel = __esm({
       avatar,
       sections: propSections,
       actions,
+      maxInlineActions,
       backAction,
       footer,
       slideOver = false,
@@ -42097,7 +42522,7 @@ var init_DetailPanel = __esm({
             }
           ) }),
           /* @__PURE__ */ jsxs(HStack, { justify: "end", align: "center", gap: "xs", children: [
-            otherActions.map((action, idx) => /* @__PURE__ */ jsx(
+            (maxInlineActions != null ? otherActions.slice(0, maxInlineActions) : otherActions).map((action, idx) => /* @__PURE__ */ jsx(
               Button,
               {
                 variant: action.variant || "secondary",
@@ -42112,6 +42537,22 @@ var init_DetailPanel = __esm({
               },
               idx
             )),
+            maxInlineActions != null && otherActions.length > maxInlineActions && /* @__PURE__ */ jsx(
+              Menu,
+              {
+                position: "bottom-end",
+                trigger: /* @__PURE__ */ jsx(Button, { variant: "ghost", size: "sm", "aria-label": t("common.actions"), "data-testid": "action-overflow", children: /* @__PURE__ */ jsx(Icon, { name: "more-horizontal", size: "xs" }) }),
+                items: otherActions.slice(maxInlineActions).map((action) => ({
+                  // ONE firing path: onClick → handleActionClick (emits with
+                  // the {id, row} payload). Passing `event` too would make
+                  // Menu emit a second, payload-less copy of the same event.
+                  label: action.label,
+                  icon: action.icon,
+                  variant: action.variant === "danger" ? "danger" : "default",
+                  onClick: () => handleActionClick(action, normalizedData)
+                }))
+              }
+            ),
             /* @__PURE__ */ jsx(
               Button,
               {
@@ -47968,6 +48409,7 @@ var init_component_registry_generated = __esm({
     init_DocSidebar();
     init_DocTOC();
     init_DocumentViewer();
+    init_DrawFxLayer();
     init_DrawGroup();
     init_DrawMesh();
     init_DrawShape();
@@ -47998,6 +48440,7 @@ var init_component_registry_generated = __esm({
     init_FormField();
     init_FormSection();
     init_FormSectionHeader();
+    init_FxOverlay();
     init_GameAudioToggle();
     init_GameHud();
     init_GameIcon();
@@ -48238,6 +48681,7 @@ var init_component_registry_generated = __esm({
       "DocSidebar": DocSidebar,
       "DocTOC": DocTOC,
       "DocumentViewer": DocumentViewer,
+      "DrawFxLayer": DrawFxLayer,
       "DrawGroup": DrawGroup,
       "DrawMesh": DrawMesh,
       "DrawShape": DrawShape,
@@ -48268,6 +48712,7 @@ var init_component_registry_generated = __esm({
       "FormField": FormField,
       "FormLayout": FormLayout,
       "FormSectionHeader": FormSectionHeader,
+      "FxOverlay": FxOverlay,
       "GameAudioToggle": GameAudioToggle,
       "GameHud": GameHud,
       "GameIcon": GameIcon,
@@ -50732,12 +51177,18 @@ function ServerBridgeProvider({
           } else if (effectType === "navigate") {
             const route = effect[1];
             const rawParams = effect[2];
+            const rawOptions = effect[3];
+            const optionsObj = rawOptions !== null && rawOptions !== void 0 && typeof rawOptions === "object" && !Array.isArray(rawOptions) ? rawOptions : void 0;
+            const crumb = typeof optionsObj?.crumb === "string" ? optionsObj.crumb : void 0;
             effects.push({
               type: "navigate",
               route,
               params: rawParams !== null && rawParams !== void 0 && typeof rawParams === "object" && !Array.isArray(rawParams) ? rawParams : void 0,
+              crumb,
               traitName
             });
+          } else if (effectType === "navigate-back") {
+            effects.push({ type: "navigate-back", traitName });
           } else if (effectType === "notify") {
             const message = effect[1];
             effects.push({ type: "notify", message: typeof message === "string" ? message : void 0, traitName });
@@ -51002,5 +51453,169 @@ function GameAudioProvider2({
   return /* @__PURE__ */ jsx(GameAudioContext2.Provider, { value, children });
 }
 GameAudioProvider2.displayName = "GameAudioProvider";
+function derivePageLabel(name) {
+  const stripped = name.endsWith("Page") && name.length > 4 ? name.slice(0, -4) : name;
+  return stripped.replace(/([a-z0-9])([A-Z])/g, "$1 $2");
+}
+function normalizePath(p) {
+  let normalized = p.trim();
+  if (!normalized.startsWith("/")) normalized = "/" + normalized;
+  if (normalized.length > 1 && normalized.endsWith("/")) {
+    normalized = normalized.slice(0, -1);
+  }
+  return normalized;
+}
+function matchNavPage(pages, path) {
+  const hit = matchPathAmong(pages, path, (p) => p.path);
+  return hit ? hit.candidate : null;
+}
+function seedAncestors(pages, path) {
+  const segments = normalizePath(path).split("/").filter(Boolean);
+  const ancestors = [];
+  for (let depth = 1; depth < segments.length; depth++) {
+    const prefix = "/" + segments.slice(0, depth).join("/");
+    const page = matchNavPage(pages, prefix);
+    if (page) {
+      ancestors.push({ href: prefix, label: derivePageLabel(page.name) });
+    }
+  }
+  return ancestors;
+}
+function syncNavStack(state, pages, path, pending) {
+  const normalized = normalizePath(path);
+  const page = matchNavPage(pages, normalized);
+  if (!page) return { state, orbital: null };
+  const label = pending && normalizePath(pending.href) === normalized ? pending.crumb : derivePageLabel(page.name);
+  const prior = state[page.orbital];
+  const stack = prior && prior.length > 0 ? [...prior] : seedAncestors(pages, normalized);
+  const existing = stack.findIndex((e) => e.href === normalized);
+  if (existing >= 0) {
+    stack.length = existing + 1;
+    if (pending && normalizePath(pending.href) === normalized) {
+      stack[existing] = { href: normalized, label };
+    }
+  } else {
+    stack.push({ href: normalized, label });
+  }
+  return { state: { ...state, [page.orbital]: stack }, orbital: page.orbital };
+}
+function previousEntry(state, pages, path) {
+  const page = matchNavPage(pages, normalizePath(path));
+  if (!page) return null;
+  const stack = state[page.orbital] ?? [];
+  return stack.length >= 2 ? stack[stack.length - 2] : null;
+}
+function entriesFor(state, pages, path) {
+  const page = matchNavPage(pages, normalizePath(path));
+  if (!page) return [];
+  return state[page.orbital] ?? [];
+}
+var INERT_API = {
+  entries: [],
+  canGoBack: false,
+  beginNavigate: () => void 0,
+  back: () => void 0,
+  goTo: () => void 0
+};
+var NavStackContext = createContext(INERT_API);
+function useNavStack2() {
+  return useContext(NavStackContext);
+}
+function loadStored(storageKey) {
+  if (!storageKey) return {};
+  try {
+    const raw = window.sessionStorage.getItem(storageKey);
+    if (!raw) return {};
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+    return {};
+  } catch {
+    return {};
+  }
+}
+function persistStored(storageKey, state) {
+  if (!storageKey) return;
+  try {
+    window.sessionStorage.setItem(storageKey, JSON.stringify(state));
+  } catch {
+  }
+}
+var NavStackProvider = ({
+  pages,
+  currentPath,
+  navigate,
+  storageKey,
+  children
+}) => {
+  const [state, setState] = useState(() => loadStored(storageKey));
+  const pendingCrumbRef = useRef(null);
+  const stateRef = useRef(state);
+  stateRef.current = state;
+  useEffect(() => {
+    const pending = pendingCrumbRef.current;
+    pendingCrumbRef.current = null;
+    setState((prev) => {
+      const next = syncNavStack(prev, pages, currentPath, pending);
+      if (next.state !== prev) persistStored(storageKey, next.state);
+      return next.state;
+    });
+  }, [currentPath, pages, storageKey]);
+  const beginNavigate = useCallback((href, crumb) => {
+    pendingCrumbRef.current = crumb !== void 0 && crumb !== "" ? { href, crumb } : null;
+  }, []);
+  const back = useCallback(() => {
+    const prev = previousEntry(stateRef.current, pages, currentPath);
+    if (prev) navigate(prev.href);
+  }, [pages, currentPath, navigate]);
+  const goTo = useCallback(
+    (href) => {
+      navigate(href);
+    },
+    [navigate]
+  );
+  const entries = useMemo(
+    () => entriesFor(state, pages, currentPath),
+    [state, pages, currentPath]
+  );
+  const api = useMemo(
+    () => ({
+      entries,
+      canGoBack: previousEntry(state, pages, currentPath) !== null,
+      beginNavigate,
+      back,
+      goTo
+    }),
+    [entries, state, pages, currentPath, beginNavigate, back, goTo]
+  );
+  return /* @__PURE__ */ jsx(NavStackContext.Provider, { value: api, children });
+};
+NavStackProvider.displayName = "NavStackProvider";
+var NavStackRouterBridge = ({
+  pages,
+  storageKey = "almadar:navstack",
+  children
+}) => {
+  const location = useLocation();
+  const routerNavigate = useNavigate();
+  const navigate = useCallback(
+    (path) => {
+      routerNavigate(path);
+    },
+    [routerNavigate]
+  );
+  return /* @__PURE__ */ jsx(
+    NavStackProvider,
+    {
+      pages,
+      currentPath: location.pathname,
+      navigate,
+      storageKey,
+      children
+    }
+  );
+};
+NavStackRouterBridge.displayName = "NavStackRouterBridge";
 
-export { CurrentPagePathContext, CurrentPagePathProvider, EntityBindingContext, EntitySchemaProvider, EventBusContext2 as EventBusContext, EventBusProvider, GameAudioContext2 as GameAudioContext, GameAudioProvider2 as GameAudioProvider, NavigationProvider2 as NavigationProvider, OfflineModeProvider, OrbitalProvider, OrbitalThemeProvider, SelectionContext, SelectionProvider, ServerBridgeProvider, TraitContext, TraitProvider, TraitScopeProvider3 as TraitScopeProvider, UserContext, UserProvider, VerificationProvider, comparePathSpecificity2 as comparePathSpecificity, extractRouteParams2 as extractRouteParams, findPageByName2 as findPageByName, findPageByPath2 as findPageByPath, getAllPages2 as getAllPages, getDefaultPage2 as getDefaultPage, matchPath2 as matchPath, matchPathAmong2 as matchPathAmong, pathMatches2 as pathMatches, useActivePage2 as useActivePage, useCurrentPagePath2 as useCurrentPagePath, useEntityBindingSnapshot2 as useEntityBindingSnapshot, useEntitySchema, useEntitySchemaOptional6 as useEntitySchemaOptional, useGameAudioContext2 as useGameAudioContext, useGameAudioContextOptional2 as useGameAudioContextOptional, useHasPermission, useHasRole, useInitPayload2 as useInitPayload, useNavigateTo2 as useNavigateTo, useNavigation2 as useNavigation, useNavigationId2 as useNavigationId, useNavigationState2 as useNavigationState, useOfflineMode, useOptionalOfflineMode, useSelection, useSelectionOptional, useServerBridge, useTrait, useTraitContext, useTraitScope2 as useTraitScope, useTraitScopeChain2 as useTraitScopeChain, useUser, useUserForEvaluation };
+export { CurrentPagePathContext, CurrentPagePathProvider, EntityBindingContext, EntitySchemaProvider, EventBusContext2 as EventBusContext, EventBusProvider, GameAudioContext2 as GameAudioContext, GameAudioProvider2 as GameAudioProvider, NavStackProvider, NavStackRouterBridge, NavigationProvider2 as NavigationProvider, OfflineModeProvider, OrbitalProvider, OrbitalThemeProvider, SelectionContext, SelectionProvider, ServerBridgeProvider, TraitContext, TraitProvider, TraitScopeProvider3 as TraitScopeProvider, UserContext, UserProvider, VerificationProvider, comparePathSpecificity2 as comparePathSpecificity, extractRouteParams2 as extractRouteParams, findPageByName2 as findPageByName, findPageByPath2 as findPageByPath, getAllPages2 as getAllPages, getDefaultPage2 as getDefaultPage, matchPath2 as matchPath, matchPathAmong2 as matchPathAmong, pathMatches2 as pathMatches, useActivePage2 as useActivePage, useCurrentPagePath2 as useCurrentPagePath, useEntityBindingSnapshot2 as useEntityBindingSnapshot, useEntitySchema, useEntitySchemaOptional6 as useEntitySchemaOptional, useGameAudioContext2 as useGameAudioContext, useGameAudioContextOptional2 as useGameAudioContextOptional, useHasPermission, useHasRole, useInitPayload2 as useInitPayload, useNavStack2 as useNavStack, useNavigateTo2 as useNavigateTo, useNavigation2 as useNavigation, useNavigationId2 as useNavigationId, useNavigationState2 as useNavigationState, useOfflineMode, useOptionalOfflineMode, useSelection, useSelectionOptional, useServerBridge, useTrait, useTraitContext, useTraitScope2 as useTraitScope, useTraitScopeChain2 as useTraitScopeChain, useUser, useUserForEvaluation };