@shellui/core 0.2.0-alpha.3 → 0.2.0-alpha.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shellui/core",
-  "version": "0.2.0-alpha.3",
+  "version": "0.2.0-alpha.4",
   "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-alpha.4"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",

package/src/components/ContentView.tsx

@@ -30,9 +30,13 @@ export const ContentView = ({
   const navigate = useNavigate();
   const iframeRef = useRef<HTMLIFrameElement>(null);
   const isInternalNavigation = useRef(false);
+  const cancelRevealRef = useRef<(() => void) | null>(null);
+  const mountTimeRef = useRef(Date.now());
   const [initialUrl] = useState(url);
   const [isLoading, setIsLoading] = useState(true);
 
+  const MIN_LOADING_MS = 80; // Don't reveal before this, reduces blink from theme/layout paint
+
   useEffect(() => {
     if (!iframeRef.current) {
       return;
@@ -104,25 +108,63 @@ export const ContentView = ({
     };
   }, [pathPrefix, navigate]);
 
-  // Hide loading overlay when iframe sends SHELLUI_INITIALIZED
+  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.
+  // Defer reveal (double rAF + min time) so the iframe has time to apply theme and paint.
   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;
+        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();
+    };
   }, []);
 
-  // Fallback: hide overlay after 400ms if SHELLUI_INITIALIZED was not received
+  // Fallback: hide overlay after 400ms if SHELLUI_INITIALIZED was not received.
   useEffect(() => {
     if (!isLoading) return;
     const timeoutId = setTimeout(() => {
       logger.info('ContentView: Timeout expired, hiding loading overlay');
-      setIsLoading(false);
+      cancelRevealRef.current?.();
+      let cancelled = false;
+      cancelRevealRef.current = () => {
+        cancelled = true;
+        cancelRevealRef.current = null;
+      };
+      scheduleReveal(() => {
+        if (!cancelled) setIsLoading(false);
+        cancelRevealRef.current = null;
+      });
     }, 400);
     return () => clearTimeout(timeoutId);
   }, [isLoading]);
@@ -130,11 +172,10 @@ export const ContentView = ({
   // 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.src !== url) {
         iframeRef.current.src = url;
         setIsLoading(true);
+        mountTimeRef.current = Date.now(); // apply min delay for this load too
       }
     }
   }, [url]);
@@ -234,19 +275,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,6 +1,6 @@
 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"

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;

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

@@ -6,18 +6,13 @@ export function getNavPathPrefix(item: NavigationItem): string {
 }
 
 /** 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: {