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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shellui/core",
-  "version": "0.2.0-alpha.3",
+  "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.3"
+    "@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,9 +34,18 @@ 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
 
   useEffect(() => {
     if (!iframeRef.current) {
@@ -58,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)
@@ -87,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);
         }
       },
     );
@@ -102,105 +130,85 @@ export const ContentView = ({
     return () => {
       cleanup();
     };
-  }, [pathPrefix, navigate]);
+  }, [pathPrefix, navigate, navItem]);
+
+  const scheduleReveal = (reveal: () => void) => {
+    const doReveal = () => {
+      const elapsed = Date.now() - mountTimeRef.current;
+      if (elapsed < MIN_LOADING_MS) {
+        const timer = setTimeout(doReveal, MIN_LOADING_MS - elapsed);
+        cancelRevealRef.current = () => {
+          clearTimeout(timer);
+          cancelRevealRef.current = null;
+        };
+        return;
+      }
+      reveal();
+    };
+    requestAnimationFrame(() => requestAnimationFrame(doReveal));
+  };
 
-  // Hide loading overlay when iframe sends SHELLUI_INITIALIZED
+  // 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) {
-          setIsLoading(false);
-        }
+        if (event.source !== iframeRef.current?.contentWindow) return;
+        if (!ignoreMessages) lastLoadedIframeUrl = urlRef.current;
+        cancelRevealRef.current?.();
+        let cancelled = false;
+        cancelRevealRef.current = () => {
+          cancelled = true;
+          cancelRevealRef.current = null;
+        };
+        scheduleReveal(() => {
+          if (!cancelled) setIsLoading(false);
+          cancelRevealRef.current = null;
+        });
       },
     );
-    return () => cleanup();
-  }, []);
+    return () => {
+      cancelRevealRef.current?.();
+      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(() => {
       logger.info('ContentView: Timeout expired, hiding loading overlay');
-      setIsLoading(false);
-    }, 400);
+      cancelRevealRef.current?.();
+      let cancelled = false;
+      cancelRevealRef.current = () => {
+        cancelled = true;
+        cancelRevealRef.current = null;
+      };
+      scheduleReveal(() => {
+        if (!cancelled) setIsLoading(false);
+        cancelRevealRef.current = null;
+      });
+    }, LOADING_OVERLAY_DURATION_MS);
     return () => clearTimeout(timeoutId);
   }, [isLoading]);
 
   // Handle external URL changes (e.g. from Sidebar)
   useEffect(() => {
-    if (iframeRef.current && !isInternalNavigation.current) {
-      // Only update iframe src if it's actually different from its current src
-      // to avoid unnecessary reloads
+    if (iframeRef.current) {
       if (iframeRef.current.src !== url) {
         iframeRef.current.src = url;
-        setIsLoading(true);
+        // 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
+        }
       }
     }
-  }, [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 });
-      }
-    };
-
-    // 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(() => {
@@ -234,19 +242,28 @@ export const ContentView = ({
   }, []);
 
   return (
-    <div style={{ width: '100%', height: '100%', display: 'flex', position: 'relative' }}>
+    <div
+      style={{ width: '100%', height: '100%', display: 'flex', position: 'relative' }}
+      className="bg-background"
+    >
       {/* Note: allow-same-origin is required for same-origin iframe content (e.g., Vite dev server, cookies, localStorage).
           While this allows the iframe to remove its own sandboxing, it's acceptable here because the iframe content
           is trusted microfrontend content from the same application origin.
           Browser security warnings about this combination cannot be suppressed programmatically. */}
+      {/* Strategy to prevent browser deprioritizing iframe rendering:
+          - loading="eager" explicitly requests immediate loading (not deferred)
+          - opacity:0 hides the iframe during loading while keeping it in the rendering pipeline
+          - Reveal is instant (no transition) after deferred double-rAF to avoid blink */}
       <iframe
         ref={iframeRef}
         src={initialUrl}
+        loading="eager"
         style={{
           width: '100%',
           height: '100%',
           border: 'none',
           display: 'block',
+          opacity: isLoading ? 0 : 1,
         }}
         sandbox="allow-same-origin allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox"
         referrerPolicy="no-referrer-when-downgrade"

package/src/components/LoadingOverlay.tsx

@@ -1,10 +1,14 @@
+import { LOADING_OVERLAY_DURATION_MS } from '../constants';
+
 export function LoadingOverlay() {
   return (
-    <div className="absolute inset-0 z-10 flex flex-col bg-background">
+    <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/AppBarLayout.tsx

@@ -61,8 +61,7 @@ function TopBarEndItem({
   const pathPrefix = getNavPathPrefix(item);
   const isOverlay = item.openIn === 'modal' || item.openIn === 'drawer';
   const isExternal = item.openIn === 'external';
-  const isActive =
-    !isOverlay && !isExternal && pathPrefix === activePathPrefix;
+  const isActive = !isOverlay && !isExternal && pathPrefix === activePathPrefix;
 
   const faviconUrl = isExternal && !item.icon ? getExternalFaviconUrl(item.url) : null;
   const iconSrc = item.icon ?? faviconUrl ?? null;

package/src/features/layouts/DefaultLayout.tsx

@@ -99,8 +99,7 @@ const NavigationContent = ({
     const pathPrefix = getNavPathPrefix(navItem);
     const isOverlay = navItem.openIn === 'modal' || navItem.openIn === 'drawer';
     const isExternal = navItem.openIn === 'external';
-    const isActive =
-      !isOverlay && !isExternal && pathPrefix === activePathPrefix;
+    const isActive = !isOverlay && !isExternal && pathPrefix === activePathPrefix;
     const itemLabel = resolveLocalizedString(navItem.label, currentLanguage);
     const faviconUrl = isExternal && !navItem.icon ? getExternalFaviconUrl(navItem.url) : null;
     const iconSrc = navItem.icon ?? faviconUrl ?? null;
@@ -434,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);
@@ -471,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));
@@ -482,7 +486,7 @@ const MobileBottomNav = ({
       overflowItems: overflow,
       hasMore: overflow.length > 0,
     };
-  }, [items, rowWidth]);
+  }, [items, rowWidth, showHomeButton]);
 
   useEffect(() => {
     setExpanded(false);
@@ -519,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
@@ -582,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]);
 
@@ -638,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/WindowsLayout.tsx

@@ -6,11 +6,13 @@ import {
   useEffect,
   type PointerEvent as ReactPointerEvent,
 } from 'react';
+import { useLocation } from 'react-router';
 import { useTranslation } from 'react-i18next';
 import { shellui } from '@shellui/sdk';
 import type { NavigationItem, NavigationGroup } from '../config/types';
 import {
   flattenNavigationItems,
+  getActivePathPrefix,
   getNavPathPrefix,
   resolveLocalizedString as resolveNavLabel,
   splitNavigationByPosition,
@@ -121,13 +123,16 @@ function AppWindow({
   const resizeRafRef = useRef<number | null>(null);
   const pendingResizeBoundsRef = useRef<WindowState['bounds'] | null>(null);
 
-  useEffect(() => {
-    setBounds(win.bounds);
-  }, [win.bounds]);
+  // Use a ref for onBoundsChange to avoid it in effect deps (prevents infinite render loop).
+  // The parent creates a new callback reference on every render (inline arrow), so including
+  // it in a dependency array would re-fire the effect every render, triggering a state update
+  // in the parent, which re-renders, which re-fires the effect → React error #185.
+  const onBoundsChangeRef = useRef(onBoundsChange);
+  onBoundsChangeRef.current = onBoundsChange;
 
   useEffect(() => {
-    onBoundsChange(bounds);
-  }, [bounds, onBoundsChange]);
+    onBoundsChangeRef.current(bounds);
+  }, [bounds]);
 
   // When maximized, keep filling the viewport on window resize
   useEffect(() => {
@@ -504,6 +509,7 @@ export function WindowsLayout({
   logo: _logo,
   navigation,
 }: WindowsLayoutProps) {
+  const location = useLocation();
   const { i18n } = useTranslation();
   const { settings } = useSettings();
   const currentLanguage = i18n.language || 'en';
@@ -523,6 +529,7 @@ export function WindowsLayout({
   const [startMenuOpen, setStartMenuOpen] = useState(false);
   const [now, setNow] = useState(() => new Date());
   const startPanelRef = useRef<HTMLDivElement>(null);
+  const initialOpenFromUrlDoneRef = useRef(false);
 
   // Update date/time every second for taskbar clock
   useEffect(() => {
@@ -568,6 +575,20 @@ export function WindowsLayout({
     [currentLanguage, windows.length],
   );
 
+  // On first load only: open a window for the current URL if it matches a nav item (no reaction to later URL changes)
+  useEffect(() => {
+    if (initialOpenFromUrlDoneRef.current) return;
+    initialOpenFromUrlDoneRef.current = true;
+    const pathname = location.pathname;
+    const windowableItems = navigationItems.filter(
+      (i) => i.openIn !== 'modal' && i.openIn !== 'drawer' && i.openIn !== 'external',
+    );
+    const pathPrefix = getActivePathPrefix(pathname, windowableItems);
+    if (!pathPrefix) return;
+    const item = windowableItems.find((i) => getNavPathPrefix(i) === pathPrefix);
+    if (item) openWindow(item);
+  }, [location.pathname, navigationItems, openWindow]);
+
   const closeWindow = useCallback((id: string) => {
     setWindows((prev) => prev.filter((w) => w.id !== id));
     setFrontWindowId((current) => (current === id ? null : current));

package/src/features/layouts/utils.ts

@@ -5,19 +5,42 @@ 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 {
+export function getActivePathPrefix(pathname: string, items: NavigationItem[]): string | null {
   const linkItems = items.filter(
     (i) => i.openIn !== 'modal' && i.openIn !== 'drawer' && i.openIn !== 'external',
   );
   const matching = linkItems
     .map((i) => getNavPathPrefix(i))
-    .filter(
-      (p) => pathname === p || pathname.startsWith(p === '/' ? '/' : p + '/'),
-    );
+    .filter((p) => pathname === p || pathname.startsWith(p === '/' ? '/' : `${p}/`));
   if (matching.length === 0) return null;
   return matching.reduce((a, b) => (a.length >= b.length ? a : b));
 }

package/src/features/settings/SettingsProvider.tsx

@@ -65,8 +65,7 @@ function getResolvedAppearanceForSettings(
 ): Appearance | undefined {
   if (typeof window === 'undefined') return undefined;
   config?.themes?.forEach(registerTheme);
-  const themeName =
-    settings.appearance?.name || config?.defaultTheme || 'default';
+  const themeName = settings.appearance?.name || config?.defaultTheme || 'default';
   const themeDef = getTheme(themeName) || getTheme('default');
   if (!themeDef) return undefined;
   const colorScheme = settings.appearance?.colorScheme ?? 'system';
@@ -135,13 +134,13 @@ function buildSettingsForPropagation(
     };
   }
   if (config?.navigation?.length) {
-    const items: SettingsNavigationItem[] = flattenNavigationItems(
-      config.navigation,
-    ).map((item) => ({
-      path: item.path,
-      url: item.url,
-      label: resolveLabel(item.label, lang),
-    }));
+    const items: SettingsNavigationItem[] = flattenNavigationItems(config.navigation).map(
+      (item) => ({
+        path: item.path,
+        url: item.url,
+        label: resolveLabel(item.label, lang),
+      }),
+    );
     result = { ...result, navigation: { items } };
   }
   return result;
@@ -292,9 +291,12 @@ export function SettingsProvider({ children }: { children: ReactNode }) {
               ...defaultAppearance,
               ...parsed.appearance,
               // Migrate from legacy theme/themeName
-              name: parsed.appearance?.name ?? parsed.appearance?.themeName ?? defaultAppearance.name,
+              name:
+                parsed.appearance?.name ?? parsed.appearance?.themeName ?? defaultAppearance.name,
               colorScheme:
-                parsed.appearance?.colorScheme ?? parsed.appearance?.theme ?? defaultAppearance.colorScheme,
+                parsed.appearance?.colorScheme ??
+                parsed.appearance?.theme ??
+                defaultAppearance.colorScheme,
               colors: parsed.appearance?.colors ?? defaultAppearance.colors,
             },
             language: {

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;
 };