@medalsocial/meda 2.7.1 → 2.8.0

package/README.md

@@ -107,6 +107,62 @@ Workspace shells also expose chrome-level composition slots:
 </AppShell>
 ```
 
+### Rail header (`headerLayout="rail"`)
+
+By default the desktop header is a `split` grid: the workspace switcher and `headerLeading` share
+the left region, and `headerCenter` owns the middle. Because the switcher is as wide as the
+workspace name, the leading region both moves per workspace and never gets more than about half
+the window. `headerLayout="rail"` swaps in a three-column grid instead — rail column · fill ·
+actions:
+
+```tsx
+<AppShell
+  variant="workspace"
+  headerLayout="rail"
+  iconRail={{ mainItems, labelVisibility: 'visible' }}
+  headerLeading={<SectionTabs />}          // owns the whole fill column
+  // Keep the panel views, drop the header's toggle:
+  rightPanel={{ panelViews, showToggle: false }}
+  globalActions={<NewButton />}
+>
+  {children}
+</AppShell>
+```
+
+- Column 1 is exactly the icon rail's width (`--shell-rail-label-width` when
+  `iconRail.labelVisibility` is `visible`, `--shell-rail-width` otherwise) and holds the workspace
+  switcher in its `tile` variant: the mark centred on the rail's axis with the workspace name
+  beneath it, in the icon-rail label type. The dropdown is the chip's, unchanged.
+- Column 2 is `headerLeading`, `min-w-0`, and gets every remaining pixel.
+- Column 3 is `globalActions` plus the panel toggle.
+- `headerCenter` is **ignored** in this layout — there is no centre column.
+
+The tile is metered to **44px** — a 28px mark, a 2px gap and ONE 14px label line, with no vertical
+padding — and carries `max-h-full` inside an `overflow-hidden` column. So it fits whatever you set
+`--shell-header-height` to, down to 52px (the web app runs 52px under its desktop window-tab
+strip), and can never paint past the header:
+
+```css
+/* a tighter header — the tile follows it */
+:root { --shell-header-height: 52px; }
+```
+
+Because the label is truncated to one line — and hidden entirely below 700px viewport height, the
+same tier at which every icon-rail label hides — the full workspace name is always recoverable two
+other ways: the tile's tooltip, and its accessible name (`"<workspace> workspace menu"`).
+
+Both layouts put `data-meda-shell-header` on the `<header>` (with
+`data-meda-header-layout="split" | "rail"`), so consumer CSS and tests can target the header
+without depending on its structure.
+
+### Mobile nav: light by app
+
+`mobileNav.activeTo` marks the exact address. Pass `mobileNav.activeId` (the active APP's id) as
+well and the dock lights whenever `item.id === activeId`, so it stays lit on every route inside
+that app rather than only on its first tab; the workspace sheet then opens with that row expanded
+and scrolled into view. `mobileNav.currentFirst` additionally hoists that row to the top of its
+group. Omit `activeId` and both surfaces keep comparing against `activeTo` as before.
+
 `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.
 
 `ContextRail` is usable for both navigation rails and custom rendered rails. Navigation rails show Meda's label header by default. Custom rendered rails hide the automatic visible header by default so consumers can render their own heading without duplication. Rail bodies scroll vertically by default; use `contextRail={{ header: "visible" }}` or `contextRail={{ scroll: "none" }}` when you need explicit control.

package/dist/lib/utils.d.ts

@@ -1,2 +1,2 @@
-import { type ClassValue } from 'clsx';
+import type { ClassValue } from 'clsx';
 export declare function cn(...inputs: ClassValue[]): string;

package/dist/lib/utils.js

@@ -1,5 +1,44 @@
-import { clsx } from 'clsx';
 import { twMerge } from 'tailwind-merge';
+/**
+ * Flatten one clsx-style class value.
+ *
+ * Deliberately inlined instead of calling `clsx`, so that `cn` — which nearly
+ * every component in this package calls — leaves no RUNTIME edge to the `clsx`
+ * module. `clsx` stays a dependency for its `ClassValue` type, which appears in
+ * this file's public signature; `import type` is erased at compile time.
+ *
+ * Why it is worth inlining twenty lines: `clsx` is also a dependency of
+ * `recharts`, so a bundler that groups the chart vendor graph into one chunk
+ * puts the single shared `clsx` module in THAT chunk. Every eager importer of
+ * `cn` then hard-depends on the whole chart bundle. Measured in the Medal web
+ * app (2026-09-06): the `/login` server closure reached a 392 kB
+ * `vendor-recharts` chunk through exactly one edge — the shell's `cn` — and
+ * removing this import dropped that closure from 4,758,902 to 4,357,355 bytes
+ * with the chart chunk no longer reachable at all.
+ *
+ * Behaviour is identical to `clsx`, pinned by the equivalence test in
+ * `test/unit/lib/utils.test.ts`.
+ */
+function toClassName(input) {
+    if (!input)
+        return '';
+    if (typeof input === 'string' || typeof input === 'number') {
+        return String(input);
+    }
+    if (Array.isArray(input)) {
+        return input.map(toClassName).filter(Boolean).join(' ');
+    }
+    if (typeof input === 'object') {
+        let className = '';
+        for (const key in input) {
+            if (input[key]) {
+                className = className ? `${className} ${key}` : key;
+            }
+        }
+        return className;
+    }
+    return '';
+}
 export function cn(...inputs) {
-    return twMerge(clsx(inputs));
+    return twMerge(toClassName(inputs));
 }

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

@@ -1,5 +1,5 @@
 import { type ReactNode } from 'react';
-import type { AppShellAppTabsConfig, AppShellContextRailConfig, AppShellIconRailConfig, AppShellMobileNavConfig, AppShellRightPanelConfig, AppShellWorkspaceConfig, ShellMainLayout } from './types.js';
+import type { AppShellAppTabsConfig, AppShellContextRailConfig, AppShellIconRailConfig, AppShellMobileNavConfig, AppShellRightPanelConfig, AppShellWorkspaceConfig, ShellHeaderLayout, ShellMainLayout } from './types.js';
 export interface AppShellWorkspaceProps {
     iconRail?: AppShellIconRailConfig;
     contextRail?: AppShellContextRailConfig;
@@ -9,6 +9,12 @@ export interface AppShellWorkspaceProps {
     globalActions?: ReactNode;
     headerCenter?: ReactNode;
     headerLeading?: ReactNode;
+    /**
+     * Desktop header grid — `split` (default, unchanged) or `rail`. See
+     * `ShellHeaderLayout`. In `rail` the header's first column is sized from
+     * `iconRail.labelVisibility` so it lines up with the rail below it.
+     */
+    headerLayout?: ShellHeaderLayout;
     banners?: ReactNode;
     mainLayout?: ShellMainLayout;
     mainClassName?: string;
@@ -27,4 +33,4 @@ export interface AppShellWorkspaceProps {
     mobileNav?: AppShellMobileNavConfig;
     children: ReactNode;
 }
-export declare function AppShellWorkspace({ iconRail, contextRail, rightPanel, workspace, appTabs, globalActions, headerCenter, headerLeading, banners, mainLayout, mainClassName, builtInCommandPalette, mobileNav, children, }: AppShellWorkspaceProps): import("react/jsx-runtime").JSX.Element;
+export declare function AppShellWorkspace({ iconRail, contextRail, rightPanel, workspace, appTabs, globalActions, headerCenter, headerLeading, headerLayout, banners, mainLayout, mainClassName, builtInCommandPalette, mobileNav, children, }: AppShellWorkspaceProps): import("react/jsx-runtime").JSX.Element;

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

@@ -17,11 +17,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, appTabs, globalActions, headerCenter, headerLeading, banners, mainLayout, mainClassName, builtInCommandPalette = true, mobileNav, children, }) {
+export function AppShellWorkspace({ iconRail, contextRail, rightPanel, workspace, appTabs, globalActions, headerCenter, headerLeading, headerLayout, banners, mainLayout, mainClassName, builtInCommandPalette = true, mobileNav, children, }) {
     const viewport = useShellViewport();
     const isMobile = viewport === 'mobile';
     const staticPanelViews = rightPanel?.panelViews ?? EMPTY_PANEL_VIEWS;
     const resolvedRightPanel = useResolvedPanelViews(staticPanelViews, rightPanel?.defaultView);
+    // The header toggle still requires at least one panel view — `showToggle`
+    // only lets a consumer KEEP the views and drop the control, never the
+    // reverse (a toggle with nothing behind it is a dead end).
+    const showPanelToggle = (rightPanel?.showToggle ?? true) && resolvedRightPanel.panelViews.length > 0;
     // Derive the bottom-nav items from the variant config so each button maps
     // to a drawer that actually has content. Menu is always available because
     // the mobile drawer now carries workspace actions and the theme toggle.
@@ -42,12 +46,12 @@ export function AppShellWorkspace({ iconRail, contextRail, rightPanel, workspace
     // <AppShell> wrapper already enforces h-screen for the workspace variant, so
     // nested viewport-height divs collapse cleanly — no double-scroll.
     const commandRegistry = useContext(CommandRegistryContext);
-    const shell = (_jsxs("div", { className: "flex h-svh flex-col", children: [isMobile ? (_jsx(MobileHeader, { globalActions: globalActions, headerCenter: headerCenter })) : (_jsx(ShellHeader, { globalActions: globalActions, headerCenter: headerCenter, headerLeading: headerLeading, appTabsRenderLink: appTabs?.renderLink, workspaceMenuItems: workspace?.menuItems, workspaceMenuFooter: workspace?.menuFooter, showPanelToggle: resolvedRightPanel.panelViews.length > 0, panelViews: resolvedRightPanel.panelViews })), 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, labelVisibility: iconRail.labelVisibility })), !isMobile && contextRail && (_jsx(ContextRail, { appId: contextRail.appId, module: contextRail.module, activeItemId: contextRail.activeItemId, renderLink: contextRail.renderLink, header: contextRail.header, scroll: contextRail.scroll })), _jsx(ShellMain, { layout: mainLayout ?? 'workspace', className: cn(mainClassName, 
+    const shell = (_jsxs("div", { className: "flex h-svh flex-col", children: [isMobile ? (_jsx(MobileHeader, { globalActions: globalActions, headerCenter: headerCenter })) : (_jsx(ShellHeader, { globalActions: globalActions, headerCenter: headerCenter, headerLeading: headerLeading, headerLayout: headerLayout, railLabelVisibility: iconRail?.labelVisibility, appTabsRenderLink: appTabs?.renderLink, workspaceMenuItems: workspace?.menuItems, workspaceMenuFooter: workspace?.menuFooter, showPanelToggle: showPanelToggle, panelViews: resolvedRightPanel.panelViews })), 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, labelVisibility: iconRail.labelVisibility })), !isMobile && contextRail && (_jsx(ContextRail, { appId: contextRail.appId, module: contextRail.module, activeItemId: contextRail.activeItemId, renderLink: contextRail.renderLink, header: contextRail.header, scroll: contextRail.scroll })), _jsx(ShellMain, { layout: mainLayout ?? 'workspace', className: cn(mainClassName, 
                         // Pad the scroll area so the dock never covers content. 64px is
                         // the bar-variant dock's intrinsic height (py-2 + 25px icon +
                         // label) — the previous 80px over-reserved 16px of permanently
                         // unreachable space at the bottom of every mobile surface.
-                        isMobile && mobileNav && 'pb-[calc(env(safe-area-inset-bottom)+64px)]'), children: children }), !isMobile && resolvedRightPanel.panelViews.length > 0 && (_jsx(RightPanel, { panelViews: staticPanelViews, defaultView: rightPanel?.defaultView }))] }), isMobile && mobileNav ? (_jsxs(_Fragment, { children: [_jsx(MobileDock, { items: mobileNav.dock, activeTo: mobileNav.activeTo, renderLink: mobileNav.renderLink, variant: mobileNav.variant }), _jsx(MobileWorkspaceSheet, { tree: mobileNav.tree, activeTo: mobileNav.activeTo, renderLink: mobileNav.renderLink, workspaceMenuItems: workspace?.menuItems, workspaceMenuFooter: workspace?.menuFooter })] })) : (_jsxs(_Fragment, { children: [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, moduleActiveItemId: contextRail?.activeItemId, moduleRenderLink: contextRail?.renderLink, moduleHeader: contextRail?.header, moduleScroll: contextRail?.scroll, sectionTabs: headerLeading, panelViews: resolvedRightPanel.panelViews, defaultView: resolvedRightPanel.defaultView }))] }))] }));
+                        isMobile && mobileNav && 'pb-[calc(env(safe-area-inset-bottom)+64px)]'), children: children }), !isMobile && resolvedRightPanel.panelViews.length > 0 && (_jsx(RightPanel, { panelViews: staticPanelViews, defaultView: rightPanel?.defaultView }))] }), isMobile && mobileNav ? (_jsxs(_Fragment, { children: [_jsx(MobileDock, { items: mobileNav.dock, activeTo: mobileNav.activeTo, activeId: mobileNav.activeId, renderLink: mobileNav.renderLink, variant: mobileNav.variant }), _jsx(MobileWorkspaceSheet, { tree: mobileNav.tree, activeTo: mobileNav.activeTo, activeId: mobileNav.activeId, currentFirst: mobileNav.currentFirst, renderLink: mobileNav.renderLink, workspaceMenuItems: workspace?.menuItems, workspaceMenuFooter: workspace?.menuFooter })] })) : (_jsxs(_Fragment, { children: [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, moduleActiveItemId: contextRail?.activeItemId, moduleRenderLink: contextRail?.renderLink, moduleHeader: contextRail?.header, moduleScroll: contextRail?.scroll, sectionTabs: headerLeading, panelViews: resolvedRightPanel.panelViews, defaultView: resolvedRightPanel.defaultView }))] }))] }));
     // Backwards-compatible default: meda provides the built-in CommandPalette
     // (and its CommandRegistryContext) so consumers calling useCommands()/
     // useCommandGroup() under the workspace shell keep working. When a registry is

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

@@ -1,5 +1,5 @@
 import type { ReactNode } from 'react';
-import type { AppShellAppTabsConfig, AppShellAuthBranding, AppShellAuthConfig, AppShellContextRailConfig, AppShellIconRailConfig, AppShellMobileNavConfig, AppShellRightPanelConfig, AppShellWorkspaceConfig, ShellMainLayout } from './types.js';
+import type { AppShellAppTabsConfig, AppShellAuthBranding, AppShellAuthConfig, AppShellContextRailConfig, AppShellIconRailConfig, AppShellMobileNavConfig, AppShellRightPanelConfig, AppShellWorkspaceConfig, ShellHeaderLayout, ShellMainLayout } from './types.js';
 interface AppShellBaseProps {
     children: ReactNode;
     className?: string;
@@ -29,14 +29,24 @@ export type AppShellProps = AppShellBaseProps & ({
     globalActions?: ReactNode;
     /**
      * Optional center-region header content. Replaces the default
-     * application tabs when provided.
+     * application tabs when provided. Ignored when
+     * `headerLayout="rail"` — that layout has no centre column.
      */
     headerCenter?: ReactNode;
     /**
      * Optional leading content rendered in the LEFT header region immediately
      * after the workspace switcher. On mobile, surfaced inside the menu drawer.
+     * Under `headerLayout="rail"` it owns the header's whole fill column.
      */
     headerLeading?: ReactNode;
+    /**
+     * Desktop header grid. `split` (the default) is the pre-2.8 layout,
+     * byte-for-byte unchanged. `rail` switches to
+     * `[rail column | fill | actions]`: the workspace switcher renders as a
+     * tile the width of the icon rail, and `headerLeading` gets every
+     * remaining pixel. See `ShellHeaderLayout`.
+     */
+    headerLayout?: ShellHeaderLayout;
     /**
      * Optional chrome-level content rendered below the header and above
      * the workspace rail row.

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, appTabs: props.appTabs, globalActions: props.globalActions, headerCenter: props.headerCenter, headerLeading: props.headerLeading, banners: props.banners, mainLayout: props.mainLayout, mainClassName: props.mainClassName, builtInCommandPalette: props.builtInCommandPalette, mobileNav: props.mobileNav, 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, headerLeading: props.headerLeading, headerLayout: props.headerLayout, banners: props.banners, mainLayout: props.mainLayout, mainClassName: props.mainClassName, builtInCommandPalette: props.builtInCommandPalette, mobileNav: props.mobileNav, children: props.children }));
         case 'chat':
             return wrapper(_jsx(AppShellChat, { globalActions: props.globalActions, children: props.children }));
     }

package/dist/shell/index.d.ts

@@ -20,12 +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, PanelToggleProps } from './shell-header.js';
+export type { AppTabsProps, PanelToggleProps, ShellHeaderProps, WorkspaceSwitcherProps, WorkspaceSwitcherVariant, } 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, AppShellAppTabsConfig, AppShellAuthBranding, AppShellAuthConfig, AppShellContextRailConfig, AppShellIconRailConfig, AppShellMobileNavConfig, AppShellRightPanelConfig, AppShellVariant, AppShellWorkspaceConfig, AppTabRenderLinkArgs, CommandDefinition, ContextItem, ContextModule, ContextRailHeader, ContextRailScroll, MobileBottomNavItem, MobileDockItem, MobileNavGroup, MobileNavItem, MobileNavLinkArgs, MobileNavTree, MobileNavView, PanelMode, PanelView, ShellLinkRenderArgs, ShellMainLayout, ShellRenderContext, ShellViewport, ThemeAdapter, WorkspaceDefinition, WorkspaceMenuItem, } from './types.js';
+export type { AppDefinition, AppShellAppTabsConfig, AppShellAuthBranding, AppShellAuthConfig, AppShellContextRailConfig, AppShellIconRailConfig, AppShellMobileNavConfig, AppShellRightPanelConfig, AppShellVariant, AppShellWorkspaceConfig, AppTabRenderLinkArgs, CommandDefinition, ContextItem, ContextModule, ContextRailHeader, ContextRailScroll, MobileBottomNavItem, MobileDockItem, MobileNavGroup, MobileNavItem, MobileNavLinkArgs, MobileNavTree, MobileNavView, PanelMode, PanelView, ShellHeaderLayout, ShellLinkRenderArgs, ShellMainLayout, ShellRenderContext, ShellViewport, ThemeAdapter, WorkspaceDefinition, WorkspaceMenuItem, } from './types.js';
 export { useShellViewport } from './use-shell-viewport.js';

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

@@ -5,6 +5,12 @@ export declare const WORKSPACE_SHEET_KEY = "workspace-sheet";
 export interface MobileDockProps {
     items: MobileDockItem[];
     activeTo?: string;
+    /**
+     * The active APP's id. When set, a slot is active iff `item.id === activeId`
+     * — so the dock stays lit everywhere inside that app, not only on the exact
+     * address in `activeTo`. Omit to keep the `to === activeTo` comparison.
+     */
+    activeId?: string;
     renderLink?: (args: MobileNavLinkArgs) => ReactNode;
     className?: string;
     /** `pill` (default) floating dock, or `bar` full-width labeled bottom bar. */
@@ -21,4 +27,4 @@ export interface MobileDockProps {
  *
  * Hidden on non-mobile viewports and when the right panel is fullscreen.
  */
-export declare function MobileDock({ items, activeTo, renderLink, className, variant, }: MobileDockProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function MobileDock({ items, activeTo, activeId, renderLink, className, variant, }: MobileDockProps): import("react/jsx-runtime").JSX.Element | null;

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

@@ -28,7 +28,7 @@ function renderIcon(icon, size) {
  *
  * Hidden on non-mobile viewports and when the right panel is fullscreen.
  */
-export function MobileDock({ items, activeTo, renderLink, className, variant = 'pill', }) {
+export function MobileDock({ items, activeTo, activeId, renderLink, className, variant = 'pill', }) {
     const ctx = useMedaShell();
     const band = useShellViewport();
     if (band !== 'mobile')
@@ -37,6 +37,9 @@ export function MobileDock({ items, activeTo, renderLink, className, variant = '
         return null;
     if (items.length === 0)
         return null;
+    // `activeId` wins when supplied; otherwise fall back to the exact-address
+    // comparison the dock has always used.
+    const isItemActive = (item) => activeId != null ? item.id === activeId : Boolean(item.to && activeTo && item.to === activeTo);
     const runAction = (item) => {
         if (item.action === 'open-sheet')
             ctx.mobileDrawer.setOpen(WORKSPACE_SHEET_KEY);
@@ -49,14 +52,17 @@ export function MobileDock({ items, activeTo, renderLink, className, variant = '
     if (variant === 'bar') {
         const renderBarSlot = (item) => {
             const label = typeof item.label === 'function' ? item.label() : item.label;
-            const isActive = Boolean(item.to && activeTo && item.to === activeTo);
+            const isActive = isItemActive(item);
             const isBrand = item.emphasis === 'brand';
-            const iconEl = isBrand ? (_jsx("span", { className: "flex size-8 items-center justify-center rounded-full bg-[#5B2D8C] text-white", children: renderIcon(item.icon, 20) })) : (renderIcon(item.icon, 25));
+            const iconEl = isBrand ? (_jsx("span", { className: cn('flex size-8 items-center justify-center rounded-full bg-[#5B2D8C] text-white', isActive && 'ring-2 ring-primary ring-offset-2 ring-offset-card'), children: renderIcon(item.icon, 20) })) : (renderIcon(item.icon, 25));
+            // Active wins over brand: a slot carrying `aria-current="page"` must
+            // have a visible treatment too. The label goes primary; the glyph in the
+            // disc stays white because the disc sets its own colour.
             let toneClass = 'text-muted-foreground hover:text-foreground';
-            if (isBrand)
-                toneClass = 'text-muted-foreground';
-            else if (isActive)
+            if (isActive)
                 toneClass = 'font-medium text-primary';
+            else if (isBrand)
+                toneClass = 'text-muted-foreground';
             const slotClass = cn('flex w-full flex-col items-center justify-center gap-1 py-2 text-[11px] leading-none transition-colors', toneClass);
             const children = (_jsxs(_Fragment, { children: [_jsxs("span", { className: "relative flex items-center justify-center", children: [iconEl, item.badge ? (_jsx("span", { className: "absolute -top-0.5 -right-1 size-2 rounded-full bg-primary ring-2 ring-card" })) : null] }), _jsx("span", { children: label })] }));
             if (item.to && !item.action) {
@@ -86,12 +92,18 @@ export function MobileDock({ items, activeTo, renderLink, className, variant = '
     const brandItems = items.filter((item) => item.emphasis === 'brand');
     const renderSlot = (item, size) => {
         const label = typeof item.label === 'function' ? item.label() : item.label;
-        const isActive = Boolean(item.to && activeTo && item.to === activeTo);
+        const isActive = isItemActive(item);
         const icon = renderIcon(item.icon, size);
         const badge = item.badge ? (_jsx("span", { className: "absolute top-0 right-0 size-2 rounded-full bg-primary ring-2 ring-card" })) : null;
         // Route link
         if (item.to && !item.action) {
-            const className = cn('relative flex items-center justify-center rounded-full p-1 transition-colors', isActive ? 'text-foreground' : 'text-muted-foreground hover:text-foreground');
+            const className = cn('relative flex items-center justify-center rounded-full p-1 transition-colors', 
+            // A brand slot is rendered inside a filled brand disc that already
+            // sets `text-white`; a colour class here would override it and paint
+            // the glyph muted-grey on purple. Inherit instead, and let the disc
+            // itself carry the active ring (see the brandItems map below).
+            item.emphasis === 'brand' && 'text-inherit', item.emphasis !== 'brand' &&
+                (isActive ? 'text-foreground' : 'text-muted-foreground hover:text-foreground'));
             const children = (_jsxs(_Fragment, { children: [icon, badge] }));
             if (renderLink) {
                 return renderLink({
@@ -110,8 +122,11 @@ export function MobileDock({ items, activeTo, renderLink, className, variant = '
             }
             return (_jsx("a", { href: item.to, className: className, "aria-label": label, "aria-current": isActive ? 'page' : undefined, children: children }));
         }
-        // Action slot
-        return (_jsxs("button", { type: "button", onClick: () => runAction(item), "aria-label": label, className: "relative flex items-center justify-center rounded-full p-1 text-muted-foreground transition-colors hover:text-foreground", children: [icon, badge] }));
+        // Action slot. Before `activeId` these never carried an active state, so
+        // the `activeTo` fallback deliberately does NOT light them — only an
+        // explicit `activeId` match does.
+        const actionActive = activeId != null && item.id === activeId;
+        return (_jsxs("button", { type: "button", onClick: () => runAction(item), "aria-label": label, className: cn('relative flex items-center justify-center rounded-full p-1 transition-colors', actionActive ? 'text-foreground' : 'text-muted-foreground hover:text-foreground'), children: [icon, badge] }));
     };
-    return (_jsxs("div", { "data-testid": "mobile-dock", className: cn('pointer-events-none absolute inset-x-0 bottom-0 z-30 flex items-center justify-center gap-2.5 pb-[calc(env(safe-area-inset-bottom)+12px)] pt-2', className), children: [_jsx("nav", { "aria-label": "Dock", className: "pointer-events-auto flex items-center gap-[18px] rounded-full border border-border bg-card px-4 py-2.5 shadow-[0_6px_20px_rgba(20,18,60,0.14)]", children: pillItems.map((item) => (_jsx("span", { className: "flex", children: renderSlot(item, 22) }, item.id))) }), brandItems.map((item) => (_jsx("span", { className: "pointer-events-auto flex size-11 items-center justify-center rounded-full bg-[#5B2D8C] text-white shadow-[0_6px_20px_rgba(91,45,140,0.35)]", children: renderSlot(item, 22) }, item.id)))] }));
+    return (_jsxs("div", { "data-testid": "mobile-dock", className: cn('pointer-events-none absolute inset-x-0 bottom-0 z-30 flex items-center justify-center gap-2.5 pb-[calc(env(safe-area-inset-bottom)+12px)] pt-2', className), children: [_jsx("nav", { "aria-label": "Dock", className: "pointer-events-auto flex items-center gap-[18px] rounded-full border border-border bg-card px-4 py-2.5 shadow-[0_6px_20px_rgba(20,18,60,0.14)]", children: pillItems.map((item) => (_jsx("span", { className: "flex", children: renderSlot(item, 22) }, item.id))) }), brandItems.map((item) => (_jsx("span", { className: cn('pointer-events-auto flex size-11 items-center justify-center rounded-full bg-[#5B2D8C] text-white shadow-[0_6px_20px_rgba(91,45,140,0.35)]', isItemActive(item) && 'ring-2 ring-primary ring-offset-2 ring-offset-background'), children: renderSlot(item, 22) }, item.id)))] }));
 }

package/dist/shell/internal/mobile-workspace-sheet.d.ts

@@ -3,6 +3,16 @@ import type { MobileNavLinkArgs, MobileNavTree, WorkspaceMenuItem } from '../typ
 export interface MobileWorkspaceSheetProps {
     tree: MobileNavTree;
     activeTo?: string;
+    /**
+     * The active APP's id — a row id in `tree`. When supplied it, not
+     * `activeTo`, decides which row the sheet opens on.
+     */
+    activeId?: string;
+    /**
+     * Render the current row first inside its group. Defaults to `false`, i.e.
+     * the tree's own order.
+     */
+    currentFirst?: boolean;
     renderLink?: (args: MobileNavLinkArgs) => ReactNode;
     workspaceMenuItems?: WorkspaceMenuItem[];
     workspaceMenuFooter?: ReactNode;
@@ -14,5 +24,9 @@ export interface MobileWorkspaceSheetProps {
  * preset views (accordion, one open at a time). Filters, layout, and saved
  * views deliberately stay on the page, not here. Opened from the dock's
  * workspace-selector slot; a workspace header on top surfaces the account menu.
+ *
+ * The sheet opens WHERE YOU ARE: the current row (see `activeId` / `activeTo`)
+ * is expanded and scrolled into view on every open, and the user can still
+ * collapse it.
  */
-export declare function MobileWorkspaceSheet({ tree, activeTo, renderLink, workspaceMenuItems, workspaceMenuFooter, }: MobileWorkspaceSheetProps): import("react/jsx-runtime").JSX.Element;
+export declare function MobileWorkspaceSheet({ tree, activeTo, activeId, currentFirst, renderLink, workspaceMenuItems, workspaceMenuFooter, }: MobileWorkspaceSheetProps): import("react/jsx-runtime").JSX.Element;

package/dist/shell/internal/mobile-workspace-sheet.js

@@ -1,7 +1,7 @@
 'use client';
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { ChevronDown, ChevronRight, ChevronUp, Monitor, Moon, Search, Sun, } from 'lucide-react';
-import { createElement, Fragment, isValidElement, useState } from 'react';
+import { createElement, Fragment, isValidElement, useEffect, useRef, useState, } 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';
@@ -18,6 +18,36 @@ function renderIcon(icon, size) {
     return null;
 }
 const rowClass = 'flex w-full items-center gap-3 rounded-[10px] px-2 py-2.5 text-left text-[13.5px] transition-colors hover:bg-accent';
+/** Every row in the tree, groups first then footer rows, in render order. */
+function allNavItems(tree) {
+    return [...tree.groups.flatMap((group) => group.items), ...(tree.footerItems ?? [])];
+}
+/**
+ * The row the user is currently "in".
+ *
+ * `activeId` is authoritative when supplied. Otherwise the row is derived from
+ * `activeTo`: an exact `to` match first, then the row that owns `activeTo`
+ * among its preset `views`.
+ */
+function resolveCurrentItem(tree, activeId, activeTo) {
+    const items = allNavItems(tree);
+    if (activeId != null)
+        return items.find((item) => item.id === activeId) ?? null;
+    if (activeTo == null)
+        return null;
+    return (items.find((item) => item.to === activeTo) ??
+        items.find((item) => (item.views ?? []).some((view) => view.to === activeTo)) ??
+        null);
+}
+/** Move `currentId` to the front of `items` (used by `currentFirst`). */
+function withCurrentFirst(items, currentId) {
+    if (currentId == null)
+        return items;
+    const index = items.findIndex((item) => item.id === currentId);
+    if (index <= 0)
+        return items;
+    return [items[index], ...items.slice(0, index), ...items.slice(index + 1)];
+}
 /**
  * The one mobile workspace sheet — a calm, scannable list of the whole nav
  * tree that replaces the four drawers. Modules are light group labels,
@@ -25,13 +55,50 @@ const rowClass = 'flex w-full items-center gap-3 rounded-[10px] px-2 py-2.5 text
  * preset views (accordion, one open at a time). Filters, layout, and saved
  * views deliberately stay on the page, not here. Opened from the dock's
  * workspace-selector slot; a workspace header on top surfaces the account menu.
+ *
+ * The sheet opens WHERE YOU ARE: the current row (see `activeId` / `activeTo`)
+ * is expanded and scrolled into view on every open, and the user can still
+ * collapse it.
  */
-export function MobileWorkspaceSheet({ tree, activeTo, renderLink, workspaceMenuItems, workspaceMenuFooter, }) {
+export function MobileWorkspaceSheet({ tree, activeTo, activeId, currentFirst = false, renderLink, workspaceMenuItems, workspaceMenuFooter, }) {
     const ctx = useMedaShell();
     const open = ctx.mobileDrawer.open === WORKSPACE_SHEET_KEY;
     const close = () => ctx.mobileDrawer.setOpen(null);
     const [expandedId, setExpandedId] = useState(null);
     const [accountOpen, setAccountOpen] = useState(false);
+    // Which row we have already scrolled to for the CURRENT open session, so a
+    // re-render does not keep yanking a sheet the user has scrolled by hand.
+    const scrolledToRef = useRef(null);
+    const currentItem = resolveCurrentItem(tree, activeId, activeTo);
+    const currentItemId = currentItem?.id ?? null;
+    const currentHasViews = (currentItem?.views ?? []).length > 0;
+    // Reset the accordion to the current row on every open. Primitive deps, so
+    // a re-render with the same current row does not fight a manual collapse.
+    useEffect(() => {
+        if (!open)
+            return;
+        setExpandedId(currentHasViews ? currentItemId : null);
+    }, [open, currentItemId, currentHasViews]);
+    useEffect(() => {
+        if (!open)
+            scrolledToRef.current = null;
+    }, [open]);
+    // Bring the current row into view as soon as it is in the DOM, so a long
+    // tree never opens scrolled away from where the user actually is. Done from
+    // the ref callback rather than an effect because the drawer portals its
+    // content in a later commit than the one that flips `open`.
+    const registerRow = (id) => (el) => {
+        if (el == null)
+            return;
+        if (!open || id !== currentItemId || scrolledToRef.current === id)
+            return;
+        scrolledToRef.current = id;
+        // `scrollIntoView` is absent in some non-browser DOM implementations.
+        if (typeof el.scrollIntoView === 'function') {
+            el.scrollIntoView({ block: 'center' });
+        }
+    };
+    const orderItems = (items) => currentFirst ? withCurrentFirst(items, currentItemId) : items;
     const navLink = (to, label, className, children, isActive) => {
         if (renderLink) {
             return renderLink({
@@ -72,7 +139,7 @@ export function MobileWorkspaceSheet({ tree, activeTo, renderLink, workspaceMenu
     return (_jsx(Drawer, { open: open, onOpenChange: (o) => !o && close(), direction: "bottom", children: _jsxs(DrawerContent, { showOverlay: true, className: "max-h-[86vh] rounded-t-[22px] p-0 data-[vaul-drawer-direction=bottom]:mt-0 data-[vaul-drawer-direction=bottom]:max-h-[86vh]", children: [_jsxs(DrawerHeader, { className: "sr-only", children: [_jsx(DrawerTitle, { children: "Navigation" }), _jsx(DrawerDescription, { children: "Jump to any area of the workspace." })] }), _jsxs("div", { className: "min-h-0 flex-1 overflow-y-auto px-3 pt-1 pb-[calc(env(safe-area-inset-bottom)+12px)]", children: [_jsxs("button", { type: "button", onClick: () => setAccountOpen((v) => !v), "aria-expanded": accountOpen, className: "flex w-full items-center gap-2.5 rounded-[10px] px-1.5 py-2 text-left hover:bg-accent", children: [_jsx("span", { className: "inline-flex size-7 shrink-0 items-center justify-center overflow-hidden rounded-lg bg-muted ring-1 ring-border/70", children: ctx.workspace.icon }), _jsx("span", { className: "min-w-0 flex-1 truncate font-medium text-sm", children: ctx.workspace.name }), accountOpen ? (_jsx(ChevronUp, { className: "size-4 text-muted-foreground", "aria-hidden": "true" })) : (_jsx(ChevronDown, { className: "size-4 text-muted-foreground", "aria-hidden": "true" }))] }), accountOpen ? (_jsxs("div", { className: "mb-1 flex flex-col gap-0.5 border-b pb-2", children: [workspaceMenuItems?.map((item) => (_jsxs(Fragment, { children: [_jsx(WorkspaceMenuRow, { item: item, onClose: close }), item.separatorAfter ? _jsx("div", { className: "my-1 h-px bg-border" }) : null] }, item.id))), _jsx(ThemeRow, {}), workspaceMenuFooter] })) : null, _jsxs("button", { type: "button", onClick: () => {
                                 close();
                                 ctx.commandPalette.setOpen(true);
-                            }, className: "my-2 flex w-full items-center gap-2 rounded-[10px] border px-3 py-2.5 text-left text-muted-foreground text-sm", children: [_jsx(Search, { className: "size-4", "aria-hidden": "true" }), "Search\u2026"] }), tree.groups.map((group) => (_jsxs("section", { "aria-label": group.label, children: [_jsx("p", { className: "px-2 pt-3 pb-1 text-[11px] text-muted-foreground", children: group.label }), _jsx("div", { className: "flex flex-col gap-0.5", children: group.items.map((item) => (_jsx(Fragment, { children: renderRow(item) }, item.id))) })] }, group.id))), tree.footerItems && tree.footerItems.length > 0 ? (_jsxs(_Fragment, { children: [_jsx("div", { className: "mx-2 my-2 h-px bg-border" }), _jsx("div", { className: "flex flex-col gap-0.5", children: tree.footerItems.map((item) => (_jsx(Fragment, { children: renderRow(item) }, item.id))) })] })) : null] })] }) }));
+                            }, className: "my-2 flex w-full items-center gap-2 rounded-[10px] border px-3 py-2.5 text-left text-muted-foreground text-sm", children: [_jsx(Search, { className: "size-4", "aria-hidden": "true" }), "Search\u2026"] }), tree.groups.map((group) => (_jsxs("section", { "aria-label": group.label, children: [_jsx("p", { className: "px-2 pt-3 pb-1 text-[11px] text-muted-foreground", children: group.label }), _jsx("div", { className: "flex flex-col gap-0.5", children: orderItems(group.items).map((item) => (_jsx("div", { ref: registerRow(item.id), "data-meda-nav-item": item.id, children: renderRow(item) }, item.id))) })] }, group.id))), tree.footerItems && tree.footerItems.length > 0 ? (_jsxs(_Fragment, { children: [_jsx("div", { className: "mx-2 my-2 h-px bg-border" }), _jsx("div", { className: "flex flex-col gap-0.5", children: orderItems(tree.footerItems).map((item) => (_jsx("div", { ref: registerRow(item.id), "data-meda-nav-item": item.id, children: renderRow(item) }, item.id))) })] })) : null] })] }) }));
 }
 function WorkspaceMenuRow({ item, onClose }) {
     const icon = renderIcon(item.icon, 16);

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

@@ -1,5 +1,15 @@
 import { type ReactNode } from 'react';
-import type { AppShellAppTabsConfig, PanelView, WorkspaceMenuItem } from './types.js';
+import type { IconRailLabelVisibility } from './icon-rail.js';
+import type { AppShellAppTabsConfig, PanelView, ShellHeaderLayout, WorkspaceMenuItem } from './types.js';
+/**
+ * WorkspaceSwitcher trigger shape.
+ *
+ * - `chip` (default, unchanged) — a horizontal button: mark · name · chevron.
+ * - `tile` — a full-width, rail-column button: the mark centred on the rail's
+ *   axis with the workspace name beneath it in the icon-rail label type. Used
+ *   by `<ShellHeader headerLayout="rail">`.
+ */
+export type WorkspaceSwitcherVariant = 'chip' | 'tile';
 export interface WorkspaceSwitcherProps {
     /**
      * Configurable dropdown items. When provided, REPLACES the default
@@ -17,8 +27,20 @@ export interface WorkspaceSwitcherProps {
     menuFooter?: ReactNode;
     /** @deprecated Use `menuFooter` instead. */
     workspaceMenuFooter?: ReactNode;
+    /**
+     * Trigger presentation. Defaults to `chip` — the 1.x/2.x horizontal button.
+     * The dropdown content and behaviour are identical in both variants.
+     */
+    variant?: WorkspaceSwitcherVariant;
+    /**
+     * `tile` variant only — render the workspace name under the mark. Pass
+     * `false` when the icon rail is icon-only (`labelVisibility: 'tooltip'`) so
+     * the tile matches the narrow rail. Ignored by the `chip` variant, whose
+     * name is never hidden. Defaults to `true`.
+     */
+    showLabel?: boolean;
 }
-export declare function WorkspaceSwitcher({ menuItems, menuFooter, workspaceMenuFooter, }?: WorkspaceSwitcherProps): import("react/jsx-runtime").JSX.Element;
+export declare function WorkspaceSwitcher({ menuItems, menuFooter, workspaceMenuFooter, variant, showLabel, }?: WorkspaceSwitcherProps): import("react/jsx-runtime").JSX.Element;
 export interface AppTabsProps extends AppShellAppTabsConfig {
 }
 export declare function AppTabs({ renderLink }?: AppTabsProps): import("react/jsx-runtime").JSX.Element;
@@ -31,7 +53,8 @@ export interface ShellHeaderProps {
     globalActions?: ReactNode;
     /**
      * Optional center-region content. Replaces the default application tabs when
-     * provided.
+     * provided. IGNORED when `headerLayout="rail"` — that layout has no centre
+     * column; put the content in `headerLeading` instead.
      */
     headerCenter?: ReactNode;
     /**
@@ -50,5 +73,19 @@ export interface ShellHeaderProps {
     showPanelToggle?: boolean;
     /** Panel views forwarded to the header `<PanelToggle>` dropdown. */
     panelViews?: PanelView[];
+    /**
+     * Header grid. `split` (default) is the pre-2.8 markup, unchanged. `rail`
+     * switches to `[rail column | fill | actions]` — see `ShellHeaderLayout`.
+     */
+    headerLayout?: ShellHeaderLayout;
+    /**
+     * The icon rail's label mode, so the `rail` layout can size its first column
+     * to the rail below it (`--shell-rail-label-width` when the rail shows
+     * labels, `--shell-rail-width` when it does not) and hide the tile's
+     * workspace name in icon-only mode. Mirror `iconRail.labelVisibility`.
+     * Defaults to `tooltip`, matching `IconRail`'s own default. Unused by the
+     * `split` layout.
+     */
+    railLabelVisibility?: IconRailLabelVisibility;
 }
-export declare function ShellHeader({ globalActions, headerCenter, headerLeading, appTabsRenderLink, className, workspaceMenuItems, workspaceMenuFooter, showPanelToggle, panelViews, }?: ShellHeaderProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function ShellHeader({ globalActions, headerCenter, headerLeading, appTabsRenderLink, className, workspaceMenuItems, workspaceMenuFooter, showPanelToggle, panelViews, headerLayout, railLabelVisibility, }?: ShellHeaderProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/shell/shell-header.js

@@ -3,6 +3,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import { ChevronDown, Monitor, Moon, PanelRight, Sun } from 'lucide-react';
 import { createElement, Fragment, isValidElement } from 'react';
 import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuTrigger, } from '../components/ui/dropdown-menu.js';
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, } from '../components/ui/tooltip.js';
 import { cn } from '../lib/utils.js';
 import { useMedaShell } from './shell-provider.js';
 import { useTheme } from './theme.js';
@@ -52,12 +53,27 @@ function renderConfiguredItem(item) {
     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] }));
 }
+/** Mark fallback for the tile variant when the workspace carries no icon. */
+function workspaceInitial(name) {
+    return name.trim().charAt(0).toUpperCase();
+}
 /* v8 ignore next — v8 phantom duplicate function record for WorkspaceSwitcher (default params) */
-export function WorkspaceSwitcher({ menuItems, menuFooter, workspaceMenuFooter, } = {}) {
+export function WorkspaceSwitcher({ menuItems, menuFooter, workspaceMenuFooter, variant = 'chip', showLabel = true, } = {}) {
     const { workspace, workspaces } = useMedaShell();
     const resolvedFooter = menuFooter ?? workspaceMenuFooter;
     const useConfiguredItems = Array.isArray(menuItems);
-    return (_jsxs(DropdownMenu, { children: [_jsxs(DropdownMenuTrigger, { render: _jsx("button", { type: "button", className: "flex min-w-0 items-center gap-2.5 rounded-lg px-2.5 py-2 text-sm font-semibold hover:bg-accent" }), children: [workspace.icon != null && (_jsx("span", { className: "inline-flex size-8 shrink-0 items-center justify-center overflow-hidden rounded-lg bg-muted text-foreground ring-1 ring-border/70", "aria-hidden": "true", children: workspace.icon })), _jsx("span", { className: "max-w-[13rem] truncate", children: workspace.name }), _jsx(ChevronDown, { size: 16, "aria-hidden": "true" })] }), _jsxs(DropdownMenuContent, { className: "min-w-[240px]", children: [!useConfiguredItems && workspaces.length > 0 && (_jsxs(_Fragment, { children: [workspaces.map((ws) => (_jsxs(DropdownMenuItem, { children: [ws.icon != null && (_jsx("span", { className: "inline-flex size-7 shrink-0 items-center justify-center overflow-hidden rounded-md bg-muted text-foreground ring-1 ring-border/70", "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] })] }));
+    // The tile sits in the header's rail column: the mark is the only
+    // flow-level child, so it stays centred on the rail's axis, and the chevron
+    // hangs off it absolutely rather than pushing it sideways.
+    //
+    // Its intrinsic height is deliberately bounded — mark 28 + gap 2 + one 14px
+    // label line = 44px, with NO vertical padding — so it fits inside
+    // `--shell-header-height` even when a consumer tightens that token (the web
+    // app runs a 52px header under its window-tab strip). `max-h-full` plus the
+    // rail column's `overflow-hidden` is the belt-and-braces guard.
+    const tileTrigger = (_jsxs(DropdownMenuTrigger, { "data-meda-workspace-switcher": "tile", render: _jsx("button", { type: "button", "aria-label": `${workspace.name} workspace menu`, className: "flex max-h-full w-full min-w-0 flex-col items-center justify-center gap-0.5 rounded-lg px-1 hover:bg-accent" }), children: [_jsxs("span", { className: "relative inline-flex shrink-0", "aria-hidden": "true", children: [_jsx("span", { className: "inline-flex size-7 items-center justify-center overflow-hidden rounded-lg bg-muted text-[13px] text-foreground font-semibold ring-1 ring-border/70", children: workspace.icon ?? workspaceInitial(workspace.name) }), _jsx(ChevronDown, { size: 11, "aria-hidden": "true", className: "pointer-events-none absolute -right-1.5 -bottom-1 rounded-full bg-background text-muted-foreground" })] }), showLabel && (_jsx("span", { "data-slot": "icon-rail-label", className: "max-w-full truncate text-center font-medium text-[11px] leading-[14px] [@media(max-height:700px)]:hidden", children: workspace.name }))] }));
+    const trigger = variant === 'tile' ? (_jsx(TooltipProvider, { children: _jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { render: _jsx("span", { className: "flex max-h-full w-full min-w-0" }), children: tileTrigger }), _jsx(TooltipContent, { side: "bottom", children: workspace.name })] }) })) : (_jsxs(DropdownMenuTrigger, { "data-meda-workspace-switcher": "chip", render: _jsx("button", { type: "button", className: "flex min-w-0 items-center gap-2.5 rounded-lg px-2.5 py-2 text-sm font-semibold hover:bg-accent" }), children: [workspace.icon != null && (_jsx("span", { className: "inline-flex size-8 shrink-0 items-center justify-center overflow-hidden rounded-lg bg-muted text-foreground ring-1 ring-border/70", "aria-hidden": "true", children: workspace.icon })), _jsx("span", { className: "max-w-[13rem] truncate", children: workspace.name }), _jsx(ChevronDown, { size: 16, "aria-hidden": "true" })] }));
+    return (_jsxs(DropdownMenu, { children: [trigger, _jsxs(DropdownMenuContent, { className: "min-w-[240px]", children: [!useConfiguredItems && workspaces.length > 0 && (_jsxs(_Fragment, { children: [workspaces.map((ws) => (_jsxs(DropdownMenuItem, { children: [ws.icon != null && (_jsx("span", { className: "inline-flex size-7 shrink-0 items-center justify-center overflow-hidden rounded-md bg-muted text-foreground ring-1 ring-border/70", "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] })] }));
 }
 /* v8 ignore next — v8 phantom duplicate function record for AppTabs (default params) */
 export function AppTabs({ renderLink } = {}) {
@@ -117,7 +133,7 @@ export function PanelToggle({ panelViews = [] } = {}) {
                     })] })] }));
 }
 /* v8 ignore next — v8 phantom duplicate function record for ShellHeader (default params) */
-export function ShellHeader({ globalActions, headerCenter, headerLeading, appTabsRenderLink, className, workspaceMenuItems, workspaceMenuFooter, showPanelToggle = true, panelViews = [], } = {}) {
+export function ShellHeader({ globalActions, headerCenter, headerLeading, appTabsRenderLink, className, workspaceMenuItems, workspaceMenuFooter, showPanelToggle = true, panelViews = [], headerLayout = 'split', railLabelVisibility = 'tooltip', } = {}) {
     const band = useShellViewport();
     if (band === 'mobile')
         return null;
@@ -125,8 +141,16 @@ export function ShellHeader({ globalActions, headerCenter, headerLeading, appTab
     // the WorkspaceSwitcher — separated by whitespace only (no divider line),
     // matching the design prototype's topbar spacing.
     const leadingRegion = headerLeading != null ? (_jsx("div", { className: "ml-2 flex min-w-0 items-center", children: headerLeading })) : null;
+    // Rail layout: column 1 is exactly the icon rail's width, so the switcher
+    // tile sits on the rail's axis and `headerLeading` starts precisely where
+    // the main region starts below. No left padding, `pr-4` on the right.
+    if (headerLayout === 'rail') {
+        return (_jsxs("header", { "data-meda-shell-header": "", "data-meda-header-layout": "rail", className: cn('grid h-[var(--shell-header-height)] w-full items-center bg-background pr-4', railLabelVisibility === 'visible'
+                ? 'grid-cols-[var(--shell-rail-label-width)_minmax(0,1fr)_auto]'
+                : 'grid-cols-[var(--shell-rail-width)_minmax(0,1fr)_auto]', className), children: [_jsx("div", { className: "flex h-full min-w-0 items-center justify-center overflow-hidden px-1", children: _jsx(WorkspaceSwitcher, { menuItems: workspaceMenuItems, menuFooter: workspaceMenuFooter, variant: "tile", showLabel: railLabelVisibility === 'visible' }) }), _jsx("div", { className: "flex min-w-0 items-center", children: headerLeading }), _jsxs("div", { className: "flex shrink-0 items-center gap-2 justify-self-end pl-4", children: [globalActions, showPanelToggle && _jsx(PanelToggle, { panelViews: panelViews })] })] }));
+    }
     if (headerCenter !== undefined) {
-        return (_jsxs("header", { className: cn('grid h-[var(--shell-header-height)] w-full grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)] items-center', 'gap-4 bg-background px-4', className), children: [_jsxs("div", { className: "flex min-w-0 items-center gap-2 justify-self-start", children: [_jsx(WorkspaceSwitcher, { menuItems: workspaceMenuItems, menuFooter: workspaceMenuFooter }), leadingRegion] }), _jsx("div", { className: "flex min-w-0 items-center justify-center justify-self-center", children: headerCenter }), _jsxs("div", { className: "flex min-w-0 items-center justify-end gap-2 justify-self-end", children: [globalActions, showPanelToggle && _jsx(PanelToggle, { panelViews: panelViews })] })] }));
+        return (_jsxs("header", { "data-meda-shell-header": "", "data-meda-header-layout": "split", className: cn('grid h-[var(--shell-header-height)] w-full grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)] items-center', 'gap-4 bg-background px-4', className), children: [_jsxs("div", { className: "flex min-w-0 items-center gap-2 justify-self-start", children: [_jsx(WorkspaceSwitcher, { menuItems: workspaceMenuItems, menuFooter: workspaceMenuFooter }), leadingRegion] }), _jsx("div", { className: "flex min-w-0 items-center justify-center justify-self-center", children: headerCenter }), _jsxs("div", { className: "flex min-w-0 items-center justify-end gap-2 justify-self-end", children: [globalActions, showPanelToggle && _jsx(PanelToggle, { panelViews: panelViews })] })] }));
     }
-    return (_jsxs("header", { className: cn('flex h-[var(--shell-header-height)] w-full items-center justify-between', 'gap-4 bg-background px-4', className), children: [_jsxs("div", { className: "flex min-w-0 shrink-0 items-center gap-2", children: [_jsx(WorkspaceSwitcher, { menuItems: workspaceMenuItems, menuFooter: workspaceMenuFooter }), leadingRegion] }), _jsx("div", { className: "flex min-w-0 flex-1 items-center", children: _jsx(AppTabs, { renderLink: appTabsRenderLink }) }), _jsxs("div", { className: "flex shrink-0 items-center gap-2", children: [globalActions, showPanelToggle && _jsx(PanelToggle, { panelViews: panelViews })] })] }));
+    return (_jsxs("header", { "data-meda-shell-header": "", "data-meda-header-layout": "split", className: cn('flex h-[var(--shell-header-height)] w-full items-center justify-between', 'gap-4 bg-background px-4', className), children: [_jsxs("div", { className: "flex min-w-0 shrink-0 items-center gap-2", children: [_jsx(WorkspaceSwitcher, { menuItems: workspaceMenuItems, menuFooter: workspaceMenuFooter }), leadingRegion] }), _jsx("div", { className: "flex min-w-0 flex-1 items-center", children: _jsx(AppTabs, { renderLink: appTabsRenderLink }) }), _jsxs("div", { className: "flex shrink-0 items-center gap-2", children: [globalActions, showPanelToggle && _jsx(PanelToggle, { panelViews: panelViews })] })] }));
 }

package/dist/shell/types.d.ts

@@ -49,6 +49,19 @@ export interface PanelView {
 }
 export type PanelMode = 'closed' | 'panel' | 'expanded' | 'fullscreen';
 export type ShellMainLayout = 'workspace' | 'centered' | 'fullbleed';
+/**
+ * Desktop header grid.
+ *
+ * - `split` (default, unchanged) — the workspace switcher and `headerLeading`
+ *   share the LEFT region; `headerCenter`, when supplied, owns the middle and
+ *   the leading region is capped at roughly half the window.
+ * - `rail` — a three-column grid `[rail column | fill | actions]`. Column 1 is
+ *   exactly as wide as the icon rail below it and holds the workspace switcher
+ *   in its `tile` variant; column 2 is `headerLeading` and gets ALL remaining
+ *   width; column 3 is `globalActions` (plus the panel toggle). `headerCenter`
+ *   is ignored in this layout.
+ */
+export type ShellHeaderLayout = 'split' | 'rail';
 export type ShellViewport = 'mobile' | 'tablet' | 'desktop' | 'wide' | 'ultrawide';
 export type ContextRailHeader = 'auto' | 'visible' | 'hidden';
 export type ContextRailScroll = 'auto' | 'none';
@@ -116,6 +129,23 @@ export interface AppShellMobileNavConfig {
     tree: MobileNavTree;
     /** The `to` of the currently-active row, for highlighting. */
     activeTo?: string;
+    /**
+     * The `id` of the currently-active APP (a `dock` item id and/or a
+     * `tree` row id). When set it wins over `activeTo` for:
+     *
+     * - the dock — a slot lights when `item.id === activeId`, so the dock stays
+     *   lit on every route inside that app instead of only on its first tab;
+     * - the workspace sheet — that row is the one expanded and scrolled into
+     *   view when the sheet opens.
+     *
+     * Omit it to keep the pre-2.8 behaviour (both derive from `activeTo`).
+     */
+    activeId?: string;
+    /**
+     * Render the current row (see `activeId` / `activeTo`) first inside its
+     * group in the workspace sheet. Defaults to `false` — the tree order.
+     */
+    currentFirst?: boolean;
     /** Render dock/sheet targets as router links (else plain `<a>`). */
     renderLink?: (args: MobileNavLinkArgs) => ReactNode;
     /**
@@ -183,6 +213,14 @@ export interface AppShellContextRailConfig {
 export interface AppShellRightPanelConfig {
     panelViews: PanelView[];
     defaultView?: string;
+    /**
+     * Whether the header renders its `PanelToggle`. Defaults to `true`, i.e. the
+     * toggle shows whenever at least one panel view is registered (the pre-2.8
+     * behaviour). Set `false` to keep the panel views — and every other way of
+     * opening them, such as `useMedaShell().panel.focus(id)` or a command — while
+     * dropping the header control.
+     */
+    showToggle?: boolean;
 }
 /**
  * A single configurable item in the WorkspaceSwitcher dropdown.

package/package.json

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

package/skills/shell/SKILL.md

@@ -21,11 +21,69 @@ The package exports a single `<AppShell>` component with a discriminated `varian
 | Variant | When to use | Key config |
 |---|---|---|
 | `'auth'` | Sign-in / sign-up / password reset / OAuth callbacks. Lets the form scroll past viewport (dense forms, high zoom). | `auth`, `branding`, optional `preview` (right-side art) + `actions` (top-right) |
-| `'workspace'` | Logged-in product shell. Has icon rail + context rail + header + main + optional right panel. | `iconRail`, `contextRail`, `rightPanel`, `workspace` (menu items override), `appTabs` (router integration), `headerCenter`, `banners`, `mainLayout`, `globalActions` |
+| `'workspace'` | Logged-in product shell. Has icon rail + context rail + header + main + optional right panel. | `iconRail`, `contextRail`, `rightPanel`, `workspace` (menu items override), `appTabs` (router integration), `headerCenter`, `headerLeading`, `headerLayout`, `banners`, `mainLayout`, `globalActions`, `mobileNav` |
 | `'chat'` | Chat-first surfaces (full-bleed messaging UI; no rails). | `globalActions` |
 
 `AppShellWorkspace.workspace.menuItems` REPLACES the default workspace dropdown ("Manage workspaces / Settings / Profile / Sign out") when provided. **The theme toggle is preserved automatically** — consumers do not have to re-implement theme cycling.
 
+## Header layout — `split` (default) vs `rail`
+
+`headerLayout` picks the desktop header grid. `split` is the historic layout and stays the default.
+
+| | `split` (default) | `rail` |
+|---|---|---|
+| Grid | `[1fr, auto, 1fr]` when `headerCenter` is set, else flex | `[rail width, minmax(0,1fr), auto]` |
+| Column 1 | workspace switcher (`chip`) + `headerLeading` | workspace switcher (`tile`), centred on the rail's axis |
+| Column 2 | `headerCenter` | `headerLeading`, `min-w-0`, **all** remaining width |
+| Column 3 | `globalActions` + `PanelToggle` | `globalActions` + `PanelToggle` |
+| `headerCenter` | rendered | **ignored** |
+| Padding | `px-4` | none on the left, `pr-4` |
+
+Reach for `rail` when the app's section tabs live in the header: in `split` they are capped at
+roughly half the window AND they shift horizontally with the workspace name, because the switcher
+sizes to that name. In `rail` the switcher is boxed into the rail column, so the tabs start at a
+fixed x — the same x the main region starts at below.
+
+Column 1's width comes from `iconRail.labelVisibility`: `--shell-rail-label-width` for `visible`,
+`--shell-rail-width` for the default `tooltip`. `AppShell` wires this for you; if you render
+`<ShellHeader>` by hand, mirror it into `railLabelVisibility` yourself or the header and the rail
+will disagree.
+
+**Target the header with `data-meda-shell-header`**, present on both layouts (alongside
+`data-meda-header-layout="split" | "rail"`). Do NOT reach for it structurally — a selector like
+`.flex.h-svh > header` breaks silently on any markup change.
+
+## WorkspaceSwitcher variants
+
+`variant="chip"` (default) is the horizontal mark · name · chevron button. `variant="tile"` is the
+rail-column shape the `rail` header uses: a full-width button with the mark on the rail axis, the
+name beneath it in `data-slot="icon-rail-label"` type, and a small chevron hung off the mark so
+the mark itself never leaves the axis. Its accessible name is `"<workspace name> workspace menu"`.
+Pass `showLabel={false}` in icon-only rail mode. The dropdown — items, theme toggle, footer,
+keyboard and dismiss behaviour — is identical in both.
+
+**The tile's height is a budget, not a suggestion.** It has to fit inside
+`--shell-header-height`, which consumers retune (the web app runs 52px under its desktop
+window-tab strip) and which is a fixed `height` — so anything taller overlaps the chrome around
+it rather than growing the header. The tile spends 28px on the mark + a 2px gap + ONE 14px label
+line = 44px, with **no vertical padding**, plus `max-h-full` and an `overflow-hidden` rail column.
+Change any of those and re-check the sum against 52px, not 64px.
+
+That one-line label truncates, and hides entirely below 700px viewport height like every other
+rail label. So the tile always renders a tooltip carrying the full workspace name — the same
+`Tooltip` primitive the icon rail uses, rendered unconditionally rather than on the rail's
+`!showLabel || isShortViewport` rule, because unlike a rail item the tile can also be
+visible-but-truncated. **Any new rail-width control whose label can truncate or hide needs the
+same tooltip:** an accessible name alone is not a substitute for a sighted user.
+
+## Keeping panel views without the header toggle
+
+`rightPanel.showToggle: false` drops the header's `PanelToggle` while the views stay registered and
+openable from anywhere else (`useMedaShell().panel.focus(id)`, a command, a route). It cannot do
+the reverse — a toggle with no views is still hidden, because it would be a dead end. Do NOT hide
+the toggle with consumer CSS such as `[data-meda-global-actions] + * { display: none }`; that is
+what this prop replaces.
+
 ## MedaShellProvider — the runtime root
 
 Wrap your app once with `<MedaShellProvider>` (typically in the root layout). Props:
@@ -129,6 +187,26 @@ Each hook auto-handles register-on-mount and unregister-on-unmount via `useEffec
 
 The default palette hotkey is `'mod+k'` — override via `MedaShellProvider.commandPaletteHotkey`. Hotkey matching is strict modifier-aware: `'mod+k'` does NOT fire on `mod+shift+k`. Use `'mod'` (resolves to ⌘ on macOS, Ctrl on Windows/Linux), not platform-specific keywords.
 
+## Mobile dock + workspace sheet — light by app, open where you are
+
+`mobileNav.activeTo` is the exact address of the active row. On its own it makes the dock go dark
+as soon as the user leaves an app's first tab, because a dock slot only lights on
+`item.to === activeTo`. Pass `mobileNav.activeId` — the active APP's id — alongside it:
+
+- **Dock:** a slot is active iff `item.id === activeId`. Action slots (`open-sheet`, `open-ai`,
+  `open-command-palette`) light only through `activeId`, never through the `activeTo` fallback.
+  An `emphasis: 'brand'` slot keeps its brand disc when active and gains a ring plus a primary
+  label — **active always outranks brand.** A slot that carries `aria-current="page"` must carry a
+  visible treatment too; a variant branch that reassigns the tone after the active check (the
+  `let toneClass` ladder in `mobile-dock.tsx`) is exactly how that regresses.
+- **Workspace sheet:** that row is expanded and scrolled into view on every open. The user can
+  still collapse it, and it re-expands on the next open. With no `activeId` the sheet derives the
+  row from `activeTo` — an exact `to` match first, then the row that owns `activeTo` among its
+  preset `views`.
+- **`mobileNav.currentFirst`:** renders that row first inside its group.
+
+Omit `activeId` and both surfaces behave exactly as they did before it existed.
+
 ## Right panel patterns
 
 Use a single `RightPanel` per shell. Don't build a parallel right-side surface — multiple right panels create state and dismiss-behavior conflicts. For a stacked detail experience, register multiple `PanelView`s with the existing `PanelViewsProvider` (`src/shell/panel-views-provider.tsx`).
@@ -149,3 +227,10 @@ Use a single `RightPanel` per shell. Don't build a parallel right-side surface
 | Multiple `RightPanel`s in one shell | Dismiss/state conflicts | Use `PanelViewsProvider` for stacked detail |
 | Forking `MedaShellProvider` per app | Loses cross-consumer parity | Compose around it; pass a custom `ThemeAdapter` for theme integration |
 | Hard-coded modifier in hotkey strings (`'cmd+k'`) | Breaks on Windows/Linux | Use `'mod+k'` — resolves per-platform |
+| Selecting the header structurally (`.flex.h-svh > header`) | Breaks silently on any markup change | Target `[data-meda-shell-header]` |
+| Hiding the panel toggle with consumer CSS | Depends on internal sibling order | `rightPanel={{ showToggle: false }}` |
+| Passing `headerCenter` together with `headerLayout="rail"` | The rail grid has no centre column; the node never renders | Put the content in `headerLeading` |
+| Lighting the mobile dock from `activeTo` alone | Goes dark on every route past an app's first tab | Also pass `mobileNav.activeId` |
+| A rail-width control whose label truncates or hides, with no tooltip | The name becomes unrecoverable for sighted users | Add the `Tooltip` the icon rail and switcher tile use |
+| Letting a variant branch (brand, emphasis) reassign the tone after the active check | `aria-current` with no visible state | Test the active state of every variant, not just the default one |
+| Adding vertical padding or a second label line to the switcher tile | Overflows a 52px `--shell-header-height` | Keep the tile inside its 44px budget |