@medalsocial/meda 1.4.0 → 1.6.0

package/README.md

@@ -17,6 +17,28 @@ Peer deps: `react >= 19`, `react-dom >= 19`, and `lucide-react`.
 Meda ships a `styles.css` with its design tokens. Import it once in your entry stylesheet or entry script:
 
 ```css
+@import 'tailwindcss';
+@import '@medalsocial/meda/styles.css';
+
+:root {
+  /* Consumer overrides go after meda so equal-specificity tokens win by source order. */
+  --color-brand-500: oklch(0.62 0.18 245);
+  --auth-gradient-primary: var(--color-brand-500);
+}
+
+.dark {
+  --color-brand-500: oklch(0.72 0.16 245);
+}
+```
+
+Avoid placing token overrides before the Meda import; `tokens.css` defines the package defaults and later declarations are what override them:
+
+```css
+/* Wrong: meda's imported defaults overwrite this block. */
+:root {
+  --color-brand-500: oklch(0.62 0.18 245);
+}
+
 @import '@medalsocial/meda/styles.css';
 ```
 
@@ -58,11 +80,35 @@ import Link from 'next/link';
     mainItems,
     renderLink: ({ item, linkProps }) => <Link {...linkProps} href={item.to} prefetch />,
   }}
+  appTabs={{
+    renderLink: ({ app, linkProps }) =>
+      app.to ? <Link {...linkProps} href={app.to} prefetch /> : <a {...linkProps} />,
+  }}
 >
   {children}
 </AppShell>;
 ```
 
+Workspace shells also expose chrome-level composition slots:
+
+```tsx
+<AppShell
+  variant="workspace"
+  headerCenter={<SectionTabs />}
+  banners={<SystemHealthBanner />}
+  mainLayout="fullbleed"
+  mainClassName="marketing-main"
+  workspace={{
+    menuItems: [{ id: 'settings', label: 'Settings', href: '/settings' }],
+    menuFooter: <AccountSwitcher />,
+  }}
+>
+  {children}
+</AppShell>
+```
+
+`workspace.menuItems`, `workspace.menuFooter`, and the theme toggle are available from the mobile Menu drawer. Use `mainLayout`/`mainClassName` when a workspace shell needs the same mobile chrome but a custom main scroll region, such as a full-bleed marketing page. `useCommands()` works from workspace descendants without manually mounting `CommandPalette`; lower-level primitive compositions can still mount `CommandPalette` directly.
+
 For app-scoped brand tokens:
 
 ```ts

package/dist/recipes/next.js

@@ -1,7 +1,7 @@
 export const nextAppShellRecipe = {
     name: 'meda-next-app-shell',
     title: 'Meda Next AppShell',
-    description: 'Copyable Next.js App Router shell adapter with next/link routing, route-owned panel views, and auth controls.',
+    description: 'Copyable Next.js App Router shell adapter with next/link routing, route-owned panel views, mobile workspace menus, full-bleed main layout hooks, and auth controls.',
     dependencies: ['@medalsocial/meda', 'lucide-react'],
     peerDependencies: ['next', 'react', 'react-dom'],
     cssVars: ['@medalsocial/meda/styles.css'],
@@ -25,9 +25,12 @@ import {
   MedaShellProvider,
   PanelViewsProvider,
   type AppDefinition,
+  type AppShellAppTabsConfig,
   type IconRailItem,
   type PanelView,
+  type ShellMainLayout,
   type WorkspaceDefinition,
+  type WorkspaceMenuItem,
 } from '@medalsocial/meda/shell'
 
 export function MedaNextWorkspaceShell({
@@ -37,6 +40,13 @@ export function MedaNextWorkspaceShell({
   activeIconId,
   panelViews = [],
   defaultPanelView,
+  appTabs,
+  headerCenter,
+  banners,
+  mainLayout,
+  mainClassName,
+  workspaceMenuItems,
+  workspaceMenuFooter,
   children,
 }: {
   workspace: WorkspaceDefinition
@@ -45,6 +55,13 @@ export function MedaNextWorkspaceShell({
   activeIconId?: string
   panelViews?: PanelView[]
   defaultPanelView?: string
+  appTabs?: AppShellAppTabsConfig
+  headerCenter?: ReactNode
+  banners?: ReactNode
+  mainLayout?: ShellMainLayout
+  mainClassName?: string
+  workspaceMenuItems?: WorkspaceMenuItem[]
+  workspaceMenuFooter?: ReactNode
   children: ReactNode
 }) {
   return (
@@ -58,6 +75,17 @@ export function MedaNextWorkspaceShell({
             <Link {...linkProps} href={item.to} prefetch />
           ),
         }}
+        appTabs={
+          appTabs ?? {
+            renderLink: ({ app, linkProps }) =>
+              app.to ? <Link {...linkProps} href={app.to} prefetch /> : <a {...linkProps} />,
+          }
+        }
+        headerCenter={headerCenter}
+        banners={banners}
+        mainLayout={mainLayout}
+        mainClassName={mainClassName}
+        workspace={{ menuItems: workspaceMenuItems, menuFooter: workspaceMenuFooter }}
         rightPanel={{ panelViews, defaultView: defaultPanelView }}
       >
         <PanelViewsProvider views={panelViews} defaultView={defaultPanelView}>
@@ -114,6 +142,7 @@ export function MedaNextAuthShell({
     accessibility: [
         'Every drawer and panel keeps its accessible name from AppShell and RightPanel.',
         'Custom link renderers must forward all linkProps to preserve aria-current, labels, handlers, and className.',
+        'Workspace menu items render in desktop and mobile chrome, so critical actions stay reachable across viewports.',
         'Auth provider buttons keep the visible provider affordance separate from the accessible button name.',
         'Route-owned panel views should expose headings inside their rendered panel content.',
         'Reduced-motion behavior remains delegated to Meda shell motion tokens.',
@@ -121,6 +150,9 @@ export function MedaNextAuthShell({
     composition: [
         'MedaShellProvider owns workspace and app context for the copied shell adapter.',
         'AppShell receives route-owned rightPanel views on first render to avoid delayed panel UI.',
+        'AppShellWorkspace mounts CommandPalette internally; route children can call useCommands without an extra shell-level mount.',
+        'headerCenter and banners keep route-level chrome in the shell band instead of inside the main pane.',
+        'mainLayout and mainClassName let full-bleed routes reuse AppShell mobile chrome without dropping down to primitives.',
         'PanelViewsProvider wraps children with the same panelViews and defaultPanelView for nested route registrations.',
         'renderLink composes Next Link by forwarding Meda linkProps before setting framework-specific props.',
     ],

package/dist/shell/app-shell-auth.js

@@ -7,7 +7,7 @@ function DefaultBrandMark() {
 }
 export function AppShellAuth({ children, title, description, brandName = 'Meda', brandMark, eyebrow, preview, actions, }) {
     const resolvedBrandMark = brandMark ?? _jsx(DefaultBrandMark, {});
-    return (_jsxs("section", { "data-testid": "app-shell-auth", className: "grid min-h-screen overflow-hidden bg-background text-foreground lg:grid-cols-[minmax(0,1.08fr)_minmax(420px,0.92fr)]", children: [_jsxs("div", { className: "relative flex min-h-[24rem] flex-col overflow-hidden bg-[radial-gradient(circle_at_24%_18%,var(--color-info-500)_0,transparent_25%),radial-gradient(circle_at_84%_24%,var(--color-brand-400)_0,transparent_28%),linear-gradient(135deg,var(--color-brand-800),var(--color-brand-700)_42%,var(--color-brand-500))] px-6 py-6 text-white sm:min-h-[30rem] sm:px-8 lg:min-h-screen lg:px-10 lg:py-8", children: [_jsx("div", { className: "pointer-events-none absolute inset-0 opacity-[0.07]", style: {
+    return (_jsxs("section", { "data-testid": "app-shell-auth", className: "grid min-h-screen overflow-hidden bg-background text-foreground lg:grid-cols-[minmax(0,1.08fr)_minmax(420px,0.92fr)]", children: [_jsxs("div", { "data-meda-auth-marketing-panel": "", className: "relative flex min-h-[24rem] flex-col overflow-hidden bg-[radial-gradient(circle_at_24%_18%,var(--auth-gradient-primary)_0,transparent_25%),radial-gradient(circle_at_84%_24%,var(--auth-gradient-secondary)_0,transparent_28%),linear-gradient(135deg,var(--auth-gradient-base),var(--auth-gradient-secondary)_42%,var(--auth-gradient-primary))] px-6 py-6 text-white sm:min-h-[30rem] sm:px-8 lg:min-h-screen lg:px-10 lg:py-8", children: [_jsx("div", { className: "pointer-events-none absolute inset-0 opacity-[0.07]", style: {
                             backgroundImage: "url(\"data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='.9' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)'/%3E%3C/svg%3E\")",
                         } }), _jsxs("div", { className: "relative z-10 flex items-center gap-3", children: [resolvedBrandMark, _jsx("span", { className: "text-lg font-semibold tracking-normal", children: brandName })] }), _jsxs("div", { className: "relative z-10 flex flex-1 flex-col justify-center gap-8 py-10 lg:py-12", children: [_jsxs("div", { className: "max-w-2xl", children: [eyebrow && (_jsx("p", { className: "mb-4 text-sm font-semibold uppercase tracking-[0.12em] text-white/70", children: eyebrow })), _jsx("h1", { className: "text-4xl font-bold leading-tight tracking-normal text-white sm:text-5xl", children: title }), description && (_jsx("p", { className: "mt-4 max-w-xl text-base leading-7 text-white/72 sm:text-lg", children: description }))] }), _jsx("div", { className: "w-full max-w-3xl", children: preview ?? _jsx(DefaultAuthPreview, {}) })] })] }), _jsxs("div", { className: "relative flex min-h-screen flex-col bg-background px-6 py-6 sm:px-8 lg:px-12", children: [actions && _jsx("div", { className: "flex justify-end", children: actions }), _jsxs("div", { className: "mx-auto flex w-full max-w-md flex-1 flex-col justify-center py-10", children: [_jsx("div", { className: "mb-8 flex justify-center lg:hidden", children: resolvedBrandMark }), children] })] })] }));
 }

package/dist/shell/app-shell-workspace.d.ts

@@ -1,10 +1,16 @@
-import type { ReactNode } from 'react';
-import type { AppShellContextRailConfig, AppShellIconRailConfig, AppShellRightPanelConfig } from './types.js';
+import { type ReactNode } from 'react';
+import type { AppShellAppTabsConfig, AppShellContextRailConfig, AppShellIconRailConfig, AppShellRightPanelConfig, AppShellWorkspaceConfig, ShellMainLayout } from './types.js';
 export interface AppShellWorkspaceProps {
     iconRail?: AppShellIconRailConfig;
     contextRail?: AppShellContextRailConfig;
     rightPanel?: AppShellRightPanelConfig;
+    workspace?: AppShellWorkspaceConfig;
+    appTabs?: AppShellAppTabsConfig;
     globalActions?: ReactNode;
+    headerCenter?: ReactNode;
+    banners?: ReactNode;
+    mainLayout?: ShellMainLayout;
+    mainClassName?: string;
     children: ReactNode;
 }
-export declare function AppShellWorkspace({ iconRail, contextRail, rightPanel, globalActions, children, }: AppShellWorkspaceProps): import("react/jsx-runtime").JSX.Element;
+export declare function AppShellWorkspace({ iconRail, contextRail, rightPanel, workspace, appTabs, globalActions, headerCenter, banners, mainLayout, mainClassName, children, }: AppShellWorkspaceProps): import("react/jsx-runtime").JSX.Element;

package/dist/shell/app-shell-workspace.js

@@ -1,6 +1,8 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { LayoutGrid, Menu, PanelTop, Sparkles } from 'lucide-react';
+import { useContext } from 'react';
+import { CommandPalette, CommandRegistryContext } from './command-palette.js';
 import { ContextRail } from './context-rail.js';
 import { IconRail } from './icon-rail.js';
 import { MobileBottomNav } from './internal/mobile-bottom-nav.js';
@@ -12,16 +14,15 @@ import { ShellHeader } from './shell-header.js';
 import { ShellMain } from './shell-main.js';
 import { useShellViewport } from './use-shell-viewport.js';
 const EMPTY_PANEL_VIEWS = [];
-export function AppShellWorkspace({ iconRail, contextRail, rightPanel, globalActions, children, }) {
+export function AppShellWorkspace({ iconRail, contextRail, rightPanel, workspace, appTabs, globalActions, headerCenter, banners, mainLayout, mainClassName, children, }) {
     const viewport = useShellViewport();
     const isMobile = viewport === 'mobile';
     const staticPanelViews = rightPanel?.panelViews ?? EMPTY_PANEL_VIEWS;
     const resolvedRightPanel = useResolvedPanelViews(staticPanelViews, rightPanel?.defaultView);
     // Derive the bottom-nav items from the variant config so each button maps
-    // to a drawer that actually has content. Without this filter, partial
-    // configs (e.g. iconRail only) would show Module/Panels/AI buttons that
-    // dispatch into the void.
-    const navItems = buildMobileNavItems(iconRail, contextRail, resolvedRightPanel.panelViews);
+    // to a drawer that actually has content. Menu is always available because
+    // the mobile drawer now carries workspace actions and the theme toggle.
+    const navItems = buildMobileNavItems(contextRail, resolvedRightPanel.panelViews);
     const hasDrawerContent = navItems.length > 0;
     // Mobile menu drawer needs both main and utility items — desktop IconRail
     // shows both, so dropping utilityItems here would orphan items like Help/
@@ -37,13 +38,14 @@ export function AppShellWorkspace({ iconRail, contextRail, rightPanel, globalAct
     // rendered without an explicit-height ancestor (tests, direct imports). The
     // <AppShell> wrapper already enforces h-screen for the workspace variant, so
     // nested viewport-height divs collapse cleanly — no double-scroll.
-    return (_jsxs("div", { className: "flex h-screen flex-col", children: [isMobile ? (_jsx(MobileHeader, { globalActions: globalActions })) : (_jsx(ShellHeader, { globalActions: globalActions })), _jsxs("div", { className: "relative flex flex-1 overflow-hidden", children: [!isMobile && iconRail && (_jsx(IconRail, { mainItems: iconRail.mainItems, utilityItems: iconRail.utilityItems, footer: iconRail.footer, activeId: iconRail.activeId, renderLink: iconRail.renderLink })), !isMobile && contextRail && (_jsx(ContextRail, { appId: contextRail.appId, module: contextRail.module, activeItemId: contextRail.activeItemId })), _jsx(ShellMain, { layout: "workspace", children: children }), !isMobile && resolvedRightPanel.panelViews.length > 0 && (_jsx(RightPanel, { panelViews: staticPanelViews, defaultView: rightPanel?.defaultView }))] }), isMobile && hasDrawerContent && _jsx(MobileBottomNav, { items: navItems }), isMobile && hasDrawerContent && (_jsx(MobileDrawers, { menuItems: mobileMenuItems, menuActiveId: iconRail?.activeId, menuRenderLink: iconRail?.renderLink, module: contextRail?.module, moduleAppId: contextRail?.appId, panelViews: resolvedRightPanel.panelViews, defaultView: resolvedRightPanel.defaultView }))] }));
+    const commandRegistry = useContext(CommandRegistryContext);
+    const shell = (_jsxs("div", { className: "flex h-screen flex-col", children: [isMobile ? (_jsx(MobileHeader, { globalActions: globalActions })) : (_jsx(ShellHeader, { globalActions: globalActions, headerCenter: headerCenter, appTabsRenderLink: appTabs?.renderLink, workspaceMenuItems: workspace?.menuItems, workspaceMenuFooter: workspace?.menuFooter })), banners ? (_jsx("div", { "data-meda-banners": "", className: "flex-shrink-0", children: banners })) : (false), _jsxs("div", { className: "relative flex flex-1 overflow-hidden", children: [!isMobile && iconRail && (_jsx(IconRail, { mainItems: iconRail.mainItems, utilityItems: iconRail.utilityItems, footer: iconRail.footer, activeId: iconRail.activeId, renderLink: iconRail.renderLink })), !isMobile && contextRail && (_jsx(ContextRail, { appId: contextRail.appId, module: contextRail.module, activeItemId: contextRail.activeItemId })), _jsx(ShellMain, { layout: mainLayout ?? 'workspace', className: mainClassName, children: children }), !isMobile && resolvedRightPanel.panelViews.length > 0 && (_jsx(RightPanel, { panelViews: staticPanelViews, defaultView: rightPanel?.defaultView }))] }), isMobile && hasDrawerContent && _jsx(MobileBottomNav, { items: navItems }), isMobile && hasDrawerContent && (_jsx(MobileDrawers, { menuItems: mobileMenuItems, menuActiveId: iconRail?.activeId, menuRenderLink: iconRail?.renderLink, workspaceMenuItems: workspace?.menuItems, workspaceMenuFooter: workspace?.menuFooter, module: contextRail?.module, moduleAppId: contextRail?.appId, panelViews: resolvedRightPanel.panelViews, defaultView: resolvedRightPanel.defaultView }))] }));
+    return commandRegistry ? shell : _jsx(CommandPalette, { children: shell });
 }
-function buildMobileNavItems(iconRail, contextRail, panelViews) {
-    const items = [];
-    if (iconRail) {
-        items.push({ id: 'menu', label: 'Menu', icon: Menu, opens: 'menu-drawer' });
-    }
+function buildMobileNavItems(contextRail, panelViews) {
+    const items = [
+        { id: 'menu', label: 'Menu', icon: Menu, opens: 'menu-drawer' },
+    ];
     if (contextRail?.module &&
         ((contextRail.module.items ?? []).length > 0 || Boolean(contextRail.module.render))) {
         items.push({ id: 'module', label: 'Module', icon: LayoutGrid, opens: 'module-drawer' });

package/dist/shell/app-shell.d.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from 'react';
-import type { AppShellAuthBranding, AppShellAuthConfig, AppShellContextRailConfig, AppShellIconRailConfig, AppShellRightPanelConfig } from './types.js';
+import type { AppShellAppTabsConfig, AppShellAuthBranding, AppShellAuthConfig, AppShellContextRailConfig, AppShellIconRailConfig, AppShellRightPanelConfig, AppShellWorkspaceConfig, ShellMainLayout } from './types.js';
 interface AppShellBaseProps {
     children: ReactNode;
     className?: string;
@@ -15,7 +15,37 @@ export type AppShellProps = AppShellBaseProps & ({
     iconRail?: AppShellIconRailConfig;
     contextRail?: AppShellContextRailConfig;
     rightPanel?: AppShellRightPanelConfig;
+    /**
+     * Configurable workspace dropdown — replaces the package-default
+     * "Manage workspaces / Settings / Profile / Sign out" entries when
+     * `menuItems` is provided. The theme toggle is preserved automatically.
+     */
+    workspace?: AppShellWorkspaceConfig;
+    /**
+     * Optional application-tab rendering config, used for router-specific
+     * link integration.
+     */
+    appTabs?: AppShellAppTabsConfig;
     globalActions?: ReactNode;
+    /**
+     * Optional center-region header content. Replaces the default
+     * application tabs when provided.
+     */
+    headerCenter?: ReactNode;
+    /**
+     * Optional chrome-level content rendered below the header and above
+     * the workspace rail row.
+     */
+    banners?: ReactNode;
+    /**
+     * Layout passed through to the workspace shell's main scroll region.
+     * Defaults to `workspace`.
+     */
+    mainLayout?: ShellMainLayout;
+    /**
+     * Optional className for the workspace shell's main scroll region.
+     */
+    mainClassName?: string;
 } | {
     variant: 'chat';
     globalActions?: ReactNode;

package/dist/shell/app-shell.js

@@ -16,7 +16,7 @@ export function AppShell(props) {
         case 'auth':
             return wrapper(_jsx(AppShellAuth, { ...resolveAuthConfig(props), children: props.children }));
         case 'workspace':
-            return wrapper(_jsx(AppShellWorkspace, { iconRail: props.iconRail, contextRail: props.contextRail, rightPanel: props.rightPanel, globalActions: props.globalActions, children: props.children }));
+            return wrapper(_jsx(AppShellWorkspace, { iconRail: props.iconRail, contextRail: props.contextRail, rightPanel: props.rightPanel, workspace: props.workspace, appTabs: props.appTabs, globalActions: props.globalActions, headerCenter: props.headerCenter, banners: props.banners, mainLayout: props.mainLayout, mainClassName: props.mainClassName, children: props.children }));
         case 'chat':
             return wrapper(_jsx(AppShellChat, { globalActions: props.globalActions, children: props.children }));
     }

package/dist/shell/index.d.ts

@@ -20,11 +20,12 @@ export type { RailDropZonesProps } from './rail-drop-zones.js';
 export { RailDropZones } from './rail-drop-zones.js';
 export { ResizableHandle, ResizableShell, ResizableShellPanel } from './resizable-shell.js';
 export { RightPanel } from './right-panel.js';
+export type { AppTabsProps } from './shell-header.js';
 export { AppTabs, PanelToggle, ShellHeader, WorkspaceSwitcher } from './shell-header.js';
 export { ShellMain } from './shell-main.js';
 export type { MedaShellProviderProps } from './shell-provider.js';
 export { MedaShellProvider, useMedaShell, useShellSelection } from './shell-provider.js';
 export { DefaultThemeProvider, ThemeToggle, useTheme } from './theme.js';
 export { NextThemesAdapter } from './theme-next-themes.js';
-export type { AppDefinition, AppShellAuthBranding, AppShellAuthConfig, AppShellContextRailConfig, AppShellIconRailConfig, AppShellRightPanelConfig, AppShellVariant, CommandDefinition, ContextItem, ContextModule, MobileBottomNavItem, PanelMode, PanelView, ShellLinkRenderArgs, ShellMainLayout, ShellRenderContext, ShellViewport, ThemeAdapter, WorkspaceDefinition, } from './types.js';
+export type { AppDefinition, AppShellAppTabsConfig, AppShellAuthBranding, AppShellAuthConfig, AppShellContextRailConfig, AppShellIconRailConfig, AppShellRightPanelConfig, AppShellVariant, AppShellWorkspaceConfig, AppTabRenderLinkArgs, CommandDefinition, ContextItem, ContextModule, MobileBottomNavItem, PanelMode, PanelView, ShellLinkRenderArgs, ShellMainLayout, ShellRenderContext, ShellViewport, ThemeAdapter, WorkspaceDefinition, WorkspaceMenuItem, } from './types.js';
 export { useShellViewport } from './use-shell-viewport.js';

package/dist/shell/index.js

@@ -24,7 +24,6 @@ export { RailDropSlot } from './rail-drop-slot.js';
 export { RailDropZones } from './rail-drop-zones.js';
 export { ResizableHandle, ResizableShell, ResizableShellPanel } from './resizable-shell.js';
 export { RightPanel } from './right-panel.js';
-// Header (and its individual children for advanced composition)
 export { AppTabs, PanelToggle, ShellHeader, WorkspaceSwitcher } from './shell-header.js';
 export { ShellMain } from './shell-main.js';
 // Provider + hooks

package/dist/shell/internal/mobile-drawers.d.ts

@@ -1,6 +1,6 @@
 import { type ReactNode } from 'react';
 import type { IconRailItem, IconRailProps } from '../icon-rail.js';
-import type { ContextModule, PanelView } from '../types.js';
+import type { ContextModule, PanelView, WorkspaceMenuItem } from '../types.js';
 export interface MobileDrawersProps {
     /** Menu drawer source (icon-rail items). */
     menuItems?: IconRailItem[];
@@ -8,6 +8,10 @@ export interface MobileDrawersProps {
     menuActiveId?: string;
     /** Custom menu link renderer, sourced from icon rail config. */
     menuRenderLink?: IconRailProps['renderLink'];
+    /** Workspace-level menu items rendered after icon rail links on mobile. */
+    workspaceMenuItems?: WorkspaceMenuItem[];
+    /** Workspace-level footer rendered after workspace items and the theme toggle. */
+    workspaceMenuFooter?: ReactNode;
     /** Module drawer source (current app's context-rail module). */
     module?: ContextModule;
     /** App id used when rendering module custom content. */
@@ -29,4 +33,4 @@ export interface MobileDrawersProps {
  * any custom-content drawers. Mount once near the AppShell root; drawers
  * open/close via `ctx.mobileDrawer.open` provider state.
  */
-export declare function MobileDrawers({ menuItems, menuActiveId, menuRenderLink, module, moduleAppId, panelViews, defaultView, customContent, }: MobileDrawersProps): import("react/jsx-runtime").JSX.Element;
+export declare function MobileDrawers({ menuItems, menuActiveId, menuRenderLink, workspaceMenuItems, workspaceMenuFooter, module, moduleAppId, panelViews, defaultView, customContent, }: MobileDrawersProps): import("react/jsx-runtime").JSX.Element;

package/dist/shell/internal/mobile-drawers.js

@@ -1,15 +1,17 @@
 'use client';
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { cloneElement, isValidElement, useEffect } from 'react';
+import { Monitor, Moon, Sun } from 'lucide-react';
+import { cloneElement, createElement, Fragment, isValidElement, useEffect, } from 'react';
 import { Drawer, DrawerContent, DrawerDescription, DrawerHeader, DrawerTitle, } from '../../components/ui/drawer.js';
 import { cn } from '../../lib/utils.js';
 import { useMedaShell } from '../shell-provider.js';
+import { useTheme } from '../theme.js';
 /**
  * Renders all four mobile drawer slots (Menu / Module / Panels / AI) plus
  * any custom-content drawers. Mount once near the AppShell root; drawers
  * open/close via `ctx.mobileDrawer.open` provider state.
  */
-export function MobileDrawers({ menuItems = [], menuActiveId, menuRenderLink, module, moduleAppId, panelViews = [], defaultView, customContent = {}, }) {
+export function MobileDrawers({ menuItems = [], menuActiveId, menuRenderLink, workspaceMenuItems, workspaceMenuFooter, module, moduleAppId, panelViews = [], defaultView, customContent = {}, }) {
     const ctx = useMedaShell();
     const open = ctx.mobileDrawer.open;
     const setOpen = ctx.mobileDrawer.setOpen;
@@ -22,13 +24,15 @@ export function MobileDrawers({ menuItems = [], menuActiveId, menuRenderLink, mo
         workspaceId: ctx.workspace.id,
         appId: moduleAppId ?? ctx.activeAppId,
     };
-    return (_jsxs(_Fragment, { children: [_jsx(MenuDrawer, { open: open === 'menu-drawer', onClose: close, items: menuItems, activeId: menuActiveId, renderLink: menuRenderLink }), _jsx(ModuleDrawer, { open: open === 'module-drawer', onClose: close, module: module, renderCtx: moduleRenderCtx }), _jsx(PanelsDrawer, { open: open === 'panels-drawer', onClose: close, panelViews: panelViews, defaultView: defaultView, renderCtx: renderCtx }), _jsx(AiDrawer, { open: open === 'ai-drawer', onClose: close, panelViews: panelViews, renderCtx: renderCtx }), Object.entries(customContent).map(([id, renderFn]) => (_jsx(Drawer, { open: open === id, onOpenChange: (o) => !o && close(), direction: "bottom", children: _jsx(DrawerContent, { children: renderFn(close) }) }, id)))] }));
+    return (_jsxs(_Fragment, { children: [_jsx(MenuDrawer, { open: open === 'menu-drawer', onClose: close, items: menuItems, activeId: menuActiveId, renderLink: menuRenderLink, workspaceItems: workspaceMenuItems, workspaceFooter: workspaceMenuFooter }), _jsx(ModuleDrawer, { open: open === 'module-drawer', onClose: close, module: module, renderCtx: moduleRenderCtx }), _jsx(PanelsDrawer, { open: open === 'panels-drawer', onClose: close, panelViews: panelViews, defaultView: defaultView, renderCtx: renderCtx }), _jsx(AiDrawer, { open: open === 'ai-drawer', onClose: close, panelViews: panelViews, renderCtx: renderCtx }), Object.entries(customContent).map(([id, renderFn]) => (_jsx(Drawer, { open: open === id, onOpenChange: (o) => !o && close(), direction: "bottom", children: _jsx(DrawerContent, { children: renderFn(close) }) }, id)))] }));
 }
 // ---------------------------------------------------------------------------
 // Internal sub-drawers
 // ---------------------------------------------------------------------------
-function MenuDrawer({ open, onClose, items, activeId, renderLink, }) {
-    return (_jsx(Drawer, { open: open, onOpenChange: (o) => !o && onClose(), direction: "left", children: _jsxs(DrawerContent, { children: [_jsxs(DrawerHeader, { children: [_jsx(DrawerTitle, { children: "Menu" }), _jsx(DrawerDescription, { className: "sr-only", children: "Switch between primary app areas." })] }), _jsx("nav", { className: "flex flex-col gap-0.5 p-2", children: items.map((item) => (_jsx(MenuDrawerItem, { item: item, isActive: item.id === activeId, onClose: onClose, renderLink: renderLink }, item.id))) })] }) }));
+function MenuDrawer({ open, onClose, items, activeId, renderLink, workspaceItems, workspaceFooter, }) {
+    const hasIconItems = items.length > 0;
+    const hasWorkspaceItems = Array.isArray(workspaceItems) && workspaceItems.length > 0;
+    return (_jsx(Drawer, { open: open, onOpenChange: (o) => !o && onClose(), direction: "left", children: _jsxs(DrawerContent, { children: [_jsxs(DrawerHeader, { children: [_jsx(DrawerTitle, { children: "Menu" }), _jsx(DrawerDescription, { className: "sr-only", children: "Switch between primary app areas." })] }), _jsxs("div", { className: "flex flex-col gap-2 p-2", children: [hasIconItems && (_jsx("nav", { "aria-label": "Primary navigation", className: "flex flex-col gap-0.5", children: items.map((item) => (_jsx(MenuDrawerItem, { item: item, isActive: item.id === activeId, onClose: onClose, renderLink: renderLink }, item.id))) })), (hasIconItems || hasWorkspaceItems) && _jsx("div", { className: "h-px bg-border" }), _jsxs("nav", { "aria-label": "Workspace menu", className: "flex flex-col gap-0.5", children: [workspaceItems?.map((item) => (_jsxs(Fragment, { children: [_jsx(WorkspaceMenuDrawerItem, { item: item, onClose: onClose }), item.separatorAfter && _jsx("div", { className: "my-1 h-px bg-border" })] }, item.id))), _jsx(MobileThemeMenuItem, { onClose: onClose })] }), workspaceFooter] })] }) }));
 }
 const menuItemClassName = 'flex items-center gap-2 rounded-md px-3 py-2 text-sm text-muted-foreground hover:bg-accent hover:text-foreground';
 function MenuDrawerItem({ item, isActive, onClose, renderLink, }) {
@@ -63,6 +67,49 @@ function closeAfterLinkClick(link, onClose) {
         },
     });
 }
+function renderWorkspaceIcon(icon) {
+    if (icon == null)
+        return null;
+    if (isValidElement(icon))
+        return icon;
+    if (typeof icon === 'function') {
+        return createElement(icon, { size: 18, 'aria-hidden': true });
+    }
+    if (typeof icon === 'object') {
+        const candidate = icon;
+        if (candidate.$$typeof != null) {
+            return createElement(icon, { size: 18, 'aria-hidden': true });
+        }
+    }
+    return icon;
+}
+function WorkspaceMenuDrawerItem({ item, onClose, }) {
+    const children = (_jsxs(_Fragment, { children: [renderWorkspaceIcon(item.icon), _jsx("span", { children: item.label })] }));
+    const className = cn(menuItemClassName, item.variant === 'destructive' && 'text-destructive hover:text-destructive');
+    const handleClick = () => {
+        item.onClick?.();
+        onClose();
+    };
+    if (item.href != null) {
+        return closeAfterLinkClick(_jsx("a", { href: item.href, className: className, "data-variant": item.variant ?? 'default', onClick: () => item.onClick?.(), children: children }), onClose);
+    }
+    return (_jsx("button", { type: "button", "data-variant": item.variant ?? 'default', className: className, onClick: handleClick, children: children }));
+}
+const NEXT_THEME = { light: 'dark', dark: 'system', system: 'light' };
+const THEME_ICON = { light: Sun, dark: Moon, system: Monitor };
+const THEME_LABEL = {
+    light: 'Switch to dark theme',
+    dark: 'Switch to system theme',
+    system: 'Switch to light theme',
+};
+function MobileThemeMenuItem({ onClose }) {
+    const { theme, setTheme } = useTheme();
+    const Icon = THEME_ICON[theme];
+    return (_jsxs("button", { type: "button", "aria-label": THEME_LABEL[theme], className: menuItemClassName, onClick: () => {
+            setTheme(NEXT_THEME[theme]);
+            onClose();
+        }, children: [_jsx(Icon, { size: 18, "aria-hidden": "true" }), _jsx("span", { children: THEME_LABEL[theme] })] }));
+}
 function ModuleDrawer({ open, onClose, module, renderCtx, }) {
     const items = module?.items ?? [];
     if (!module || (items.length === 0 && !module.render))
@@ -90,7 +137,7 @@ function PanelsDrawer({ open, onClose, panelViews, defaultView, renderCtx, }) {
     const active = panelViews.find((v) => v.id === activeView) ??
         (defaultView ? panelViews.find((v) => v.id === defaultView) : undefined) ??
         panelViews[0];
-    return (_jsx(Drawer, { open: open, onOpenChange: (o) => !o && onClose(), direction: "bottom", children: _jsxs(DrawerContent, { children: [_jsxs(DrawerHeader, { children: [_jsx(DrawerTitle, { children: active?.label ?? 'Panels' }), _jsx(DrawerDescription, { className: "sr-only", children: "Contextual panels for the current module." })] }), panelViews.length > 1 && (_jsx("div", { className: "flex items-center gap-1 border-b border-border px-3 py-2", children: panelViews.map((view) => (_jsx("button", { type: "button", onClick: () => ctx.panel.setActiveView(view.id), "aria-current": view.id === activeView ? 'true' : undefined, className: cn('rounded-md px-2 py-1 text-xs', view.id === activeView
+    return (_jsx(Drawer, { open: open, onOpenChange: (o) => !o && onClose(), direction: "bottom", children: _jsxs(DrawerContent, { children: [_jsxs(DrawerHeader, { children: [_jsx(DrawerTitle, { children: active?.label ?? 'Panels' }), _jsx(DrawerDescription, { className: "sr-only", children: "Contextual panels for the current module." })] }), panelViews.length > 1 && (_jsx("div", { className: "flex items-center gap-1 border-b border-border px-3 py-2", children: panelViews.map((view) => (_jsx("button", { type: "button", onClick: () => ctx.panel.setActiveView(view.id), "aria-current": view.id === activeView ? 'true' : undefined, className: cn('rounded-md px-2 py-1 text-sm', view.id === activeView
                             ? 'bg-accent text-accent-foreground'
                             : 'text-muted-foreground hover:bg-accent'), children: view.label }, view.id))) })), _jsx("div", { className: "flex-1 overflow-y-auto p-3", children: active?.render(renderCtx) })] }) }));
 }

package/dist/shell/shell-header.d.ts

@@ -1,12 +1,42 @@
-import type { ReactNode } from 'react';
+import { type ReactNode } from 'react';
+import type { AppShellAppTabsConfig, WorkspaceMenuItem } from './types.js';
 export interface WorkspaceSwitcherProps {
+    /**
+     * Configurable dropdown items. When provided, REPLACES the default
+     * "Manage workspaces / Settings / Profile / Sign out" entries. The theme
+     * toggle is still inserted automatically by meda — between the items and
+     * the footer — so consumers don't have to reimplement theme cycling.
+     *
+     * When omitted, the package-default items render (1.x behavior).
+     */
+    menuItems?: WorkspaceMenuItem[];
+    /**
+     * Extra content rendered after all items and the theme toggle. Backwards-
+     * compatible alias for the legacy `workspaceMenuFooter` prop.
+     */
+    menuFooter?: ReactNode;
+    /** @deprecated Use `menuFooter` instead. */
     workspaceMenuFooter?: ReactNode;
 }
-export declare function WorkspaceSwitcher({ workspaceMenuFooter }?: WorkspaceSwitcherProps): import("react/jsx-runtime").JSX.Element;
-export declare function AppTabs(): import("react/jsx-runtime").JSX.Element;
+export declare function WorkspaceSwitcher({ menuItems, menuFooter, workspaceMenuFooter, }?: WorkspaceSwitcherProps): import("react/jsx-runtime").JSX.Element;
+export interface AppTabsProps extends AppShellAppTabsConfig {
+}
+export declare function AppTabs({ renderLink }?: AppTabsProps): import("react/jsx-runtime").JSX.Element;
 export declare function PanelToggle(): import("react/jsx-runtime").JSX.Element;
 export interface ShellHeaderProps {
     globalActions?: ReactNode;
+    /**
+     * Optional center-region content. Replaces the default application tabs when
+     * provided.
+     */
+    headerCenter?: ReactNode;
+    appTabsRenderLink?: AppShellAppTabsConfig['renderLink'];
     className?: string;
+    /**
+     * Forwarded to the internal `<WorkspaceSwitcher>`. See
+     * `WorkspaceSwitcherProps` for the full shape.
+     */
+    workspaceMenuItems?: WorkspaceMenuItem[];
+    workspaceMenuFooter?: ReactNode;
 }
-export declare function ShellHeader({ globalActions, className }?: ShellHeaderProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function ShellHeader({ globalActions, headerCenter, appTabsRenderLink, className, workspaceMenuItems, workspaceMenuFooter, }?: ShellHeaderProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/shell/shell-header.js

@@ -1,6 +1,7 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { ChevronDown, Monitor, Moon, PanelRightClose, PanelRightOpen, Sun } from 'lucide-react';
+import { createElement, Fragment, isValidElement } from 'react';
 import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuTrigger, } from '../components/ui/dropdown-menu.js';
 import { cn } from '../lib/utils.js';
 import { useMedaShell } from './shell-provider.js';
@@ -18,25 +19,71 @@ function ThemeToggleMenuItem() {
     const Icon = THEME_ICON[theme];
     return (_jsxs(DropdownMenuItem, { onClick: () => setTheme(NEXT_THEME[theme]), children: [_jsx(Icon, { size: 16, "aria-hidden": "true" }), THEME_LABEL[theme]] }));
 }
-export function WorkspaceSwitcher({ workspaceMenuFooter } = {}) {
+function renderShellIcon(icon) {
+    if (icon == null)
+        return null;
+    if (isValidElement(icon))
+        return icon;
+    if (typeof icon === 'function') {
+        return createElement(icon, { size: 16, 'aria-hidden': true });
+    }
+    // forwardRef/memo components are objects carrying a `$$typeof` symbol —
+    // treat them like Lucide components. Plain ReactNode objects (arrays,
+    // iterables, promises) have no `$$typeof` and are rendered as-is so they
+    // don't crash createElement with "Element type is invalid".
+    if (typeof icon === 'object' && icon !== null) {
+        const candidate = icon;
+        if (candidate.$$typeof != null) {
+            return createElement(icon, {
+                size: 16,
+                'aria-hidden': true,
+            });
+        }
+    }
+    return icon;
+}
+function renderConfiguredItem(item) {
+    const handleSelect = () => item.onClick?.();
+    // Childless anchor — Base UI merges the DropdownMenuItem's children into the
+    // cloned render element. Passing children here would override the icon +
+    // label children below and configured icons would silently disappear.
+    // biome-ignore lint/a11y/useAnchorContent: children are injected at render time by Base UI's `render` prop
+    const renderLink = item.href != null ? _jsx("a", { href: item.href }) : undefined;
+    return (_jsxs(DropdownMenuItem, { render: renderLink, "data-variant": item.variant ?? 'default', className: item.variant === 'destructive' ? 'text-destructive' : undefined, onClick: handleSelect, children: [renderShellIcon(item.icon), item.label] }));
+}
+export function WorkspaceSwitcher({ menuItems, menuFooter, workspaceMenuFooter, } = {}) {
     const { workspace, workspaces } = useMedaShell();
-    return (_jsxs(DropdownMenu, { children: [_jsxs(DropdownMenuTrigger, { render: _jsx("button", { type: "button", className: "flex items-center gap-1.5 rounded-md px-2 py-1.5 text-sm font-medium hover:bg-accent" }), children: [workspace.icon != null && (_jsx("span", { className: "shrink-0", "aria-hidden": "true", children: workspace.icon })), _jsx("span", { children: workspace.name }), _jsx(ChevronDown, { size: 14, "aria-hidden": "true" })] }), _jsxs(DropdownMenuContent, { className: "min-w-[200px]", children: [workspaces.length > 0 && (_jsxs(_Fragment, { children: [workspaces.map((ws) => (_jsxs(DropdownMenuItem, { children: [ws.icon != null && _jsx("span", { "aria-hidden": "true", children: ws.icon }), ws.name] }, ws.id))), _jsx(DropdownMenuSeparator, {})] })), _jsx(DropdownMenuItem, { children: "Manage workspaces" }), _jsx(DropdownMenuSeparator, {}), _jsx(DropdownMenuItem, { children: "Settings" }), _jsx(DropdownMenuItem, { children: "Profile" }), _jsx(DropdownMenuSeparator, {}), _jsx(ThemeToggleMenuItem, {}), _jsx(DropdownMenuSeparator, {}), _jsx(DropdownMenuItem, { children: "Sign out" }), workspaceMenuFooter] })] }));
+    const resolvedFooter = menuFooter ?? workspaceMenuFooter;
+    const useConfiguredItems = Array.isArray(menuItems);
+    return (_jsxs(DropdownMenu, { children: [_jsxs(DropdownMenuTrigger, { render: _jsx("button", { type: "button", className: "flex items-center gap-1.5 rounded-md px-2 py-1.5 text-sm font-medium hover:bg-accent" }), children: [workspace.icon != null && (_jsx("span", { className: "shrink-0", "aria-hidden": "true", children: workspace.icon })), _jsx("span", { children: workspace.name }), _jsx(ChevronDown, { size: 14, "aria-hidden": "true" })] }), _jsxs(DropdownMenuContent, { className: "min-w-[200px]", children: [workspaces.length > 0 && (_jsxs(_Fragment, { children: [workspaces.map((ws) => (_jsxs(DropdownMenuItem, { children: [ws.icon != null && _jsx("span", { "aria-hidden": "true", children: ws.icon }), ws.name] }, ws.id))), _jsx(DropdownMenuSeparator, {})] })), useConfiguredItems ? (menuItems.map((item) => (_jsxs(Fragment, { children: [renderConfiguredItem(item), item.separatorAfter && _jsx(DropdownMenuSeparator, {})] }, item.id)))) : (_jsxs(_Fragment, { children: [_jsx(DropdownMenuItem, { children: "Manage workspaces" }), _jsx(DropdownMenuSeparator, {}), _jsx(DropdownMenuItem, { children: "Settings" }), _jsx(DropdownMenuItem, { children: "Profile" })] })), _jsx(DropdownMenuSeparator, {}), _jsx(ThemeToggleMenuItem, {}), !useConfiguredItems && (_jsxs(_Fragment, { children: [_jsx(DropdownMenuSeparator, {}), _jsx(DropdownMenuItem, { children: "Sign out" })] })), resolvedFooter] })] }));
 }
-// ---------------------------------------------------------------------------
-// AppTabs
-// ---------------------------------------------------------------------------
-export function AppTabs() {
+export function AppTabs({ renderLink } = {}) {
     const { apps, activeAppId, setActiveApp } = useMedaShell();
     return (_jsx("nav", { "aria-label": "Applications", className: "flex items-center", children: apps.map((app) => {
             const isActive = app.id === activeAppId;
-            const Icon = app.icon;
-            return (_jsxs("button", { type: "button", "aria-current": isActive ? 'page' : undefined, onClick: () => {
-                    setActiveApp(app.id);
-                    // TODO(Phase 18.x): renderLink integration so clicking a tab also navigates
-                    // the consumer's router; setActiveApp alone updates context.
-                }, onMouseEnter: () => { }, className: cn('flex items-center gap-1.5 px-3 py-2 text-sm font-medium transition-colors', isActive
-                    ? 'border-b-2 border-primary text-foreground'
-                    : 'text-muted-foreground hover:text-foreground'), children: [_jsx(Icon, { size: 16, "aria-hidden": "true" }), app.label] }, app.id));
+            const className = cn('flex items-center gap-1.5 px-3 py-2 text-sm font-medium transition-colors', isActive
+                ? 'border-b-2 border-primary text-foreground'
+                : 'text-muted-foreground hover:text-foreground');
+            const children = (_jsxs(_Fragment, { children: [renderShellIcon(app.icon), app.label] }));
+            const handleClick = () => {
+                setActiveApp(app.id);
+            };
+            if (renderLink && app.to) {
+                return (_jsx(Fragment, { children: renderLink({
+                        app,
+                        isActive,
+                        className,
+                        children,
+                        linkProps: {
+                            href: app.to,
+                            className,
+                            children,
+                            'aria-current': isActive ? 'page' : undefined,
+                            onClick: handleClick,
+                        },
+                    }) }, app.id));
+            }
+            return (_jsx("button", { type: "button", "aria-current": isActive ? 'page' : undefined, onClick: handleClick, onMouseEnter: () => { }, className: className, children: children }, app.id));
         }) }));
 }
 // ---------------------------------------------------------------------------
@@ -50,9 +97,9 @@ export function PanelToggle() {
     };
     return (_jsx("button", { type: "button", "aria-label": isOpen ? 'Close right panel' : 'Open right panel', onClick: handleClick, className: cn('inline-flex h-8 w-8 items-center justify-center rounded-md transition-colors', isOpen ? 'bg-accent text-accent-foreground' : 'text-muted-foreground hover:bg-accent'), children: isOpen ? (_jsx(PanelRightClose, { size: 18, "aria-hidden": "true" })) : (_jsx(PanelRightOpen, { size: 18, "aria-hidden": "true" })) }));
 }
-export function ShellHeader({ globalActions, className } = {}) {
+export function ShellHeader({ globalActions, headerCenter, appTabsRenderLink, className, workspaceMenuItems, workspaceMenuFooter, } = {}) {
     const band = useShellViewport();
     if (band === 'mobile')
         return null;
-    return (_jsxs("header", { className: cn('flex h-[var(--shell-header-height)] w-full items-center justify-between', 'border-b border-border bg-background px-3', className), children: [_jsxs("div", { className: "flex items-center", children: [_jsx(WorkspaceSwitcher, {}), _jsx(AppTabs, {})] }), _jsxs("div", { className: "flex items-center gap-2", children: [globalActions, _jsx(PanelToggle, {})] })] }));
+    return (_jsxs("header", { className: cn('flex h-[var(--shell-header-height)] w-full items-center justify-between', 'gap-3 border-b border-border bg-background px-3', className), children: [_jsx("div", { className: "flex shrink-0 items-center", children: _jsx(WorkspaceSwitcher, { menuItems: workspaceMenuItems, menuFooter: workspaceMenuFooter }) }), _jsx("div", { className: "flex min-w-0 flex-1 items-center", children: headerCenter !== undefined ? headerCenter : _jsx(AppTabs, { renderLink: appTabsRenderLink }) }), _jsxs("div", { className: "flex shrink-0 items-center gap-2", children: [globalActions, _jsx(PanelToggle, {})] })] }));
 }

package/dist/shell/shell-provider.js

@@ -8,9 +8,8 @@ import { useShellViewport } from './use-shell-viewport.js';
 // ---------------------------------------------------------------------------
 // Theme adapter wiring
 // ---------------------------------------------------------------------------
-// Lazy-loaded so that importing next-themes only happens when the consumer
-// passes themeAdapter='next-themes'. Default-adapter consumers never trigger
-// the import.
+// Lazy-loaded so default-adapter consumers do not pay for the compatibility
+// bridge used when themeAdapter='next-themes'.
 const NextThemesAdapter = lazy(() => import('./theme-next-themes.js').then((m) => ({ default: m.NextThemesAdapter })));
 function CustomThemeBridge({ adapter, children }) {
     return _jsx(ThemeCtx.Provider, { value: adapter, children: children });

package/dist/shell/theme-next-themes.d.ts

@@ -1,4 +1,4 @@
-import type { ReactNode } from 'react';
+import { type ReactNode } from 'react';
 export declare function NextThemesAdapter({ children }: {
     children: ReactNode;
 }): import("react/jsx-runtime").JSX.Element;

package/dist/shell/theme-next-themes.js

@@ -1,24 +1,115 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
-import { ThemeProvider as NextThemesProvider, useTheme as useNextTheme } from 'next-themes';
+import { useCallback, useEffect, useInsertionEffect, useMemo, useState, } from 'react';
 import { ThemeCtx } from './theme.js';
+const STORAGE_KEY = 'theme';
+const MEDIA_QUERY = '(prefers-color-scheme: dark)';
+const THEMES = ['light', 'dark'];
 function narrow(value) {
-    if (value === 'light' || value === 'dark' || value === 'system')
-        return value;
-    return 'system';
-}
-function narrowResolved(value) {
-    return value === 'dark' ? 'dark' : 'light';
-}
-function NextThemesBridge({ children }) {
-    const { theme, setTheme, resolvedTheme } = useNextTheme();
-    const value = {
-        theme: narrow(theme),
-        setTheme: (t) => setTheme(t),
-        resolvedTheme: narrowResolved(resolvedTheme),
+    return value === 'light' || value === 'dark' || value === 'system' ? value : 'system';
+}
+function getMediaQueryList() {
+    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function')
+        return undefined;
+    return window.matchMedia(MEDIA_QUERY);
+}
+function resolveSystemTheme(mql) {
+    if (mql)
+        return mql.matches ? 'dark' : 'light';
+    return getMediaQueryList()?.matches ? 'dark' : 'light';
+}
+function getStoredTheme() {
+    if (typeof window === 'undefined')
+        return 'system';
+    try {
+        return narrow(window.localStorage.getItem(STORAGE_KEY));
+    }
+    catch {
+        return 'system';
+    }
+}
+function applyTheme(theme, resolvedTheme) {
+    if (typeof document === 'undefined')
+        return;
+    const root = document.documentElement;
+    const applied = theme === 'system' ? resolvedTheme : theme;
+    root.classList.remove(...THEMES);
+    root.classList.add(applied);
+    root.style.colorScheme = applied;
+}
+function getClientThemeSnapshot() {
+    const theme = getStoredTheme();
+    return {
+        theme,
+        resolvedTheme: theme === 'system' ? resolveSystemTheme() : theme,
     };
-    return _jsx(ThemeCtx.Provider, { value: value, children: children });
+}
+function subscribeToSystemTheme(mql, listener) {
+    if (!mql)
+        return () => { };
+    if (typeof mql.addEventListener === 'function') {
+        mql.addEventListener('change', listener);
+        return () => mql.removeEventListener('change', listener);
+    }
+    if (typeof mql.addListener === 'function') {
+        mql.addListener(listener);
+        return () => mql.removeListener?.(listener);
+    }
+    return () => { };
 }
 export function NextThemesAdapter({ children }) {
-    return (_jsx(NextThemesProvider, { attribute: "class", enableSystem: true, defaultTheme: "system", children: _jsx(NextThemesBridge, { children: children }) }));
+    const [theme, setThemeState] = useState('system');
+    const [resolvedTheme, setResolvedTheme] = useState('light');
+    const [hydrated, setHydrated] = useState(false);
+    const setTheme = useCallback((next) => {
+        setThemeState(next);
+        const resolved = next === 'system' ? resolveSystemTheme() : next;
+        setResolvedTheme(resolved);
+        applyTheme(next, resolved);
+        try {
+            if (typeof window !== 'undefined')
+                window.localStorage.setItem(STORAGE_KEY, next);
+        }
+        catch {
+            // Ignore unavailable storage, matching next-themes' best-effort behavior.
+        }
+    }, []);
+    useInsertionEffect(() => {
+        const snapshot = getClientThemeSnapshot();
+        applyTheme(snapshot.theme, snapshot.resolvedTheme);
+    }, []);
+    useEffect(() => {
+        const stored = getClientThemeSnapshot();
+        setThemeState(stored.theme);
+        setResolvedTheme(stored.resolvedTheme);
+        setHydrated(true);
+        applyTheme(stored.theme, stored.resolvedTheme);
+    }, []);
+    useEffect(() => {
+        if (!hydrated)
+            return;
+        const mql = getMediaQueryList();
+        const sync = (_event) => {
+            const resolved = theme === 'system' ? resolveSystemTheme(mql) : theme;
+            setResolvedTheme(resolved);
+            applyTheme(theme, resolved);
+        };
+        sync();
+        return subscribeToSystemTheme(mql, sync);
+    }, [hydrated, theme]);
+    useEffect(() => {
+        const handleStorage = (event) => {
+            if (event.key !== STORAGE_KEY)
+                return;
+            setThemeState(narrow(event.newValue));
+        };
+        window.addEventListener('storage', handleStorage);
+        return () => window.removeEventListener('storage', handleStorage);
+    }, []);
+    const value = useMemo(() => ({
+        theme,
+        setTheme,
+        resolvedTheme,
+    }), [theme, setTheme, resolvedTheme]);
+    return _jsx(ThemeCtx.Provider, { value: value, children: children });
 }

package/dist/shell/types.d.ts

@@ -3,7 +3,23 @@ import type { AnchorHTMLAttributes, ReactNode } from 'react';
 export interface AppDefinition {
     id: string;
     label: string;
-    icon: LucideIcon;
+    /**
+     * Either a Lucide-style icon component or a rendered React node such as a
+     * custom brand SVG.
+     */
+    icon: LucideIcon | ReactNode;
+    /** Optional route target for consumers that render app tabs as links. */
+    to?: string;
+}
+export interface AppTabRenderLinkArgs {
+    app: AppDefinition;
+    isActive: boolean;
+    className: string;
+    children: ReactNode;
+    linkProps: AnchorHTMLAttributes<HTMLAnchorElement>;
+}
+export interface AppShellAppTabsConfig {
+    renderLink?: (args: AppTabRenderLinkArgs) => ReactNode;
 }
 export interface WorkspaceDefinition {
     id: string;
@@ -93,6 +109,44 @@ export interface AppShellRightPanelConfig {
     panelViews: PanelView[];
     defaultView?: string;
 }
+/**
+ * A single configurable item in the WorkspaceSwitcher dropdown.
+ * Either `href` (renders as a link) or `onClick` (renders as a button) MUST
+ * be provided; supplying both makes the item a button that fires `onClick`
+ * AND navigates to `href` afterwards.
+ */
+interface WorkspaceMenuItemBase {
+    id: string;
+    label: ReactNode;
+    icon?: LucideIcon | ReactNode;
+    /** Insert a `<DropdownMenuSeparator />` immediately after this item. */
+    separatorAfter?: boolean;
+    /** Visual intent — `destructive` paints with the destructive token. */
+    variant?: 'default' | 'destructive';
+}
+export type WorkspaceMenuItem = WorkspaceMenuItemBase & ({
+    href: string;
+    onClick?: () => void;
+} | {
+    onClick: () => void;
+    href?: string;
+});
+/**
+ * Workspace dropdown configuration for `<AppShell variant="workspace">`.
+ *
+ * When `menuItems` is provided, it REPLACES the package-default menu
+ * ("Manage workspaces", "Settings", "Profile", "Sign out"). The theme toggle
+ * is still inserted automatically by meda — between the items and the footer
+ * — so consumers don't have to reimplement theme cycling.
+ *
+ * When `menuItems` is omitted, the package defaults render unchanged (the
+ * existing 1.x behavior). This is fully additive and non-breaking.
+ */
+export interface AppShellWorkspaceConfig {
+    menuItems?: WorkspaceMenuItem[];
+    /** Extra slot rendered after all items and the theme toggle. */
+    menuFooter?: ReactNode;
+}
 export interface AppShellAuthConfig {
     title: ReactNode;
     description?: ReactNode;
@@ -108,3 +162,4 @@ export interface AppShellAuthBranding {
     appName?: ReactNode;
     tagline?: ReactNode;
 }
+export {};

package/dist/styles/theme.css

@@ -1,7 +1,34 @@
 @import "./tokens.css";
 
+/* Tell Tailwind v4 to scan meda's compiled component output so utilities
+   like `h-full`, `mt-auto`, `py-3.5`, and `bg-shell-rail` (used by IconRail,
+   AppShellWorkspace, etc.) are generated even when the consumer app doesn't
+   reference them itself. Without this, consumers see broken layout where
+   meda components rely on classes the app doesn't otherwise use. Path is
+   resolved relative to this CSS file at build time, so it points to the
+   sibling component output regardless of where the package is installed. */
+@source "../**/*.js";
+
 @custom-variant dark (&:is(.dark *, [data-theme="dark"] *));
 
+@layer base {
+  :root {
+    color-scheme: light;
+    --auth-gradient-primary: var(--color-brand-500);
+    --auth-gradient-secondary: var(--color-brand-700);
+    --auth-gradient-base: var(--color-brand-800);
+  }
+
+  .dark,
+  [data-theme="dark"] {
+    color-scheme: dark;
+  }
+}
+
+[data-vaul-drawer][data-state="open"] {
+  will-change: auto;
+}
+
 @theme inline {
   /* Color primitives — exposed as Tailwind color scales */
 

package/dist/styles/theme.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest';
+
+// Read theme.css via Node's runtime APIs without pulling in @types/node.
+// Declared locally so the package-level tsconfig (which doesn't include
+// node typings) still typechecks cleanly under jsdom Vitest runs.
+declare const require: (id: string) => unknown;
+declare const __dirname: string;
+
+const fs = require('node:fs') as { readFileSync(p: string, enc: string): string };
+const path = require('node:path') as { join(...parts: string[]): string };
+const themeCss = fs.readFileSync(path.join(__dirname, 'theme.css'), 'utf8');
+
+describe('theme.css', () => {
+  // Tailwind v4 only generates utility classes for class names it sees in
+  // scanned files. Consumer apps don't reference every utility used by meda
+  // components (e.g. `h-full`, `mt-auto`, `py-3.5`, `bg-shell-rail` on
+  // IconRail), so without an @source directive pointing at meda's compiled
+  // dist files, those classes silently disappear and component layouts
+  // collapse — most visibly, the IconRail's utility items fail to pin to
+  // the bottom of the viewport because `mt-auto` never gets generated.
+  //
+  // The directive is resolved relative to this CSS file at build time. Since
+  // src/styles/theme.css is copied verbatim to dist/styles/theme.css by the
+  // build script, `../**/*.js` from the dist location scans every emitted
+  // component module — exactly the surface consumers import from.
+  it('declares an @source directive that scans meda component output', () => {
+    expect(themeCss).toMatch(/@source\s+["']\.\.\/\*\*\/\*\.js["']/);
+  });
+
+  it('declares dedicated auth gradient tokens for consumer overrides', () => {
+    expect(themeCss).toContain('--auth-gradient-primary: var(--color-brand-500);');
+    expect(themeCss).toContain('--auth-gradient-secondary: var(--color-brand-700);');
+    expect(themeCss).toContain('--auth-gradient-base: var(--color-brand-800);');
+  });
+
+  it('neutralizes vaul drawer layer hints after mobile drawers are open', () => {
+    expect(themeCss).toMatch(
+      /\[data-vaul-drawer\]\[data-state=["']open["']\]\s*\{[^}]*will-change:\s*auto;/s
+    );
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@medalsocial/meda",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Shared Meda UI shell and runtime package.",
   "license": "Apache-2.0",
   "repository": {