@medalsocial/meda 1.5.0 → 1.7.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,53 @@ 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.
+
+## Foundation primitives
+
+Meda includes small foundation primitives for repeated loading, empty, and filtering surfaces:
+
+```tsx
+import { EmptyState, FilterRail, Skeleton } from '@medalsocial/meda';
+```
+
+`Skeleton` mirrors shadcn's simple loading placeholder shape. `EmptyState` standardizes zero/error states across panels and content areas. `FilterRail` provides a dense filter surface while leaving selected values, URL syncing, and query logic in the consuming app.
+
+The same primitives are available from the shadcn-compatible registry when an app wants local source ownership:
+
+```bash
+npx shadcn add https://meda.medalsocial.com/r/meda-skeleton.json
+npx shadcn add https://meda.medalsocial.com/r/meda-empty-state.json
+npx shadcn add https://meda.medalsocial.com/r/meda-filter-rail.json
+```
+
 For app-scoped brand tokens:
 
 ```ts

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export * from './brand/public.js';
 export * from './chat/public.js';
 export * from './marketing/public.js';
 export * from './panel/public.js';
+export * from './primitives/index.js';
 export * from './shell/index.js';
 export * from './theme/index.js';
 export * from './timeline/public.js';

package/dist/index.js

@@ -3,6 +3,7 @@ export * from './brand/public.js';
 export * from './chat/public.js';
 export * from './marketing/public.js';
 export * from './panel/public.js';
+export * from './primitives/index.js';
 export * from './shell/index.js'; // v2 surface
 export * from './theme/index.js';
 export * from './timeline/public.js';

package/dist/primitives/empty-state.d.ts

@@ -0,0 +1,11 @@
+import type { LucideIcon } from 'lucide-react';
+import { type ComponentPropsWithoutRef, type ReactNode } from 'react';
+export type EmptyStateVariant = 'default' | 'panel' | 'inline';
+export interface EmptyStateProps extends Omit<ComponentPropsWithoutRef<'div'>, 'title'> {
+    icon?: LucideIcon | ReactNode;
+    title: ReactNode;
+    description?: ReactNode;
+    action?: ReactNode;
+    variant?: EmptyStateVariant;
+}
+export declare function EmptyState({ icon, title, description, action, variant, className, ...props }: EmptyStateProps): import("react/jsx-runtime").JSX.Element;

package/dist/primitives/empty-state.js

@@ -0,0 +1,23 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { isValidElement } from 'react';
+import { cn } from '../lib/utils.js';
+function isIconComponent(icon) {
+    if (typeof icon === 'function')
+        return true;
+    if (typeof icon !== 'object')
+        return false;
+    return '$$typeof' in icon && !isValidElement(icon);
+}
+function renderIcon(icon) {
+    if (!icon)
+        return null;
+    if (isIconComponent(icon)) {
+        const Icon = icon;
+        return _jsx(Icon, { "data-testid": "empty-state-icon", className: "size-10", "aria-hidden": "true" });
+    }
+    return (_jsx("span", { "data-testid": "empty-state-icon", "aria-hidden": "true", className: "inline-flex", children: icon }));
+}
+export function EmptyState({ icon, title, description, action, variant = 'default', className, ...props }) {
+    return (_jsxs("div", { "data-slot": "empty-state", "data-variant": variant, className: cn('flex flex-col items-center justify-center text-center', variant === 'default' && 'px-6 py-16', variant === 'panel' && 'px-4 py-10', variant === 'inline' && 'px-3 py-6', className), ...props, children: [icon ? (_jsx("div", { "data-slot": "empty-state-icon", className: cn('mb-4 inline-flex items-center justify-center rounded-md text-muted-foreground', variant === 'inline' ? 'size-9' : 'size-12'), children: renderIcon(icon) })) : null, _jsx("h3", { "data-slot": "empty-state-title", className: cn('font-semibold text-foreground', variant === 'default' && 'text-lg', variant === 'panel' && 'text-base', variant === 'inline' && 'text-sm'), children: title }), description ? (_jsx("p", { "data-slot": "empty-state-description", className: cn('mt-1 max-w-sm text-muted-foreground', variant === 'inline' ? 'text-xs' : 'text-sm'), children: description })) : null, action ? (_jsx("div", { "data-slot": "empty-state-action", className: "mt-5", children: action })) : null] }));
+}

package/dist/primitives/filter-rail.d.ts

@@ -0,0 +1,20 @@
+import { type ComponentPropsWithoutRef, type ReactNode } from 'react';
+export interface FilterRailProps extends Omit<ComponentPropsWithoutRef<'aside'>, 'title'> {
+    title?: ReactNode;
+    description?: ReactNode;
+    search?: ReactNode;
+    actions?: ReactNode;
+    footer?: ReactNode;
+    children?: ReactNode;
+}
+export interface FilterRailGroupProps extends Omit<ComponentPropsWithoutRef<'fieldset'>, 'title'> {
+    title?: ReactNode;
+    description?: ReactNode;
+    children?: ReactNode;
+}
+declare function FilterRailGroup({ title, description, children, className, ...props }: FilterRailGroupProps): import("react/jsx-runtime").JSX.Element;
+declare function FilterRailRoot({ title, description, search, actions, footer, children, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, ...props }: FilterRailProps): import("react/jsx-runtime").JSX.Element;
+export declare const FilterRail: typeof FilterRailRoot & {
+    Group: typeof FilterRailGroup;
+};
+export {};

package/dist/primitives/filter-rail.js

@@ -0,0 +1,16 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from 'react';
+import { cn } from '../lib/utils.js';
+function FilterRailGroup({ title, description, children, className, ...props }) {
+    return (_jsxs("fieldset", { "data-slot": "filter-rail-group", className: cn('space-y-2 border-0 p-0', className), ...props, children: [title ? (_jsx("legend", { "data-slot": "filter-rail-group-title", className: "text-xs font-semibold text-foreground", children: title })) : null, description ? (_jsx("p", { "data-slot": "filter-rail-group-description", className: "text-xs text-muted-foreground", children: description })) : null, _jsx("div", { "data-slot": "filter-rail-group-content", className: "space-y-1.5", children: children })] }));
+}
+function FilterRailRoot({ title, description, search, actions, footer, children, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, ...props }) {
+    const titleId = useId();
+    const label = ariaLabel ?? (ariaLabelledBy ? undefined : typeof title === 'string' ? title : undefined);
+    const labelledBy = ariaLabelledBy ?? (label ? undefined : title ? titleId : undefined);
+    return (_jsxs("aside", { "data-slot": "filter-rail", "aria-label": label, "aria-labelledby": labelledBy, className: cn('flex min-h-0 w-full flex-col border-border bg-card text-card-foreground', className), ...props, children: [title || description || actions ? (_jsxs("div", { "data-slot": "filter-rail-header", className: "flex shrink-0 items-start justify-between gap-3 border-b border-border px-4 py-3", children: [_jsxs("div", { className: "min-w-0", children: [title ? (_jsx("h2", { id: titleId, "data-slot": "filter-rail-title", className: "text-sm font-semibold text-foreground", children: title })) : null, description ? (_jsx("p", { "data-slot": "filter-rail-description", className: "mt-0.5 text-xs text-muted-foreground", children: description })) : null] }), actions ? (_jsx("div", { "data-slot": "filter-rail-actions", className: "shrink-0", children: actions })) : null] })) : null, search ? (_jsx("div", { "data-slot": "filter-rail-search", className: "shrink-0 border-b border-border p-3", children: search })) : null, _jsx("div", { "data-slot": "filter-rail-content", className: "min-h-0 flex-1 space-y-5 overflow-y-auto p-4", children: children }), footer ? (_jsx("div", { "data-slot": "filter-rail-footer", className: "shrink-0 border-t border-border p-3", children: footer })) : null] }));
+}
+export const FilterRail = Object.assign(FilterRailRoot, {
+    Group: FilterRailGroup,
+});

package/dist/primitives/index.d.ts

@@ -0,0 +1,6 @@
+export type { EmptyStateProps, EmptyStateVariant } from './empty-state.js';
+export { EmptyState } from './empty-state.js';
+export type { FilterRailGroupProps, FilterRailProps } from './filter-rail.js';
+export { FilterRail } from './filter-rail.js';
+export type { SkeletonProps } from './skeleton.js';
+export { Skeleton } from './skeleton.js';

package/dist/primitives/index.js

@@ -0,0 +1,3 @@
+export { EmptyState } from './empty-state.js';
+export { FilterRail } from './filter-rail.js';
+export { Skeleton } from './skeleton.js';

package/dist/primitives/skeleton.d.ts

@@ -0,0 +1,3 @@
+import type { ComponentProps } from 'react';
+export type SkeletonProps = ComponentProps<'div'>;
+export declare function Skeleton({ className, 'aria-hidden': ariaHidden, ...props }: SkeletonProps): import("react/jsx-runtime").JSX.Element;

package/dist/primitives/skeleton.js

@@ -0,0 +1,6 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from '../lib/utils.js';
+export function Skeleton({ className, 'aria-hidden': ariaHidden = true, ...props }) {
+    return (_jsx("div", { "data-slot": "skeleton", "aria-hidden": ariaHidden, className: cn('animate-pulse rounded-md bg-muted', className), ...props }));
+}

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,11 +1,16 @@
-import type { ReactNode } from 'react';
-import type { AppShellContextRailConfig, AppShellIconRailConfig, AppShellRightPanelConfig, AppShellWorkspaceConfig } 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, workspace, 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, workspace, 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, workspace
     // 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, workspaceMenuItems: workspace?.menuItems, workspaceMenuFooter: workspace?.menuFooter })), _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, AppShellWorkspaceConfig } from './types.js';
+import type { AppShellAppTabsConfig, AppShellAuthBranding, AppShellAuthConfig, AppShellContextRailConfig, AppShellIconRailConfig, AppShellRightPanelConfig, AppShellWorkspaceConfig, ShellMainLayout } from './types.js';
 interface AppShellBaseProps {
     children: ReactNode;
     className?: string;
@@ -21,7 +21,31 @@ export type AppShellProps = AppShellBaseProps & ({
      * `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, workspace: props.workspace, 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, AppShellWorkspaceConfig, CommandDefinition, ContextItem, ContextModule, MobileBottomNavItem, PanelMode, PanelView, ShellLinkRenderArgs, ShellMainLayout, ShellRenderContext, ShellViewport, ThemeAdapter, WorkspaceDefinition, WorkspaceMenuItem, } 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,5 +1,5 @@
 import { type ReactNode } from 'react';
-import type { WorkspaceMenuItem } from './types.js';
+import type { AppShellAppTabsConfig, WorkspaceMenuItem } from './types.js';
 export interface WorkspaceSwitcherProps {
     /**
      * Configurable dropdown items. When provided, REPLACES the default
@@ -19,10 +19,18 @@ export interface WorkspaceSwitcherProps {
     workspaceMenuFooter?: ReactNode;
 }
 export declare function WorkspaceSwitcher({ menuItems, menuFooter, workspaceMenuFooter, }?: WorkspaceSwitcherProps): import("react/jsx-runtime").JSX.Element;
-export declare function AppTabs(): 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
@@ -31,4 +39,4 @@ export interface ShellHeaderProps {
     workspaceMenuItems?: WorkspaceMenuItem[];
     workspaceMenuFooter?: ReactNode;
 }
-export declare function ShellHeader({ globalActions, className, workspaceMenuItems, workspaceMenuFooter, }?: 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

@@ -19,7 +19,7 @@ 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]] }));
 }
-function renderConfiguredIcon(icon) {
+function renderShellIcon(icon) {
     if (icon == null)
         return null;
     if (isValidElement(icon))
@@ -49,7 +49,7 @@ function renderConfiguredItem(item) {
     // 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: [renderConfiguredIcon(item.icon), item.label] }));
+    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();
@@ -57,21 +57,33 @@ export function WorkspaceSwitcher({ menuItems, 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));
         }) }));
 }
 // ---------------------------------------------------------------------------
@@ -85,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, workspaceMenuItems, workspaceMenuFooter, } = {}) {
+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, { menuItems: workspaceMenuItems, menuFooter: workspaceMenuFooter }), _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;

package/dist/styles/theme.css

@@ -14,6 +14,9 @@
 @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,
@@ -22,6 +25,10 @@
   }
 }
 
+[data-vaul-drawer][data-state="open"] {
+  will-change: auto;
+}
+
 @theme inline {
   /* Color primitives — exposed as Tailwind color scales */
 

package/dist/styles/theme.test.ts

@@ -26,4 +26,16 @@ describe('theme.css', () => {
   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.5.0",
+  "version": "1.7.0",
   "description": "Shared Meda UI shell and runtime package.",
   "license": "Apache-2.0",
   "repository": {