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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shellui/core",
-  "version": "0.2.0-alpha.2",
+  "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.2"
+    "@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

@@ -6,12 +6,13 @@ import {
   type Settings,
   type SettingsNavigationItem,
   type Appearance,
+  type SettingsAvailableTheme,
 } from '@shellui/sdk';
 import { SettingsContext } from './SettingsContext';
 import { useConfig } from '../config/useConfig';
 import { useTranslation } from 'react-i18next';
 import type { NavigationItem, NavigationGroup, ShellUIConfig } from '../config/types';
-import { getTheme, registerTheme } from '../theme/themes';
+import { getTheme, getAllThemes, registerTheme } from '../theme/themes';
 
 const logger = getLogger('shellcore');
 
@@ -40,6 +41,20 @@ function resolveColorMode(colorScheme: 'light' | 'dark' | 'system'): 'light' | '
   return colorScheme === 'dark' ? 'dark' : 'light';
 }
 
+/** Convert font file URLs to absolute so iframes/modals on other ports or domains can load them. */
+function toAbsoluteFontUrls(urls: string[]): string[] {
+  if (typeof window === 'undefined') return urls;
+  const origin = window.location.origin;
+  return urls.map((url) => {
+    const trimmed = url.trim();
+    if (trimmed.startsWith('http://') || trimmed.startsWith('https://')) {
+      return trimmed;
+    }
+    const path = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+    return `${origin}${path}`;
+  });
+}
+
 /**
  * Build the full appearance object for settings propagation so apps receive all theme
  * variable values and can style without knowing the theme name.
@@ -50,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';
@@ -75,13 +89,29 @@ function getResolvedAppearanceForSettings(
     ...(themeDef.textShadow !== undefined && { textShadow: themeDef.textShadow }),
     ...(themeDef.lineHeight !== undefined && { lineHeight: themeDef.lineHeight }),
     ...(themeDef.fontFiles !== undefined &&
-      themeDef.fontFiles.length > 0 && { fontFiles: themeDef.fontFiles }),
+      themeDef.fontFiles.length > 0 && {
+        fontFiles: toAbsoluteFontUrls(themeDef.fontFiles),
+      }),
   };
 }
 
 /**
- * Build settings for propagation to iframes: inject navigation and full theme object
- * so apps receive all theme variable values.
+ * Map registered themes to the slim shape sent to sub-apps (name, displayName, colors, optional typography for preview).
+ */
+function getAvailableThemesForSettings(): SettingsAvailableTheme[] {
+  return getAllThemes().map((theme) => ({
+    name: theme.name,
+    displayName: theme.displayName,
+    colors: theme.colors,
+    ...(theme.fontFamily !== undefined && { fontFamily: theme.fontFamily }),
+    ...(theme.letterSpacing !== undefined && { letterSpacing: theme.letterSpacing }),
+    ...(theme.textShadow !== undefined && { textShadow: theme.textShadow }),
+  }));
+}
+
+/**
+ * Build settings for propagation to iframes: inject navigation, full theme object,
+ * and list of available themes so apps can render theme pickers.
  */
 function buildSettingsForPropagation(
   settings: Settings,
@@ -93,14 +123,24 @@ function buildSettingsForPropagation(
     ...settings,
     appearance: appearance ?? settings.appearance,
   };
+  // Inject available themes when we have a resolved appearance (themes are already registered above)
+  if (result.appearance && typeof window !== 'undefined') {
+    result = {
+      ...result,
+      appearance: {
+        ...result.appearance,
+        availableThemes: getAvailableThemesForSettings(),
+      },
+    };
+  }
   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;
@@ -251,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/components/Appearance.tsx

@@ -4,8 +4,9 @@ import { useConfig } from '../../config/useConfig';
 import { Button } from '../../../components/ui/button';
 import { ButtonGroup } from '../../../components/ui/button-group';
 import { cn } from '../../../lib/utils';
-import { useEffect, useState } from 'react';
+import { useEffect, useState, useMemo } from 'react';
 import { getAllThemes, registerTheme, type ThemeDefinition } from '../../theme/themes';
+import type { SettingsAvailableTheme } from '@shellui/sdk';
 
 const SunIcon = () => (
   <svg
@@ -85,13 +86,19 @@ const MonitorIcon = () => (
   </svg>
 );
 
+/** Theme-like shape used for preview (ThemeDefinition or SettingsAvailableTheme). */
+type ThemePreviewItem = Pick<
+  ThemeDefinition | SettingsAvailableTheme,
+  'name' | 'displayName' | 'colors' | 'fontFamily' | 'letterSpacing' | 'textShadow'
+>;
+
 // Theme color preview component
 const ThemePreview = ({
   theme,
   isSelected,
   isDark,
 }: {
-  theme: ThemeDefinition;
+  theme: ThemePreviewItem;
   isSelected: boolean;
   isDark: boolean;
 }) => {
@@ -169,18 +176,25 @@ export const Appearance = () => {
   const currentTheme = settings.appearance?.colorScheme ?? 'system';
   const currentThemeName = settings.appearance?.name ?? 'default';
 
-  const [availableThemes, setAvailableThemes] = useState<ThemeDefinition[]>([]);
+  const [localThemes, setLocalThemes] = useState<ThemeDefinition[]>([]);
 
-  // Register custom themes from config and get all themes
+  // Register custom themes from config and get all themes (for shell context)
   useEffect(() => {
     if (config?.themes) {
       config.themes.forEach((themeDef: ThemeDefinition) => {
         registerTheme(themeDef);
       });
     }
-    setAvailableThemes(getAllThemes());
+    setLocalThemes(getAllThemes());
   }, [config]);
 
+  // Use availableThemes from settings when provided (e.g. from shell when in sub-app), else local registry
+  const availableThemes = useMemo((): ThemePreviewItem[] => {
+    const fromSettings = settings.appearance?.availableThemes;
+    if (fromSettings?.length) return fromSettings;
+    return localThemes;
+  }, [settings.appearance?.availableThemes, localThemes]);
+
   // Determine if we're in dark mode for preview
   const [isDarkForPreview, setIsDarkForPreview] = useState(() => {
     if (typeof window === 'undefined') return false;