@shellui/core 0.2.0-alpha.4 → 0.2.0-beta.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shellui/core",
-  "version": "0.2.0-alpha.4",
+  "version": "0.2.0-beta.0",
   "description": "ShellUI Core - Core React application runtime",
   "main": "src/index.ts",
   "type": "module",
@@ -58,7 +58,7 @@
     "workbox-strategies": "^7.1.0",
     "workbox-cacheable-response": "^7.1.0",
     "workbox-expiration": "^7.1.0",
-    "@shellui/sdk": "0.2.0-alpha.4"
+    "@shellui/sdk": "0.2.0-beta.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",

package/src/app.tsx

@@ -33,7 +33,7 @@ const AppContent = () => {
       unregisterServiceWorker();
       return;
     }
-    const serviceWorkerEnabled = settings?.serviceWorker?.enabled ?? true; // Default to enabled
+    const serviceWorkerEnabled = settings?.serviceWorker?.enabled ?? false; // Default to enabled
 
     // Don't register service worker if navigation is empty or undefined
     // This helps prevent issues in development or misconfigured apps

package/src/components/ContentView.tsx

@@ -1,5 +1,6 @@
 /* eslint-disable no-console */
 import type { NavigationItem } from '../features/config/types';
+import { isHashRouterNavItem, getHashPathFromUrl } from '../features/layouts/utils';
 import {
   addIframe,
   removeIframe,
@@ -10,10 +11,14 @@ import {
 } from '@shellui/sdk';
 import { useEffect, useRef, useState } from 'react';
 import { useNavigate } from 'react-router';
+import { LOADING_OVERLAY_DURATION_MS } from '../constants';
 import { LoadingOverlay } from './LoadingOverlay';
 
 const logger = getLogger('shellcore');
 
+/** URL of the last main-content iframe that sent SHELLUI_INITIALIZED. Used to skip the loading overlay when navigating between nav items that point to the same app URL. */
+let lastLoadedIframeUrl: string | null = null;
+
 interface ContentViewProps {
   url: string;
   pathPrefix: string;
@@ -29,11 +34,16 @@ export const ContentView = ({
 }: ContentViewProps) => {
   const navigate = useNavigate();
   const iframeRef = useRef<HTMLIFrameElement>(null);
-  const isInternalNavigation = useRef(false);
   const cancelRevealRef = useRef<(() => void) | null>(null);
   const mountTimeRef = useRef(Date.now());
+  const urlRef = useRef(url);
+  urlRef.current = url;
   const [initialUrl] = useState(url);
-  const [isLoading, setIsLoading] = useState(true);
+  const [isLoading, setIsLoading] = useState(() => {
+    // Skip overlay when same app URL was just loaded (e.g. switching App ↔ Root with same url)
+    if (!ignoreMessages && url === lastLoadedIframeUrl) return false;
+    return true;
+  });
 
   const MIN_LOADING_MS = 80; // Don't reveal before this, reduces blink from theme/layout paint
 
@@ -62,23 +72,44 @@ export const ContentView = ({
         }
 
         const { pathname, search, hash } = data.payload as ShellUIUrlPayload;
-        // Remove leading slash and trailing slashes from iframe pathname
-        let cleanPathname = pathname.startsWith(navItem.url)
-          ? pathname.slice(navItem.url.length)
-          : pathname;
-        cleanPathname = cleanPathname.startsWith('/') ? cleanPathname.slice(1) : cleanPathname;
-        cleanPathname = cleanPathname.replace(/\/+$/, ''); // Remove trailing slashes
-        // Construct the new path without trailing slashes
-        let newShellPath = cleanPathname
-          ? `/${pathPrefix}/${cleanPathname}${search}${hash}`
-          : `/${pathPrefix}${search}${hash}`;
+        // Shell URL is always path + search only (no hash) so it's transparent whether the sub-app uses hash routing or not
+        let pathSegment: string;
+        if (isHashRouterNavItem(navItem) && hash) {
+          // Hash-router app: use path relative to nav item's hash (e.g. nav #/themes, iframe #/themes → segment ''; iframe #/themes/foo → segment 'foo')
+          const iframeHashPath = hash.replace(/^#\/?/, '').replace(/\/+$/, '') || '';
+          const navHashPath = getHashPathFromUrl(navItem.url).replace(/^\/+|\/+$/g, '');
+          const relative = navHashPath
+            ? iframeHashPath === navHashPath || iframeHashPath.startsWith(`${navHashPath}/`)
+              ? iframeHashPath.slice(navHashPath.length).replace(/^\//, '')
+              : iframeHashPath
+            : iframeHashPath;
+          pathSegment = relative;
+        } else {
+          // Non-hash app: route is pathname
+          let cleanPathname = pathname.startsWith(navItem.url)
+            ? pathname.slice(navItem.url.length)
+            : pathname;
+          cleanPathname = cleanPathname.startsWith('/') ? cleanPathname.slice(1) : cleanPathname;
+          pathSegment = cleanPathname.replace(/\/+$/, '');
+        }
+        // Root (pathPrefix '' or '/') must produce /segment not //segment
+        const isRoot = pathPrefix === '' || pathPrefix === '/';
+        let newShellPath = isRoot
+          ? pathSegment
+            ? `/${pathSegment}${search}`
+            : search
+              ? `/${search}`
+              : '/'
+          : pathSegment
+            ? `/${pathPrefix}/${pathSegment}${search}`
+            : `/${pathPrefix}${search}`;
 
-        // Normalize: remove trailing slashes from pathname part only (preserve query/hash)
+        // Normalize: remove trailing slashes from pathname part only (preserve query)
         const urlParts = newShellPath.match(/^([^?#]*)([?#].*)?$/);
         if (urlParts) {
           const pathnamePart = urlParts[1].replace(/\/+$/, '') || '/';
-          const queryHashPart = urlParts[2] || '';
-          newShellPath = pathnamePart + queryHashPart;
+          const queryPart = urlParts[2] || '';
+          newShellPath = pathnamePart + queryPart;
         }
 
         // Normalize current path for comparison (remove trailing slashes from pathname)
@@ -91,14 +122,7 @@ export const ContentView = ({
         const normalizedNewPath = normalizedNewPathname + (newPathParts?.[2] || '');
 
         if (currentPath !== normalizedNewPath) {
-          // Mark this navigation as internal so we don't try to "push" it back to the iframe
-          isInternalNavigation.current = true;
-          navigate(newShellPath, { replace: true });
-
-          // Reset the flag after a short delay to allow the render cycle to complete
-          setTimeout(() => {
-            isInternalNavigation.current = false;
-          }, 100);
+          navigate(newShellPath);
         }
       },
     );
@@ -106,7 +130,7 @@ export const ContentView = ({
     return () => {
       cleanup();
     };
-  }, [pathPrefix, navigate]);
+  }, [pathPrefix, navigate, navItem]);
 
   const scheduleReveal = (reveal: () => void) => {
     const doReveal = () => {
@@ -126,11 +150,13 @@ export const ContentView = ({
 
   // Hide loading overlay when iframe sends SHELLUI_INITIALIZED.
   // Defer reveal (double rAF + min time) so the iframe has time to apply theme and paint.
+  // Remember this URL so we can skip the overlay when navigating to the same app (e.g. App ↔ Root).
   useEffect(() => {
     const cleanup = shellui.addMessageListener(
       'SHELLUI_INITIALIZED',
       (_data: ShellUIMessage, event: MessageEvent) => {
         if (event.source !== iframeRef.current?.contentWindow) return;
+        if (!ignoreMessages) lastLoadedIframeUrl = urlRef.current;
         cancelRevealRef.current?.();
         let cancelled = false;
         cancelRevealRef.current = () => {
@@ -148,9 +174,9 @@ export const ContentView = ({
       cancelRevealRef.current = null;
       cleanup();
     };
-  }, []);
+  }, [ignoreMessages]);
 
-  // Fallback: hide overlay after 400ms if SHELLUI_INITIALIZED was not received.
+  // Fallback: hide overlay after LOADING_OVERLAY_DURATION_MS if SHELLUI_INITIALIZED was not received.
   useEffect(() => {
     if (!isLoading) return;
     const timeoutId = setTimeout(() => {
@@ -165,83 +191,24 @@ export const ContentView = ({
         if (!cancelled) setIsLoading(false);
         cancelRevealRef.current = null;
       });
-    }, 400);
+    }, LOADING_OVERLAY_DURATION_MS);
     return () => clearTimeout(timeoutId);
   }, [isLoading]);
 
   // Handle external URL changes (e.g. from Sidebar)
   useEffect(() => {
-    if (iframeRef.current && !isInternalNavigation.current) {
+    if (iframeRef.current) {
       if (iframeRef.current.src !== url) {
         iframeRef.current.src = url;
-        setIsLoading(true);
-        mountTimeRef.current = Date.now(); // apply min delay for this load too
-      }
-    }
-  }, [url]);
-
-  // Inject script to prevent "Layout was forced" warning by deferring layout until stylesheets load
-  useEffect(() => {
-    const iframe = iframeRef.current;
-    if (!iframe) return;
-
-    const handleLoad = () => {
-      try {
-        const iframeWindow = iframe.contentWindow;
-        const iframeDoc = iframe.contentDocument || iframeWindow?.document;
-        if (!iframeDoc || !iframeWindow) return;
-
-        // Inject a script that waits for stylesheets before allowing layout calculations
-        const script = iframeDoc.createElement('script');
-        script.textContent = `
-          (function() {
-            // Wait for all stylesheets to load
-            function waitForStylesheets() {
-              const styleSheets = Array.from(document.styleSheets);
-              const pendingSheets = styleSheets.filter(function(sheet) {
-                try {
-                  return sheet.cssRules === null;
-                } catch (e) {
-                  return false; // Cross-origin stylesheets, assume loaded
-                }
-              });
-              
-              if (pendingSheets.length === 0) {
-                // All stylesheets loaded
-                return;
-              }
-              
-              // Check again after a short delay
-              setTimeout(waitForStylesheets, 10);
-            }
-            
-            // Start checking after DOM is ready
-            if (document.readyState === 'complete') {
-              waitForStylesheets();
-            } else {
-              window.addEventListener('load', waitForStylesheets);
-            }
-          })();
-        `;
-        iframeDoc.head.appendChild(script);
-      } catch (error) {
-        // Cross-origin or other errors - ignore (this is expected for some iframes)
-        logger.debug('Could not inject stylesheet wait script:', { error });
+        // Skip overlay when switching to the same app URL (e.g. App ↔ Root); different app still shows overlay
+        const sameAppAlreadyLoaded = !ignoreMessages;
+        if (!sameAppAlreadyLoaded) {
+          setIsLoading(true);
+          mountTimeRef.current = Date.now(); // apply min delay for this load too
+        }
       }
-    };
-
-    // Wait for iframe to load before injecting script
-    iframe.addEventListener('load', handleLoad);
-
-    // Also try immediately if already loaded
-    if (iframe.contentDocument?.readyState === 'complete') {
-      handleLoad();
     }
-
-    return () => {
-      iframe.removeEventListener('load', handleLoad);
-    };
-  }, [initialUrl]);
+  }, [url, ignoreMessages]);
 
   // Suppress browser warnings that are expected and acceptable
   useEffect(() => {

package/src/components/LoadingOverlay.tsx

@@ -1,10 +1,14 @@
+import { LOADING_OVERLAY_DURATION_MS } from '../constants';
+
 export function LoadingOverlay() {
   return (
     <div className="absolute inset-x-0 top-0 z-10">
       <div className="h-1 w-full overflow-hidden bg-muted/30">
         <div
           className="h-full w-0 bg-muted-foreground/50"
-          style={{ animation: 'loading-bar-slide 400ms linear infinite' }}
+          style={{
+            animation: `loading-bar-slide ${LOADING_OVERLAY_DURATION_MS}ms linear infinite`,
+          }}
         />
       </div>
     </div>

package/src/components/NotFoundView.tsx

@@ -37,7 +37,12 @@ export const NotFoundView = () => {
       : [];
 
   const handleNavigate = (path: string) => {
-    shellui.navigate(path.startsWith('/') ? path : `/${path}`);
+    const targetPath = path.startsWith('/') ? path : `/${path}`;
+    if (window.self !== window.top) {
+      shellui.navigate(targetPath);
+    } else {
+      window.location.href = targetPath;
+    }
   };
 
   return (

package/src/components/ViewRoute.tsx

@@ -1,6 +1,11 @@
 import { useMemo } from 'react';
 import { Navigate, useLocation } from 'react-router';
-import { getNavPathPrefix } from '../features/layouts/utils';
+import {
+  getNavPathPrefix,
+  isHashRouterNavItem,
+  getBaseUrlWithoutHash,
+  getHashPathFromUrl,
+} from '../features/layouts/utils';
 import { ContentView } from './ContentView';
 import type { NavigationItem } from '../features/config/types';
 
@@ -19,7 +24,22 @@ export const ViewRoute = ({ navigation }: ViewRouteProps) => {
     });
   }, [navigation, pathname]);
 
-  if (!navItem) {
+  // When no nav matches (e.g. /layout on refresh): use root item (path '' or '/') with pathname as hash subpath to avoid 404
+  const rootItem = useMemo(
+    () => navigation.find((item) => item.path === '' || item.path === '/'),
+    [navigation],
+  );
+  const useRootFallback = !navItem && rootItem && pathname !== '/';
+  const actualNavItem = navItem ?? (useRootFallback ? rootItem : null);
+  const actualSubPath = useRootFallback
+    ? pathname.replace(/^\//, '')
+    : actualNavItem
+      ? pathname.length > getNavPathPrefix(actualNavItem).length
+        ? pathname.slice(getNavPathPrefix(actualNavItem).length + 1)
+        : ''
+      : '';
+
+  if (!actualNavItem) {
     return (
       <Navigate
         to="/"
@@ -27,22 +47,28 @@ export const ViewRoute = ({ navigation }: ViewRouteProps) => {
       />
     );
   }
-  // Calculate the relative path from the navItem.path
-  // e.g. if item.path is "docs" and pathname is "/docs/intro", subPath is "intro"
-  const pathPrefix = getNavPathPrefix(navItem);
-  const subPath = pathname.length > pathPrefix.length ? pathname.slice(pathPrefix.length + 1) : '';
+  const subPath = actualSubPath;
 
-  // Construct the final URL for the iframe
-  let finalUrl = navItem.url;
-  if (subPath) {
-    const baseUrl = navItem.url.endsWith('/') ? navItem.url : `${navItem.url}/`;
-    finalUrl = `${baseUrl}${subPath}`;
+  // Construct the final URL for the iframe (non-hash: base + path; hash app: preserve nav url hash path + subPath)
+  let finalUrl: string;
+  if (isHashRouterNavItem(actualNavItem)) {
+    const base = getBaseUrlWithoutHash(actualNavItem.url).replace(/\/$/, '');
+    const navHashPath = getHashPathFromUrl(actualNavItem.url).replace(/^\/+|\/+$/g, '');
+    const segments = [navHashPath, subPath].filter(Boolean);
+    const fullHashPath = `/${segments.join('/')}`;
+    finalUrl = `${base}#${fullHashPath}`;
+  } else {
+    finalUrl = actualNavItem.url;
+    if (subPath) {
+      const baseUrl = actualNavItem.url.endsWith('/') ? actualNavItem.url : `${actualNavItem.url}/`;
+      finalUrl = `${baseUrl}${subPath}`;
+    }
   }
   return (
     <ContentView
       url={finalUrl}
-      pathPrefix={navItem.path}
-      navItem={navItem}
+      pathPrefix={actualNavItem.path}
+      navItem={actualNavItem}
     />
   );
 };

package/src/constants.ts

@@ -0,0 +1,2 @@
+/** Duration (ms) for loading overlay: fallback timeout and bar animation. */
+export const LOADING_OVERLAY_DURATION_MS = 1000;

package/src/features/config/types.ts

@@ -26,6 +26,8 @@ export interface NavigationItem {
   hiddenOnDesktop?: boolean;
   /** How to open this link: 'default' (navigate in main area), 'modal', 'drawer', or 'external' (target="_blank"). */
   openIn?: 'default' | 'modal' | 'drawer' | 'external';
+  /** When true, the app uses hash-based routing (e.g. /#/path). If omitted, inferred from url containing /#/. */
+  useHashRouter?: boolean;
   /** Optional drawer position when openIn === 'drawer'. Default is 'right' if omitted. */
   drawerPosition?: DrawerPosition;
   /** Sidebar position: 'start' (default) or 'end'. End items are rendered in the sidebar footer. */

package/src/features/layouts/DefaultLayout.tsx

@@ -433,13 +433,16 @@ const HomeIcon = ({ className }: { className?: string }) => (
   </svg>
 );
 
-/** Mobile bottom nav: Home + nav items; More only when not all fit. Dynamic from width. Reuses HOMEPAGE_NAV_ITEM for label. */
+/** Mobile bottom nav: optional Home + nav items; More only when not all fit. Dynamic from width. Reuses HOMEPAGE_NAV_ITEM for label. Home is shown only when no nav item is defined for "/". */
 const MobileBottomNav = ({
   items,
   currentLanguage,
+  showHomeButton,
 }: {
   items: NavigationItem[];
   currentLanguage: string;
+  /** When false, do not show the Home button (e.g. when a nav item for "/" exists). */
+  showHomeButton: boolean;
 }) => {
   const location = useLocation();
   const [expanded, setExpanded] = useState(false);
@@ -470,9 +473,11 @@ const MobileBottomNav = ({
     const computedSlots =
       rowWidth > 0 ? Math.floor((contentWidth + BOTTOM_NAV_GAP) / slotTotal) : 5;
     const totalSlots = Math.min(Math.max(0, computedSlots), BOTTOM_NAV_MAX_SLOTS);
-    const slotsForNav = totalSlots - 1;
+    const slotsForNav = showHomeButton ? totalSlots - 1 : totalSlots;
     const allFit = list.length <= slotsForNav;
-    const maxInRow = allFit ? list.length : Math.max(0, totalSlots - 2);
+    const maxInRow = allFit
+      ? list.length
+      : Math.max(0, showHomeButton ? totalSlots - 2 : totalSlots - 1);
     const row = list.slice(0, maxInRow);
     const rowPaths = new Set(row.map((i) => i.path));
     const overflow = list.filter((item) => !rowPaths.has(item.path));
@@ -481,7 +486,7 @@ const MobileBottomNav = ({
       overflowItems: overflow,
       hasMore: overflow.length > 0,
     };
-  }, [items, rowWidth]);
+  }, [items, rowWidth, showHomeButton]);
 
   useEffect(() => {
     setExpanded(false);
@@ -518,25 +523,27 @@ const MobileBottomNav = ({
         paddingBottom: 'calc(0.5rem + env(safe-area-inset-bottom, 0px))',
       }}
     >
-      {/* Top row: Home + nav items + More/Less — single row, no wrap */}
+      {/* Top row: optional Home + nav items + More/Less — single row, no wrap */}
       <div className="flex flex-row flex-nowrap items-center justify-center gap-1 px-3 overflow-x-hidden">
-        <Link
-          to="/"
-          className={cn(
-            'flex flex-col items-center justify-center gap-1 rounded-md py-1.5 px-2 min-w-0 transition-colors cursor-pointer focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
-            location.pathname === '/' || location.pathname === ''
-              ? 'bg-sidebar-accent text-sidebar-accent-foreground [&_span]:text-sidebar-accent-foreground'
-              : 'text-sidebar-foreground/80 hover:bg-sidebar-accent/50 hover:text-sidebar-foreground [&_span]:inherit',
-          )}
-          aria-label={resolveNavLabel(HOMEPAGE_NAV_ITEM.label, currentLanguage) || 'Home'}
-        >
-          <span className="size-4 shrink-0 flex items-center justify-center [&_svg]:text-current">
-            <HomeIcon className="size-4" />
-          </span>
-          <span className="text-[11px] leading-tight">
-            {resolveNavLabel(HOMEPAGE_NAV_ITEM.label, currentLanguage) || 'Home'}
-          </span>
-        </Link>
+        {showHomeButton && (
+          <Link
+            to="/"
+            className={cn(
+              'flex flex-col items-center justify-center gap-1 rounded-md py-1.5 px-2 min-w-0 transition-colors cursor-pointer focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
+              location.pathname === '/' || location.pathname === ''
+                ? 'bg-sidebar-accent text-sidebar-accent-foreground [&_span]:text-sidebar-accent-foreground'
+                : 'text-sidebar-foreground/80 hover:bg-sidebar-accent/50 hover:text-sidebar-foreground [&_span]:inherit',
+            )}
+            aria-label={resolveNavLabel(HOMEPAGE_NAV_ITEM.label, currentLanguage) || 'Home'}
+          >
+            <span className="size-4 shrink-0 flex items-center justify-center [&_svg]:text-current">
+              <HomeIcon className="size-4" />
+            </span>
+            <span className="text-[11px] leading-tight">
+              {resolveNavLabel(HOMEPAGE_NAV_ITEM.label, currentLanguage) || 'Home'}
+            </span>
+          </Link>
+        )}
         {rowItems.map((item, i) => renderItem(item, i))}
         {hasMore && (
           <button
@@ -581,17 +588,19 @@ const DefaultLayoutContent = ({ title, logo, navigation }: DefaultLayoutProps) =
   const { i18n } = useTranslation();
   const currentLanguage = i18n.language || 'en';
 
-  const { startNav, endItems, navigationItems, mobileNavItems } = useMemo(() => {
+  const { startNav, endItems, navigationItems, mobileNavItems, hasRootNavItem } = useMemo(() => {
     const desktopNav = filterNavigationByViewport(navigation, 'desktop');
     const mobileNav = filterNavigationByViewport(navigation, 'mobile');
     const { start, end } = splitNavigationByPosition(desktopNav);
     const flat = flattenNavigationItems(desktopNav);
     const mobileFlat = flattenNavigationItems(mobileNav);
+    const hasRoot = flat.some((item) => item.path === '' || item.path === '/');
     return {
       startNav: filterNavigationForSidebar(start),
       endItems: end,
       navigationItems: flat,
       mobileNavItems: mobileFlat,
+      hasRootNavItem: hasRoot,
     };
   }, [navigation]);
 
@@ -637,10 +646,11 @@ const DefaultLayoutContent = ({ title, logo, navigation }: DefaultLayoutProps) =
             </main>
           </div>
 
-          {/* Mobile bottom nav: visible only below md */}
+          {/* Mobile bottom nav: visible only below md; Home button only when no view for / */}
           <MobileBottomNav
             items={mobileNavItems}
             currentLanguage={currentLanguage}
+            showHomeButton={!hasRootNavItem}
           />
         </OverlayShell>
       </SidebarProvider>

package/src/features/layouts/OverlayShell.tsx

@@ -9,7 +9,12 @@ import { Toaster } from '../../components/ui/sonner';
 import { ContentView } from '../../components/ContentView';
 import { useModal } from '../modal/ModalContext';
 import { useDrawer } from '../drawer/DrawerContext';
-import { getNavPathPrefix, resolveLocalizedString } from './utils';
+import {
+  getNavPathPrefix,
+  getBaseUrlWithoutHash,
+  isHashRouterNavItem,
+  resolveLocalizedString,
+} from './utils';
 
 interface OverlayShellProps {
   navigationItems: NavigationItem[];
@@ -43,8 +48,39 @@ export function OverlayShell({ navigationItems, children }: OverlayShellProps) {
       const rawUrl = payload?.url;
       if (typeof rawUrl !== 'string' || !rawUrl.trim()) return;
 
+      closeModal();
+      closeDrawer();
+
       let pathname: string;
-      if (rawUrl.startsWith('http://') || rawUrl.startsWith('https://')) {
+
+      // Hash-based URL (e.g. http://localhost:5173/#/themes/foo): show non-hash path in shell, match by nav item base URL
+      if (rawUrl.includes('/#/')) {
+        try {
+          const parsed = new URL(rawUrl);
+          const hashPart = parsed.hash.slice(1); // strip leading #
+          const hashPath = hashPart.startsWith('/') ? hashPart : `/${hashPart}`;
+          const baseUrl = getBaseUrlWithoutHash(rawUrl);
+          const navItem = navigationItems.find(
+            (item) => isHashRouterNavItem(item) && getBaseUrlWithoutHash(item.url) === baseUrl,
+          );
+          if (!navItem) {
+            shellui.toast({
+              type: 'error',
+              title: t('navigationError') ?? 'Navigation error',
+              description:
+                t('navigationNotAllowed') ?? 'This URL is not configured in the app navigation.',
+            });
+            return;
+          }
+          const pathPrefix = getNavPathPrefix(navItem);
+          pathname =
+            hashPath === '/' || hashPath === ''
+              ? pathPrefix
+              : `${pathPrefix.replace(/\/$/, '')}${hashPath}`;
+        } catch {
+          pathname = rawUrl.startsWith('/') ? rawUrl : `/${rawUrl}`;
+        }
+      } else if (rawUrl.startsWith('http://') || rawUrl.startsWith('https://')) {
         try {
           pathname = new URL(rawUrl).pathname;
         } catch {
@@ -54,9 +90,6 @@ export function OverlayShell({ navigationItems, children }: OverlayShellProps) {
         pathname = rawUrl.startsWith('/') ? rawUrl : `/${rawUrl}`;
       }
 
-      closeModal();
-      closeDrawer();
-
       const isHomepage = pathname === '/' || pathname === '';
       const isAllowed =
         isHomepage ||

package/src/features/layouts/utils.ts

@@ -5,6 +5,34 @@ export function getNavPathPrefix(item: NavigationItem): string {
   return item.path === '/' || item.path === '' ? '/' : `/${item.path}`;
 }
 
+/** Whether a URL string uses hash-based routing (e.g. contains /#/). */
+export function isHashRouterUrl(url: string): boolean {
+  return url.includes('/#/');
+}
+
+/** Whether a nav item uses hash-based routing (explicit flag or inferred from url). */
+export function isHashRouterNavItem(item: NavigationItem): boolean {
+  if (item.useHashRouter === true) return true;
+  if (item.useHashRouter === false) return false;
+  return isHashRouterUrl(item.url);
+}
+
+/** Base URL without hash (origin + pathname before #). Used to match and build iframe URLs for hash apps. */
+export function getBaseUrlWithoutHash(url: string): string {
+  const hashIndex = url.indexOf('#');
+  if (hashIndex === -1) return url;
+  const base = url.slice(0, hashIndex);
+  return base.endsWith('/') ? base : `${base}/`;
+}
+
+/** Hash path from a URL (part after #), e.g. "/themes" from "http://localhost:5173/#/themes". Returns "" if no hash. */
+export function getHashPathFromUrl(url: string): string {
+  const hashIndex = url.indexOf('#');
+  if (hashIndex === -1) return '';
+  const hash = url.slice(hashIndex + 1);
+  return hash.startsWith('/') ? hash : `/${hash}`;
+}
+
 /** Among items that match the current pathname, return the longest path prefix. Used so only one nav item is active when URLs nest (e.g. /foo and /foo/bar). */
 export function getActivePathPrefix(pathname: string, items: NavigationItem[]): string | null {
   const linkItems = items.filter(

package/src/features/settings/SettingsView.tsx

@@ -184,7 +184,7 @@ export const SettingsView = () => {
   // Navigate back to settings root
   const handleBackToSettings = useCallback(() => {
     // Navigate to settings root, replacing current history entry
-    navigate(urls.settings, { replace: true });
+    navigate(urls.settings);
   }, [navigate]);
 
   return (

package/src/router/routes.tsx

@@ -109,8 +109,18 @@ export const createRoutes = (config: ShellUIConfig): RouteObject[] => {
         ),
       });
     });
+    // Catch-all: no nav match (e.g. /layout) → ViewRoute can use root item with pathname as hash subpath to avoid 404
+    (layoutRoute.children as RouteObject[]).push({
+      path: '*',
+      element: (
+        <Suspense fallback={<RouteFallback />}>
+          <ViewRoute navigation={navigationItems} />
+        </Suspense>
+      ),
+    });
   }
-  (routes[0].children as RouteObject[]).push(layoutRoute);
+  // Layout must be before the catch-all (*) so paths like /layout are handled by layout → ViewRoute (root fallback), not 404
+  (routes[0].children as RouteObject[]).unshift(layoutRoute);
 
   return routes;
 };