@almadar/ui 5.153.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';
@@ -21326,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",
         {
@@ -21346,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,
@@ -21372,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(
@@ -31967,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);
@@ -31984,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);
@@ -32012,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 });
           }
@@ -32022,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 });
@@ -42254,6 +42269,7 @@ var init_DetailPanel = __esm({
     init_Box();
     init_Stack();
     init_SimpleGrid();
+    init_Menu();
     init_LoadingState();
     init_ErrorState();
     init_EmptyState();
@@ -42271,6 +42287,7 @@ var init_DetailPanel = __esm({
       avatar,
       sections: propSections,
       actions,
+      maxInlineActions,
       backAction,
       footer,
       slideOver = false,
@@ -42505,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",
@@ -42520,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,
               {
@@ -51144,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 });
@@ -51414,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 };

package/dist/runtime/index.cjs

@@ -21034,17 +21034,27 @@ var init_Breadcrumb = __esm({
     init_useEventBus();
     Breadcrumb = ({
       items,
+      fromNavStack = false,
+      itemEvent,
       separator = "chevron-right",
       maxItems,
       className
     }) => {
       const eventBus = useEventBus();
       const { t } = hooks.useTranslate();
-      const displayItems = maxItems && items.length > maxItems ? [
-        ...items.slice(0, 1),
+      const navStack = providers.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__ */ jsxRuntime.jsx(
         "nav",
         {
@@ -21054,7 +21064,7 @@ var init_Breadcrumb = __esm({
             const isLast = index === displayItems.length - 1;
             const isEllipsis = item.label === "...";
             return /* @__PURE__ */ jsxRuntime.jsxs("li", { className: "flex items-center gap-2", children: [
-              isEllipsis ? /* @__PURE__ */ jsxRuntime.jsx(Typography, { variant: "small", color: "muted", children: item.label }) : item.href || item.path ? /* @__PURE__ */ jsxRuntime.jsxs(
+              isEllipsis ? /* @__PURE__ */ jsxRuntime.jsx(Typography, { variant: "small", color: "muted", children: item.label }) : (item.href || item.path) && !item.event && !fromNavStack ? /* @__PURE__ */ jsxRuntime.jsxs(
                 "a",
                 {
                   href: item.href || item.path,
@@ -21080,7 +21090,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(
@@ -41679,6 +41694,7 @@ var init_DetailPanel = __esm({
     init_Box();
     init_Stack();
     init_SimpleGrid();
+    init_Menu();
     init_LoadingState();
     init_ErrorState();
     init_EmptyState();
@@ -41696,6 +41712,7 @@ var init_DetailPanel = __esm({
       avatar,
       sections: propSections,
       actions,
+      maxInlineActions,
       backAction,
       footer,
       slideOver = false,
@@ -41930,7 +41947,7 @@ var init_DetailPanel = __esm({
             }
           ) }),
           /* @__PURE__ */ jsxRuntime.jsxs(HStack, { justify: "end", align: "center", gap: "xs", children: [
-            otherActions.map((action, idx) => /* @__PURE__ */ jsxRuntime.jsx(
+            (maxInlineActions != null ? otherActions.slice(0, maxInlineActions) : otherActions).map((action, idx) => /* @__PURE__ */ jsxRuntime.jsx(
               Button,
               {
                 variant: action.variant || "secondary",
@@ -41945,6 +41962,22 @@ var init_DetailPanel = __esm({
               },
               idx
             )),
+            maxInlineActions != null && otherActions.length > maxInlineActions && /* @__PURE__ */ jsxRuntime.jsx(
+              Menu,
+              {
+                position: "bottom-end",
+                trigger: /* @__PURE__ */ jsxRuntime.jsx(Button, { variant: "ghost", size: "sm", "aria-label": t("common.actions"), "data-testid": "action-overflow", children: /* @__PURE__ */ jsxRuntime.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__ */ jsxRuntime.jsx(
               Button,
               {
@@ -49389,7 +49422,7 @@ function runTickFrame(entityId, orderedWriters, store) {
 }
 var log3 = logger.createLogger("almadar:ui:effects:client-handlers");
 function createClientEffectHandlers(options) {
-  const { eventBus, slotSetter, navigate, notify, callService, liveEntity } = options;
+  const { eventBus, slotSetter, navigate, navigateBack, notify, callService, liveEntity } = options;
   return {
     emit: (event, payload, source) => {
       const prefixedEvent = event.startsWith("UI:") ? event : `UI:${event}`;
@@ -49439,6 +49472,9 @@ function createClientEffectHandlers(options) {
       }
       log3.warn("No navigate handler, ignoring", { path });
     }),
+    navigateBack: navigateBack ?? (() => {
+      log3.warn("No navigate-back handler, ignoring");
+    }),
     notify: notify ?? ((msg, type) => {
       log3.debug("notify", { type, message: msg });
     })
@@ -50078,6 +50114,7 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
         }
       },
       navigate: optionsRef.current?.navigate,
+      navigateBack: optionsRef.current?.navigateBack,
       notify: optionsRef.current?.notify,
       callService: optionsRef.current?.callService,
       // The canonical client `set` writes `(set @entity.X)` straight into
@@ -50139,6 +50176,7 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
         emit: clientHandlers.emit,
         renderUI: clientHandlers.renderUI,
         navigate: clientHandlers.navigate,
+        navigateBack: clientHandlers.navigateBack,
         notify: clientHandlers.notify
       };
     }
@@ -50861,7 +50899,7 @@ function normalizeChild(child) {
     props: { ...rest, ...normalizedChildren !== void 0 ? { children: normalizedChildren } : {} }
   };
 }
-function applyServerEffects(effects, uiSlots, onNavigate, embeddedTraits, activeTraits) {
+function applyServerEffects(effects, uiSlots, onNavigate, embeddedTraits, activeTraits, onNavigateBack) {
   for (const eff of effects) {
     if (eff.type === "render-ui" && eff.slot && eff.pattern) {
       if (eff.traitName && activeTraits && !activeTraits.has(eff.traitName)) {
@@ -50907,7 +50945,9 @@ function applyServerEffects(effects, uiSlots, onNavigate, embeddedTraits, active
         });
       }
     } else if (eff.type === "navigate" && eff.route && onNavigate) {
-      onNavigate(eff.route, eff.params);
+      onNavigate(eff.route, eff.params, eff.crumb);
+    } else if (eff.type === "navigate-back" && onNavigateBack) {
+      onNavigateBack();
     }
   }
 }
@@ -50930,7 +50970,17 @@ function collectServerActiveTraits(ir, allTraits, mountedTraitNames) {
   }
   return active;
 }
-function TraitInitializer({ traits: traits2, routeParams, orbitalNames, onNavigate, onLocalFallback, persistence, traitConfigsByName, orbitalsByTrait, embeddedTraits, serverActiveTraits, children }) {
+function NavStackRefBridge({ apiRef }) {
+  const api = providers.useNavStack();
+  React85.useEffect(() => {
+    apiRef.current = api;
+    return () => {
+      apiRef.current = null;
+    };
+  }, [api, apiRef]);
+  return null;
+}
+function TraitInitializer({ traits: traits2, routeParams, orbitalNames, onNavigate, onNavigateBack, onLocalFallback, persistence, traitConfigsByName, orbitalsByTrait, embeddedTraits, serverActiveTraits, children }) {
   const bridge = providers.useServerBridge();
   const activeTraitNames = React85.useMemo(
     () => new Set(traits2.map((b) => b.trait.name).filter((n) => !!n)),
@@ -50956,10 +51006,10 @@ function TraitInitializer({ traits: traits2, routeParams, orbitalNames, onNaviga
     for (const name of targets) {
       const { effects, meta } = await bridge.sendEvent(name, event, withActiveTraits(payload));
       recordServerResponse(name, event, meta);
-      applyServerEffects(effects, uiSlots, onNavigate, embeddedTraits, activeTraitNames);
+      applyServerEffects(effects, uiSlots, onNavigate, embeddedTraits, activeTraitNames, onNavigateBack);
     }
-  }, [bridge.connected, bridge.sendEvent, orbitalNames, uiSlots, onNavigate, embeddedTraits, activeTraitNames, withActiveTraits]);
-  const opts = orbitalNames ? { onEventProcessed, navigate: onNavigate, traitConfigsByName, orbitalsByTrait, embeddedTraits, initPayload: routeParams } : { navigate: onNavigate, persistence, traitConfigsByName, orbitalsByTrait, embeddedTraits, initPayload: routeParams };
+  }, [bridge.connected, bridge.sendEvent, orbitalNames, uiSlots, onNavigate, onNavigateBack, embeddedTraits, activeTraitNames, withActiveTraits]);
+  const opts = orbitalNames ? { onEventProcessed, navigate: onNavigate, navigateBack: onNavigateBack, traitConfigsByName, orbitalsByTrait, embeddedTraits, initPayload: routeParams } : { navigate: onNavigate, navigateBack: onNavigateBack, persistence, traitConfigsByName, orbitalsByTrait, embeddedTraits, initPayload: routeParams };
   const { sendEvent, entityBindingSource } = useTraitStateMachine(traits2, uiSlots, opts);
   const initSentRef = React85.useRef(false);
   const prevTraitsRef = React85.useRef(void 0);
@@ -51018,13 +51068,13 @@ function TraitInitializer({ traits: traits2, routeParams, orbitalNames, onNaviga
           effects: effectTraces,
           timestamp: Date.now()
         });
-        applyServerEffects(effects, uiSlots, onNavigate, embeddedTraits, activeTraitNames);
+        applyServerEffects(effects, uiSlots, onNavigate, embeddedTraits, activeTraitNames, onNavigateBack);
       }
     })();
-  }, [bridge.connected, orbitalNames, bridge.sendEvent, uiSlots, onNavigate, embeddedTraits, activeTraitNames, withActiveTraits, routeParams]);
+  }, [bridge.connected, orbitalNames, bridge.sendEvent, uiSlots, onNavigate, onNavigateBack, embeddedTraits, activeTraitNames, withActiveTraits, routeParams]);
   return /* @__PURE__ */ jsxRuntime.jsx(providers.EntityBindingContext.Provider, { value: entityBindingSource, children });
 }
-function SchemaRunner({ schema, serverUrl, transport, mockData, pageName, routeParams, onNavigate, onLocalFallback, persistence }) {
+function SchemaRunner({ schema, serverUrl, transport, mockData, pageName, routeParams, onNavigate, onNavigateBack, onLocalFallback, persistence }) {
   const { traits: traits2, allEntities, allTraits, ir } = useResolvedSchema(schema, pageName);
   const allPageTraits = React85.useMemo(() => {
     let base;
@@ -51172,6 +51222,7 @@ function SchemaRunner({ schema, serverUrl, transport, mockData, pageName, routeP
           embeddedTraits,
           serverActiveTraits,
           onNavigate,
+          onNavigateBack,
           onLocalFallback,
           persistence,
           children: /* @__PURE__ */ jsxRuntime.jsx(providers.OrbitalThemeProvider, { theme: activeOrbitalTheme, children: /* @__PURE__ */ jsxRuntime.jsx(Box, { className: "h-full min-h-full overflow-auto p-4", children: /* @__PURE__ */ jsxRuntime.jsx(UISlotRenderer, { includeHud: true, hudMode: "inline", includeFloating: true }) }) })
@@ -51264,6 +51315,15 @@ function OrbPreview({
     const resolved = pages.find((p) => p.page.name === activePageName)?.page.path;
     return resolved ?? initialPagePath;
   }, [pages, currentPage, initialPagePath]);
+  const navPages = React85.useMemo(
+    () => pages.filter((p) => typeof p.page.path === "string" && p.page.path.length > 0).map((p) => ({ path: p.page.path, name: p.page.name, orbital: p.orbitalName })),
+    [pages]
+  );
+  const concreteCurrentPath = React85.useMemo(() => {
+    const pattern = currentPagePath ?? "/";
+    return pattern.replace(/:([A-Za-z0-9_]+)/g, (whole, key) => routeParams[key] ?? whole);
+  }, [currentPagePath, routeParams]);
+  const navStackRef = React85.useRef(null);
   const handleNavigate = React85.useCallback((path) => {
     const hit = providers.matchPathAmong(pages, path, (entry) => entry.page.path);
     const match = hit?.candidate;
@@ -51285,6 +51345,16 @@ function OrbPreview({
       }
     }
   }, [pages]);
+  const handleNavigateEffect = React85.useCallback(
+    (path, _params, crumb) => {
+      navStackRef.current?.beginNavigate(path, crumb);
+      handleNavigate(path);
+    },
+    [handleNavigate]
+  );
+  const handleNavigateBack = React85.useCallback(() => {
+    navStackRef.current?.back();
+  }, []);
   React85.useEffect(() => {
     const unsubscribe = eventBus.on("UI:NAVIGATE", (event) => {
       const url = event.payload?.url;
@@ -51337,20 +51407,33 @@ function OrbPreview({
       style: { height },
       children: [
         localFallback && /* @__PURE__ */ jsxRuntime.jsx(Box, { className: "px-3 py-2 bg-[var(--color-warning)] bg-opacity-10 border-b border-[var(--color-warning)] flex items-center gap-2", children: /* @__PURE__ */ jsxRuntime.jsx(Typography, { variant: "caption", className: "text-[var(--color-warning-foreground)] flex-1", children: "Preview server unreachable \u2014 running locally. Server-side state and persistence are disabled." }) }),
-        /* @__PURE__ */ jsxRuntime.jsx(providers.CurrentPagePathProvider, { value: currentPagePath, children: /* @__PURE__ */ jsxRuntime.jsx(providers.OrbitalProvider, { initialData: effectiveMockData, skipTheme: true, verification: true, isolated, children: /* @__PURE__ */ jsxRuntime.jsx(context.UISlotProvider, { children: /* @__PURE__ */ jsxRuntime.jsx(
-          SchemaRunner,
+        /* @__PURE__ */ jsxRuntime.jsx(providers.CurrentPagePathProvider, { value: currentPagePath, children: /* @__PURE__ */ jsxRuntime.jsxs(
+          providers.NavStackProvider,
           {
-            schema: parseResult.schema,
-            serverUrl,
-            transport,
-            mockData: effectiveMockData,
-            pageName: currentPage,
-            routeParams,
-            onNavigate: handleNavigate,
-            onLocalFallback: handleLocalFallback,
-            persistence
-          }
-        ) }) }) })
+            pages: navPages,
+            currentPath: concreteCurrentPath,
+            navigate: handleNavigate,
+            storageKey: `almadar:navstack:${parseResult.schema.name ?? "preview"}`,
+            children: [
+              /* @__PURE__ */ jsxRuntime.jsx(NavStackRefBridge, { apiRef: navStackRef }),
+              /* @__PURE__ */ jsxRuntime.jsx(providers.OrbitalProvider, { initialData: effectiveMockData, skipTheme: true, verification: true, isolated, children: /* @__PURE__ */ jsxRuntime.jsx(context.UISlotProvider, { children: /* @__PURE__ */ jsxRuntime.jsx(
+                SchemaRunner,
+                {
+                  schema: parseResult.schema,
+                  serverUrl,
+                  transport,
+                  mockData: effectiveMockData,
+                  pageName: currentPage,
+                  routeParams,
+                  onNavigate: handleNavigateEffect,
+                  onNavigateBack: handleNavigateBack,
+                  onLocalFallback: handleLocalFallback,
+                  persistence
+                }
+              ) }) })
+            ]
+          }
+        ) })
       ]
     }
   );