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

package/package.json

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

package/src/components/ContentView.tsx

@@ -16,22 +16,17 @@ const logger = getLogger('shellcore');
 
 interface ContentViewProps {
   url: string;
-  /** Base URL for this content (effective nav item URL). Used for URL sync; when omitted, falls back to navItem.url or url. */
-  baseUrl?: string;
   pathPrefix: string;
   ignoreMessages?: boolean;
-  /** Nav item for this content; may be undefined when opening by URL (e.g. settings modal) if no matching item found. */
-  navItem?: NavigationItem | null;
+  navItem: NavigationItem;
 }
 
 export const ContentView = ({
   url,
-  baseUrl: baseUrlProp,
   pathPrefix,
   ignoreMessages = false,
   navItem,
 }: ContentViewProps) => {
-  const baseUrl = baseUrlProp ?? navItem?.url ?? url;
   const navigate = useNavigate();
   const iframeRef = useRef<HTMLIFrameElement>(null);
   const isInternalNavigation = useRef(false);
@@ -63,13 +58,9 @@ export const ContentView = ({
         }
 
         const { pathname, search, hash } = data.payload as ShellUIUrlPayload;
-        // Use pathname part of baseUrl for comparison (iframe pathname is always path-only)
-        const basePathname =
-          baseUrl.startsWith('http') || baseUrl.startsWith('//')
-            ? new URL(baseUrl, window.location.origin).pathname
-            : baseUrl;
-        let cleanPathname = pathname.startsWith(basePathname)
-          ? pathname.slice(basePathname.length)
+        // 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
@@ -111,7 +102,7 @@ export const ContentView = ({
     return () => {
       cleanup();
     };
-  }, [pathPrefix, navigate, baseUrl]);
+  }, [pathPrefix, navigate]);
 
   // Hide loading overlay when iframe sends SHELLUI_INITIALIZED
   useEffect(() => {

package/src/components/ViewRoute.tsx

@@ -1,6 +1,6 @@
 import { useMemo } from 'react';
 import { Navigate, useLocation } from 'react-router';
-import { getNavPathPrefix, getEffectiveUrl } from '../features/layouts/utils';
+import { getNavPathPrefix } from '../features/layouts/utils';
 import { ContentView } from './ContentView';
 import type { NavigationItem } from '../features/config/types';
 
@@ -32,18 +32,15 @@ export const ViewRoute = ({ navigation }: ViewRouteProps) => {
   const pathPrefix = getNavPathPrefix(navItem);
   const subPath = pathname.length > pathPrefix.length ? pathname.slice(pathPrefix.length + 1) : '';
 
-  // Effective URL: url string or app-path URL when item uses a component
-  const baseUrl = getEffectiveUrl(navItem);
-  let finalUrl = baseUrl;
-  if (!navItem.component && subPath && navItem.url) {
-    const base = navItem.url.endsWith('/') ? navItem.url : `${navItem.url}/`;
-    finalUrl = `${base}${subPath}`;
+  // 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}`;
   }
-
   return (
     <ContentView
       url={finalUrl}
-      baseUrl={baseUrl}
       pathPrefix={navItem.path}
       navItem={navItem}
     />

package/src/components/ui/sonner.tsx

@@ -11,7 +11,7 @@ const Toaster = ({ ...props }: ToasterProps) => {
   return (
     <Sonner
       position="top-center"
-      theme={settings.appearance.theme as 'light' | 'dark' | 'system'}
+      theme={settings.appearance.colorScheme as 'light' | 'dark' | 'system'}
       className="toaster group"
       style={{
         zIndex: Z_INDEX.TOAST,

package/src/constants/urls.ts

@@ -1,6 +1,4 @@
 export default {
   settings: '/__settings',
   cookiePreferences: '/__cookie-preferences',
-  /** Base path for navigation items that use a React component; full URL is /__app/{path}. */
-  appPath: '/__app',
 };

package/src/features/config/ConfigProvider.ts

@@ -1,15 +1,12 @@
 import { createContext, useState, createElement, type ReactNode } from 'react';
-import type { ComponentType } from 'react';
 import { getLogger } from '@shellui/sdk';
 import type { ShellUIConfig } from './types';
-import shelluiConfig, { shelluiComponents } from '@shellui/config';
+import shelluiConfig from '@shellui/config';
 
 const logger = getLogger('shellcore');
 
 export interface ConfigContextValue {
   config: ShellUIConfig;
-  /** Map of nav path -> component for /__app/:path (injected when componentPath is set in config). */
-  shelluiComponents: Record<string, ComponentType>;
 }
 
 export const ConfigContext = createContext<ConfigContextValue | null>(null);
@@ -47,9 +44,7 @@ export function ConfigProvider(props: ConfigProviderProps): ReturnType<typeof cr
     }
   });
 
-  const value: ConfigContextValue = {
-    config,
-    shelluiComponents: typeof shelluiComponents !== 'undefined' ? shelluiComponents : {},
-  };
+  // Always provide a value - never null - to prevent "useConfig must be used within ConfigProvider" errors
+  const value: ConfigContextValue = { config };
   return createElement(ConfigContext.Provider, { value }, props.children);
 }

package/src/features/config/shellui-config.d.ts

@@ -1,13 +1,9 @@
 /**
  * Type declaration for the virtual @shellui/config module.
  * The CLI injects this module at build time via Vite (virtual:shellui-config).
- * When nav items have componentPath, the CLI also injects shelluiComponents for /__app/:path routes.
  */
 declare module '@shellui/config' {
-  import type { ComponentType } from 'react';
   import type { ShellUIConfig } from './types';
   export const shelluiConfig: ShellUIConfig;
-  /** Map of nav path -> component for component-based items (injected when componentPath is set). */
-  export const shelluiComponents: Record<string, ComponentType>;
   export default shelluiConfig;
 }

package/src/features/config/types.ts

@@ -1,5 +1,3 @@
-import type { ComponentType } from 'react';
-
 // Language-specific label/title
 export type LocalizedString =
   | string
@@ -18,12 +16,7 @@ export type LayoutType = 'sidebar' | 'fullscreen' | 'windows' | 'app-bar';
 export interface NavigationItem {
   label: string | LocalizedString;
   path: string;
-  /** URL to load in the content area (iframe). Omit when using component; then the app-path URL is used. */
-  url?: string;
-  /** React component to render for this item. When set, a URL under the app-path is generated so the content can be loaded in an iframe like URL-based items. The CLI infers the component module path from your config file imports so you don't need to set componentPath. */
-  component?: ComponentType;
-  /** @internal Set by the CLI when loading config (inferred from component + config file imports). Only needed if you bypass the CLI. */
-  componentPath?: string;
+  url: string;
   icon?: string; // Path to SVG icon file (e.g., '/icons/book-open.svg')
   /** When true, hide this item from the sidebar and 404 page; route remains valid and item still appears in Develop settings. */
   hidden?: boolean;

package/src/features/layouts/AppBarLayout.tsx

@@ -6,7 +6,7 @@ import type { NavigationItem, NavigationGroup } from '../config/types';
 import {
   filterNavigationByViewport,
   flattenNavigationItems,
-  getEffectiveUrl,
+  getActivePathPrefix,
   getNavPathPrefix,
   resolveLocalizedString as resolveNavLabel,
   splitNavigationByPosition,
@@ -49,17 +49,22 @@ function resolveLocalizedLabel(
 }
 
 /** End link: icon-only or first-letter badge with themed tooltip. */
-function TopBarEndItem({ item, label }: { item: NavigationItem; label: string }) {
+function TopBarEndItem({
+  item,
+  label,
+  activePathPrefix,
+}: {
+  item: NavigationItem;
+  label: string;
+  activePathPrefix: string | null;
+}) {
   const pathPrefix = getNavPathPrefix(item);
   const isOverlay = item.openIn === 'modal' || item.openIn === 'drawer';
   const isExternal = item.openIn === 'external';
-  const location = useLocation();
   const isActive =
-    !isOverlay &&
-    !isExternal &&
-    (location.pathname === pathPrefix || location.pathname.startsWith(`${pathPrefix}/`));
+    !isOverlay && !isExternal && pathPrefix === activePathPrefix;
 
-  const faviconUrl = isExternal && !item.icon ? getExternalFaviconUrl(getEffectiveUrl(item)) : null;
+  const faviconUrl = isExternal && !item.icon ? getExternalFaviconUrl(item.url) : null;
   const iconSrc = item.icon ?? faviconUrl ?? null;
   const firstLetter = label ? label.charAt(0).toUpperCase() : '?';
 
@@ -94,7 +99,7 @@ function TopBarEndItem({ item, label }: { item: NavigationItem; label: string })
     return wrap(
       <button
         type="button"
-        onClick={() => shellui.openModal(getEffectiveUrl(item))}
+        onClick={() => shellui.openModal(item.url)}
         className={buttonClass}
         aria-label={label}
       >
@@ -106,7 +111,7 @@ function TopBarEndItem({ item, label }: { item: NavigationItem; label: string })
     return wrap(
       <button
         type="button"
-        onClick={() => shellui.openDrawer({ url: getEffectiveUrl(item), position: item.drawerPosition })}
+        onClick={() => shellui.openDrawer({ url: item.url, position: item.drawerPosition })}
         className={buttonClass}
         aria-label={label}
       >
@@ -117,7 +122,7 @@ function TopBarEndItem({ item, label }: { item: NavigationItem; label: string })
   if (item.openIn === 'external') {
     return wrap(
       <a
-        href={getEffectiveUrl(item)}
+        href={item.url}
         target="_blank"
         rel="noopener noreferrer"
         className={buttonClass}
@@ -144,16 +149,18 @@ export function AppBarLayout({ title, logo, navigation }: AppBarLayoutProps) {
   const navigate = useNavigate();
   const currentLanguage = i18n.language || 'en';
 
-  const { endNavItems, navigationItems, displayStartItems } = useMemo(() => {
+  const { endNavItems, navigationItems, displayStartItems, activePathPrefix } = useMemo(() => {
     const desktopNav = filterNavigationByViewport(navigation, 'desktop');
     const { start, end } = splitNavigationByPosition(desktopNav);
     const startItems = flattenNavigationItems(start).filter((i) => !i.hidden);
+    const flat = flattenNavigationItems(navigation);
     return {
       endNavItems: flattenNavigationItems(end).filter((i) => !i.hidden),
-      navigationItems: flattenNavigationItems(navigation),
+      navigationItems: flat,
       displayStartItems: withHomepageWhenNoRoot(startItems),
+      activePathPrefix: getActivePathPrefix(location.pathname, flat),
     };
-  }, [navigation]);
+  }, [navigation, location.pathname]);
 
   useEffect(() => {
     if (!title) return;
@@ -243,6 +250,7 @@ export function AppBarLayout({ title, logo, navigation }: AppBarLayoutProps) {
                       key={item.path}
                       item={item}
                       label={resolveNavLabel(item.label, currentLanguage) || item.path || ''}
+                      activePathPrefix={activePathPrefix}
                     />
                   ))}
                 </div>

package/src/features/layouts/DefaultLayout.tsx

@@ -22,7 +22,7 @@ import {
   filterNavigationByViewport,
   filterNavigationForSidebar,
   flattenNavigationItems,
-  getEffectiveUrl,
+  getActivePathPrefix,
   getNavPathPrefix,
   HOMEPAGE_NAV_ITEM,
   resolveLocalizedString as resolveNavLabel,
@@ -83,6 +83,12 @@ const NavigationContent = ({
     });
   }, [navigation]);
 
+  const flatItems = useMemo(() => flattenNavigationItems(navigation), [navigation]);
+  const activePathPrefix = useMemo(
+    () => getActivePathPrefix(location.pathname, flatItems),
+    [location.pathname, flatItems],
+  );
+
   // Helper to check if an item is a group
   const isGroup = (item: NavigationItem | NavigationGroup): item is NavigationGroup => {
     return 'title' in item && 'items' in item;
@@ -94,11 +100,9 @@ const NavigationContent = ({
     const isOverlay = navItem.openIn === 'modal' || navItem.openIn === 'drawer';
     const isExternal = navItem.openIn === 'external';
     const isActive =
-      !isOverlay &&
-      !isExternal &&
-      (location.pathname === pathPrefix || location.pathname.startsWith(`${pathPrefix}/`));
+      !isOverlay && !isExternal && pathPrefix === activePathPrefix;
     const itemLabel = resolveLocalizedString(navItem.label, currentLanguage);
-    const faviconUrl = isExternal && !navItem.icon ? getExternalFaviconUrl(getEffectiveUrl(navItem)) : null;
+    const faviconUrl = isExternal && !navItem.icon ? getExternalFaviconUrl(navItem.url) : null;
     const iconSrc = navItem.icon ?? faviconUrl ?? null;
     const iconEl = iconSrc ? (
       <img
@@ -123,7 +127,7 @@ const NavigationContent = ({
       navItem.openIn === 'modal' ? (
         <button
           type="button"
-          onClick={() => shellui.openModal(getEffectiveUrl(navItem))}
+          onClick={() => shellui.openModal(navItem.url)}
           className="flex items-center gap-2 w-full cursor-pointer text-left"
         >
           {content}
@@ -131,14 +135,14 @@ const NavigationContent = ({
       ) : navItem.openIn === 'drawer' ? (
         <button
           type="button"
-          onClick={() => shellui.openDrawer({ url: getEffectiveUrl(navItem), position: navItem.drawerPosition })}
+          onClick={() => shellui.openDrawer({ url: navItem.url, position: navItem.drawerPosition })}
           className="flex items-center gap-2 w-full cursor-pointer text-left"
         >
           {content}
         </button>
       ) : navItem.openIn === 'external' ? (
         <a
-          href={getEffectiveUrl(navItem)}
+          href={navItem.url}
           target="_blank"
           rel="noopener noreferrer"
           className="flex items-center gap-2 w-full"
@@ -306,7 +310,7 @@ const BottomNavItem = ({
     return (
       <button
         type="button"
-        onClick={() => shellui.openModal(getEffectiveUrl(item))}
+        onClick={() => shellui.openModal(item.url)}
         className={baseClass}
       >
         {content}
@@ -317,7 +321,7 @@ const BottomNavItem = ({
     return (
       <button
         type="button"
-        onClick={() => shellui.openDrawer({ url: getEffectiveUrl(item), position: item.drawerPosition })}
+        onClick={() => shellui.openDrawer({ url: item.url, position: item.drawerPosition })}
         className={baseClass}
       >
         {content}
@@ -327,7 +331,7 @@ const BottomNavItem = ({
   if (item.openIn === 'external') {
     return (
       <a
-        href={getEffectiveUrl(item)}
+        href={item.url}
         target="_blank"
         rel="noopener noreferrer"
         className={baseClass}
@@ -443,6 +447,11 @@ const MobileBottomNav = ({
   const navRef = useRef<HTMLElement>(null);
   const [rowWidth, setRowWidth] = useState(0);
 
+  const activePathPrefix = useMemo(
+    () => getActivePathPrefix(location.pathname, items),
+    [location.pathname, items],
+  );
+
   useLayoutEffect(() => {
     const el = navRef.current;
     if (!el) return;
@@ -483,17 +492,15 @@ const MobileBottomNav = ({
     const pathPrefix = getNavPathPrefix(item);
     const isOverlayOrExternal =
       item.openIn === 'modal' || item.openIn === 'drawer' || item.openIn === 'external';
-    const isActive =
-      !isOverlayOrExternal &&
-      (location.pathname === pathPrefix || location.pathname.startsWith(`${pathPrefix}/`));
+    const isActive = !isOverlayOrExternal && pathPrefix === activePathPrefix;
     const label = resolveNavLabel(item.label, currentLanguage);
     const faviconUrl =
-      item.openIn === 'external' && !item.icon ? getExternalFaviconUrl(getEffectiveUrl(item)) : null;
+      item.openIn === 'external' && !item.icon ? getExternalFaviconUrl(item.url) : null;
     const iconSrc = item.icon ?? faviconUrl ?? null;
     const applyIconTheme = iconSrc ? isAppIcon(iconSrc) : false;
     return (
       <BottomNavItem
-        key={`${item.path}-${getEffectiveUrl(item)}-${index}`}
+        key={`${item.path}-${item.url}-${index}`}
         item={item}
         label={label}
         isActive={isActive}

package/src/features/layouts/OverlayShell.tsx

@@ -9,7 +9,7 @@ import { Toaster } from '../../components/ui/sonner';
 import { ContentView } from '../../components/ContentView';
 import { useModal } from '../modal/ModalContext';
 import { useDrawer } from '../drawer/DrawerContext';
-import { getEffectiveUrl, getNavPathPrefix, normalizeUrlToPathname, resolveLocalizedString } from './utils';
+import { getNavPathPrefix, resolveLocalizedString } from './utils';
 
 interface OverlayShellProps {
   navigationItems: NavigationItem[];
@@ -90,9 +90,7 @@ export function OverlayShell({ navigationItems, children }: OverlayShellProps) {
             <>
               <DialogTitle className="sr-only">
                 {resolveLocalizedString(
-                  navigationItems.find(
-                    (item) => normalizeUrlToPathname(getEffectiveUrl(item)) === normalizeUrlToPathname(modalUrl),
-                  )?.label,
+                  navigationItems.find((item) => item.url === modalUrl)?.label,
                   currentLanguage,
                 )}
               </DialogTitle>
@@ -107,11 +105,7 @@ export function OverlayShell({ navigationItems, children }: OverlayShellProps) {
                   url={modalUrl}
                   pathPrefix="settings"
                   ignoreMessages={true}
-                  navItem={
-                    navigationItems.find(
-                      (item) => normalizeUrlToPathname(getEffectiveUrl(item)) === normalizeUrlToPathname(modalUrl),
-                    ) ?? undefined
-                  }
+                  navItem={navigationItems.find((item) => item.url === modalUrl) as NavigationItem}
                 />
               </div>
             </>
@@ -153,11 +147,7 @@ export function OverlayShell({ navigationItems, children }: OverlayShellProps) {
                 url={drawerUrl}
                 pathPrefix="settings"
                 ignoreMessages={true}
-                navItem={
-                  navigationItems.find(
-                    (item) => normalizeUrlToPathname(getEffectiveUrl(item)) === normalizeUrlToPathname(drawerUrl),
-                  ) ?? undefined
-                }
+                navItem={navigationItems.find((item) => item.url === drawerUrl) as NavigationItem}
               />
             </div>
           ) : (

package/src/features/layouts/WindowsLayout.tsx

@@ -11,7 +11,6 @@ import { shellui } from '@shellui/sdk';
 import type { NavigationItem, NavigationGroup } from '../config/types';
 import {
   flattenNavigationItems,
-  getEffectiveUrl,
   getNavPathPrefix,
   resolveLocalizedString as resolveNavLabel,
   splitNavigationByPosition,
@@ -542,7 +541,7 @@ export function WindowsLayout({
       const label =
         typeof item.label === 'string' ? item.label : resolveNavLabel(item.label, currentLanguage);
       const faviconUrl =
-        item.openIn === 'external' && !item.icon ? getExternalFaviconUrl(getEffectiveUrl(item)) : null;
+        item.openIn === 'external' && !item.icon ? getExternalFaviconUrl(item.url) : null;
       const icon = item.icon ?? faviconUrl ?? null;
       const id = genId();
       const bounds = {
@@ -557,7 +556,7 @@ export function WindowsLayout({
           id,
           path: item.path,
           pathname: getNavPathPrefix(item),
-          baseUrl: getEffectiveUrl(item),
+          baseUrl: item.url,
           label,
           icon,
           bounds,
@@ -610,17 +609,17 @@ export function WindowsLayout({
   const handleNavClick = useCallback(
     (item: NavigationItem) => {
       if (item.openIn === 'modal') {
-        shellui.openModal(getEffectiveUrl(item));
+        shellui.openModal(item.url);
         setStartMenuOpen(false);
         return;
       }
       if (item.openIn === 'drawer') {
-        shellui.openDrawer({ url: getEffectiveUrl(item), position: item.drawerPosition });
+        shellui.openDrawer({ url: item.url, position: item.drawerPosition });
         setStartMenuOpen(false);
         return;
       }
       if (item.openIn === 'external') {
-        window.open(getEffectiveUrl(item), '_blank', 'noopener,noreferrer');
+        window.open(item.url, '_blank', 'noopener,noreferrer');
         setStartMenuOpen(false);
         return;
       }
@@ -710,7 +709,7 @@ export function WindowsLayout({
                           : resolveNavLabel(item.label, currentLanguage);
                       const icon =
                         item.icon ??
-                        (item.openIn === 'external' ? getExternalFaviconUrl(getEffectiveUrl(item)) : null);
+                        (item.openIn === 'external' ? getExternalFaviconUrl(item.url) : null);
                       return (
                         <button
                           key={item.path}
@@ -792,7 +791,7 @@ export function WindowsLayout({
                     : resolveNavLabel(item.label, currentLanguage);
                 const icon =
                   item.icon ??
-                  (item.openIn === 'external' ? getExternalFaviconUrl(getEffectiveUrl(item)) : null);
+                  (item.openIn === 'external' ? getExternalFaviconUrl(item.url) : null);
                 return (
                   <button
                     key={item.path}

package/src/features/layouts/utils.ts

@@ -1,33 +1,25 @@
 import type { NavigationItem, NavigationGroup, LocalizedString } from '../config/types';
-import urls from '../../constants/urls';
 
 /** Path prefix for a nav item: "/" for root (path '' or '/'), otherwise "/{path}". */
 export function getNavPathPrefix(item: NavigationItem): string {
   return item.path === '/' || item.path === '' ? '/' : `/${item.path}`;
 }
 
-/** Effective URL for a nav item: url if set, otherwise app-path URL for component-based items. */
-export function getEffectiveUrl(item: NavigationItem): string {
-  if (item.url != null && item.url !== '') {
-    return item.url;
-  }
-  const base = typeof window !== 'undefined' ? window.location.origin : '';
-  const path = item.path === '/' || item.path === '' ? 'home' : item.path;
-  return `${base}${urls.appPath}/${path}`;
-}
-
-/** Normalize a URL to pathname for comparison (handles full URLs and path-only). */
-export function normalizeUrlToPathname(url: string): string {
-  if (!url || typeof url !== 'string') return '';
-  const s = url.trim();
-  if (s.startsWith('http://') || s.startsWith('https://') || s.startsWith('//')) {
-    try {
-      return new URL(s, 'http://localhost').pathname.replace(/\/+$/, '') || '/';
-    } catch {
-      return s.startsWith('/') ? s.replace(/\/+$/, '') || '/' : `/${s}`.replace(/\/+$/, '') || '/';
-    }
-  }
-  return (s.startsWith('/') ? s : `/${s}`).replace(/\/+$/, '') || '/';
+/** 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(
+    (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 + '/'),
+    );
+  if (matching.length === 0) return null;
+  return matching.reduce((a, b) => (a.length >= b.length ? a : b));
 }
 
 /** Resolve a localized string to a single string for the given language. */

package/src/features/settings/SettingsProvider.tsx

@@ -5,12 +5,13 @@ import {
   type ShellUIMessage,
   type Settings,
   type SettingsNavigationItem,
+  type Appearance,
 } from '@shellui/sdk';
 import { SettingsContext } from './SettingsContext';
 import { useConfig } from '../config/useConfig';
 import { useTranslation } from 'react-i18next';
-import type { NavigationItem, NavigationGroup } from '../config/types';
-import { getEffectiveUrl } from '../layouts/utils';
+import type { NavigationItem, NavigationGroup, ShellUIConfig } from '../config/types';
+import { getTheme, registerTheme } from '../theme/themes';
 
 const logger = getLogger('shellcore');
 
@@ -32,18 +33,77 @@ function resolveLabel(
   return value[lang] || value.en || value.fr || Object.values(value)[0] || '';
 }
 
-function buildSettingsWithNavigation(
+function resolveColorMode(colorScheme: 'light' | 'dark' | 'system'): 'light' | 'dark' {
+  if (colorScheme === 'system' && typeof window !== 'undefined') {
+    return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+  }
+  return colorScheme === 'dark' ? 'dark' : 'light';
+}
+
+/**
+ * Build the full appearance object for settings propagation so apps receive all theme
+ * variable values and can style without knowing the theme name.
+ */
+function getResolvedAppearanceForSettings(
+  settings: Settings,
+  config: ShellUIConfig | undefined,
+): Appearance | undefined {
+  if (typeof window === 'undefined') return undefined;
+  config?.themes?.forEach(registerTheme);
+  const themeName =
+    settings.appearance?.name || config?.defaultTheme || 'default';
+  const themeDef = getTheme(themeName) || getTheme('default');
+  if (!themeDef) return undefined;
+  const colorScheme = settings.appearance?.colorScheme ?? 'system';
+  const mode = resolveColorMode(colorScheme);
+  return {
+    name: themeDef.name,
+    displayName: themeDef.displayName,
+    mode,
+    colorScheme,
+    colors: themeDef.colors,
+    ...(themeDef.fontFamily !== undefined && { fontFamily: themeDef.fontFamily }),
+    ...(themeDef.bodyFontFamily !== undefined && {
+      bodyFontFamily: themeDef.bodyFontFamily,
+    }),
+    ...(themeDef.headingFontFamily !== undefined && {
+      headingFontFamily: themeDef.headingFontFamily,
+    }),
+    ...(themeDef.letterSpacing !== undefined && {
+      letterSpacing: themeDef.letterSpacing,
+    }),
+    ...(themeDef.textShadow !== undefined && { textShadow: themeDef.textShadow }),
+    ...(themeDef.lineHeight !== undefined && { lineHeight: themeDef.lineHeight }),
+    ...(themeDef.fontFiles !== undefined &&
+      themeDef.fontFiles.length > 0 && { fontFiles: themeDef.fontFiles }),
+  };
+}
+
+/**
+ * Build settings for propagation to iframes: inject navigation and full theme object
+ * so apps receive all theme variable values.
+ */
+function buildSettingsForPropagation(
   settings: Settings,
-  navigation: (NavigationItem | NavigationGroup)[] | undefined,
+  config: ShellUIConfig | undefined,
   lang: string,
 ): Settings {
-  if (!navigation?.length) return settings;
-  const items: SettingsNavigationItem[] = flattenNavigationItems(navigation).map((item) => ({
-    path: item.path,
-    url: getEffectiveUrl(item),
-    label: resolveLabel(item.label, lang),
-  }));
-  return { ...settings, navigation: { items } };
+  const appearance = getResolvedAppearanceForSettings(settings, config);
+  let result: Settings = {
+    ...settings,
+    appearance: appearance ?? settings.appearance,
+  };
+  if (config?.navigation?.length) {
+    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;
 }
 
 const STORAGE_KEY = 'shellui:settings';
@@ -56,6 +116,75 @@ const getBrowserTimezone = (): string => {
   return 'UTC';
 };
 
+const defaultAppearance: Appearance = {
+  name: 'default',
+  displayName: 'Default',
+  mode: 'light',
+  colorScheme: 'system',
+  colors: {
+    light: {
+      background: '#ffffff',
+      foreground: '#09090b',
+      card: '#ffffff',
+      cardForeground: '#09090b',
+      popover: '#ffffff',
+      popoverForeground: '#09090b',
+      primary: '#18181b',
+      primaryForeground: '#fafafa',
+      secondary: '#f4f4f5',
+      secondaryForeground: '#18181b',
+      muted: '#f4f4f5',
+      mutedForeground: '#71717a',
+      accent: '#f4f4f5',
+      accentForeground: '#18181b',
+      destructive: '#ef4444',
+      destructiveForeground: '#fafafa',
+      border: '#e4e4e7',
+      input: '#e4e4e7',
+      ring: '#18181b',
+      radius: '0.5rem',
+      sidebarBackground: '#fafafa',
+      sidebarForeground: '#09090b',
+      sidebarPrimary: '#18181b',
+      sidebarPrimaryForeground: '#fafafa',
+      sidebarAccent: '#e4e4e7',
+      sidebarAccentForeground: '#18181b',
+      sidebarBorder: '#e4e4e7',
+      sidebarRing: '#18181b',
+    },
+    dark: {
+      background: '#09090b',
+      foreground: '#fafafa',
+      card: '#09090b',
+      cardForeground: '#fafafa',
+      popover: '#09090b',
+      popoverForeground: '#fafafa',
+      primary: '#fafafa',
+      primaryForeground: '#18181b',
+      secondary: '#27272a',
+      secondaryForeground: '#fafafa',
+      muted: '#27272a',
+      mutedForeground: '#a1a1aa',
+      accent: '#27272a',
+      accentForeground: '#fafafa',
+      destructive: '#7f1d1d',
+      destructiveForeground: '#fafafa',
+      border: '#27272a',
+      input: '#27272a',
+      ring: '#d4d4d8',
+      radius: '0.5rem',
+      sidebarBackground: '#09090b',
+      sidebarForeground: '#fafafa',
+      sidebarPrimary: '#fafafa',
+      sidebarPrimaryForeground: '#18181b',
+      sidebarAccent: '#27272a',
+      sidebarAccentForeground: '#fafafa',
+      sidebarBorder: '#27272a',
+      sidebarRing: '#d4d4d8',
+    },
+  },
+};
+
 const defaultSettings: Settings = {
   developerFeatures: {
     enabled: false,
@@ -69,10 +198,7 @@ const defaultSettings: Settings = {
       shellcore: false,
     },
   },
-  appearance: {
-    theme: 'system',
-    themeName: 'default',
-  },
+  appearance: defaultAppearance,
   language: {
     code: 'en',
   },
@@ -122,8 +248,13 @@ export function SettingsProvider({ children }: { children: ReactNode }) {
               },
             },
             appearance: {
-              theme: parsed.appearance?.theme || defaultSettings.appearance.theme,
-              themeName: parsed.appearance?.themeName || defaultSettings.appearance.themeName,
+              ...defaultAppearance,
+              ...parsed.appearance,
+              // Migrate from legacy theme/themeName
+              name: parsed.appearance?.name ?? parsed.appearance?.themeName ?? defaultAppearance.name,
+              colorScheme:
+                parsed.appearance?.colorScheme ?? parsed.appearance?.theme ?? defaultAppearance.colorScheme,
+              colors: parsed.appearance?.colors ?? defaultAppearance.colors,
             },
             language: {
               code: parsed.language?.code || defaultSettings.language.code,
@@ -179,9 +310,9 @@ export function SettingsProvider({ children }: { children: ReactNode }) {
             try {
               localStorage.setItem(STORAGE_KEY, JSON.stringify(newSettings));
               // Confirm: root updated localStorage; re-inject navigation when propagating
-              const settingsToPropagate = buildSettingsWithNavigation(
+              const settingsToPropagate = buildSettingsForPropagation(
                 newSettings,
-                config?.navigation,
+                config,
                 i18n.language || 'en',
               );
               logger.info('Root Parent received settings update', { message });
@@ -202,9 +333,9 @@ export function SettingsProvider({ children }: { children: ReactNode }) {
       () => {
         // Use ref to always get current settings (avoids stale closure)
         const currentSettings = settingsRef.current ?? defaultSettings;
-        const settingsWithNav = buildSettingsWithNavigation(
+        const settingsWithNav = buildSettingsForPropagation(
           currentSettings,
-          config?.navigation,
+          config,
           i18n.language || 'en',
         );
         shellui.propagateMessage({
@@ -244,9 +375,9 @@ export function SettingsProvider({ children }: { children: ReactNode }) {
           localStorage.setItem(STORAGE_KEY, JSON.stringify(newSettings));
           setSettings(newSettings);
           // Propagate to child iframes (sendMessageToParent does nothing in root)
-          const settingsWithNav = buildSettingsWithNavigation(
+          const settingsWithNav = buildSettingsForPropagation(
             newSettings,
-            config?.navigation,
+            config,
             i18n.language || 'en',
           );
           shellui.propagateMessage({
@@ -304,9 +435,9 @@ export function SettingsProvider({ children }: { children: ReactNode }) {
         // If we're in the root window, update localStorage with defaults
         if (window.parent === window) {
           localStorage.setItem(STORAGE_KEY, JSON.stringify(newSettings));
-          const settingsToPropagate = buildSettingsWithNavigation(
+          const settingsToPropagate = buildSettingsForPropagation(
             newSettings,
-            config?.navigation,
+            config,
             i18n.language || 'en',
           );
           shellui.propagateMessage({

package/src/features/settings/components/Appearance.tsx

@@ -166,8 +166,8 @@ export const Appearance = () => {
   const { t } = useTranslation('settings');
   const { settings, updateSetting } = useSettings();
   const { config } = useConfig();
-  const currentTheme = settings.appearance?.theme || 'system';
-  const currentThemeName = settings.appearance?.themeName || 'default';
+  const currentTheme = settings.appearance?.colorScheme ?? 'system';
+  const currentThemeName = settings.appearance?.name ?? 'default';
 
   const [availableThemes, setAvailableThemes] = useState<ThemeDefinition[]>([]);
 
@@ -246,7 +246,7 @@ export const Appearance = () => {
                   key={theme.value}
                   variant={isSelected ? 'default' : 'outline'}
                   onClick={() => {
-                    updateSetting('appearance', { theme: theme.value });
+                    updateSetting('appearance', { colorScheme: theme.value });
                   }}
                   className={cn(
                     'h-10 px-4 transition-all flex items-center gap-2 cursor-pointer',
@@ -283,7 +283,7 @@ export const Appearance = () => {
               <button
                 key={theme.name}
                 onClick={() => {
-                  updateSetting('appearance', { themeName: theme.name });
+                  updateSetting('appearance', { name: theme.name });
                 }}
                 className={cn(
                   'text-left transition-all cursor-pointer',

package/src/features/theme/useTheme.tsx

@@ -27,8 +27,8 @@ function applyThemeToDocument(isDark: boolean) {
 export function useTheme() {
   const { settings } = useSettings();
   const { config } = useConfig();
-  const theme = settings.appearance?.theme || 'system';
-  const themeName = settings.appearance?.themeName || 'default';
+  const colorScheme = settings.appearance?.colorScheme ?? 'system';
+  const themeName = settings.appearance?.name ?? 'default';
 
   // Apply theme immediately on mount (synchronously) to prevent empty colors
   // This ensures CSS variables are set before first render
@@ -47,11 +47,11 @@ export function useTheme() {
 
     if (themeDefinition) {
       const determineIsDark = () => {
-        if (theme === 'system') {
+        if (colorScheme === 'system') {
           const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
           return mediaQuery.matches;
         }
-        return theme === 'dark';
+        return colorScheme === 'dark';
       };
       const isDark = determineIsDark();
       applyThemeToDocument(isDark);
@@ -62,10 +62,10 @@ export function useTheme() {
       const defaultTheme = getTheme('default');
       if (defaultTheme) {
         const isDark =
-          theme === 'dark' ||
-          (theme === 'system' && window.matchMedia('(prefers-color-scheme: dark)').matches);
+          colorScheme === 'dark' ||
+          (colorScheme === 'system' && window.matchMedia('(prefers-color-scheme: dark)').matches);
         applyTheme(defaultTheme, isDark);
       }
     }
-  }, [theme, themeName, config]); // Run when theme, themeName, or config changes
+  }, [colorScheme, themeName, config]); // Run when colorScheme, themeName, or config changes
 }

package/src/router/routes.tsx

@@ -24,9 +24,6 @@ const IndexRoute = lazy(() =>
 const NotFoundView = lazy(() =>
   import('../components/NotFoundView').then((m) => ({ default: m.NotFoundView })),
 );
-const AppPathView = lazy(() =>
-  import('../components/AppPathView').then((m) => ({ default: m.AppPathView })),
-);
 
 function RouteFallback() {
   return (
@@ -62,15 +59,6 @@ export const createRoutes = (config: ShellUIConfig): RouteObject[] => {
             </Suspense>
           ),
         },
-        {
-          // App-path route: renders component-based nav items so they can be loaded in an iframe
-          path: `${urls.appPath.replace(/^\//, '')}/:path/*`,
-          element: (
-            <Suspense fallback={<RouteFallback />}>
-              <AppPathView />
-            </Suspense>
-          ),
-        },
         {
           // Catch-all route
           path: '*',

package/src/components/AppPathView.tsx

@@ -1,31 +0,0 @@
-import { useParams } from 'react-router';
-import { useConfig } from '../features/config/useConfig';
-import { flattenNavigationItems } from '../features/layouts/utils';
-import { NotFoundView } from './NotFoundView';
-
-/**
- * Renders the React component for a navigation item when the app is loaded at /__app/:path.
- * Uses navItem.component (when config is not serialized) or shelluiComponents from context (injected by CLI when componentPath is set).
- */
-export const AppPathView = () => {
-  const { config, shelluiComponents } = useConfig();
-  const { path: pathParam } = useParams<{ path: string }>();
-  const navigation = config?.navigation;
-  const items = navigation?.length ? flattenNavigationItems(navigation) : [];
-  const navItem = pathParam
-    ? items.find(
-        (item) =>
-          item.path === pathParam ||
-          (pathParam === 'home' && (item.path === '' || item.path === '/')),
-      )
-    : null;
-
-  const pathKey = pathParam === 'home' || !pathParam ? 'home' : pathParam;
-  const Component = navItem?.component ?? shelluiComponents?.[pathKey];
-
-  if (!Component) {
-    return <NotFoundView />;
-  }
-
-  return <Component />;
-};