---
name: shell
description: Use when scaffolding or modifying shell regions (icon rail, context rail, header, panel, command palette) in any app consuming `@medalsocial/meda` — Picasso, pilot-talk, NextMedal, apps/web. Required reading before adding a rail item, picking an AppShell variant (auth/workspace/chat), wiring command palette actions, configuring `MedaShellProvider`, or any `IconRail` change.
---

# Meda Shell

## When to load this skill

- Scaffolding a new shell — picking `AppShell` variant and configuring `MedaShellProvider`.
- Adding/removing/reordering icon rail items.
- Registering command palette actions.
- Wiring the workspace switcher or theme toggle in the header.
- Building or modifying the right panel.
- Touching anything under `src/shell/` in `@medalsocial/meda`.

## App shell variants

The package exports a single `<AppShell>` component with a discriminated `variant` prop. Pick exactly one variant per route group:

| 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` |
| `'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.

## MedaShellProvider — the runtime root

Wrap your app once with `<MedaShellProvider>` (typically in the root layout). Props:

```ts
interface MedaShellProviderProps {
  workspace: WorkspaceDefinition;                                 // required
  workspaces?: WorkspaceDefinition[];                             // for the switcher
  apps: AppDefinition[];                                          // required, non-empty (throws if empty)
  defaultActiveApp?: string;                                      // app id; defaults to apps[0]
  storage?: ShellStorageAdapter;                                  // defaults to localStorage adapter
  mobileBottomNav?: MobileBottomNavItem[];                        // mobile nav config
  commandPaletteHotkey?: string;                                  // e.g. 'mod+k' (default)
  themeAdapter?: 'default' | 'next-themes' | ThemeAdapter;        // pick per-framework
  children: ReactNode;
}
```

- **`themeAdapter: 'next-themes'`** for Next.js apps using `next-themes`. The adapter is lazy-loaded so default-adapter consumers don't pay for the bridge.
- **`themeAdapter: 'default'`** uses the built-in adapter (no external dep).
- Pass a custom `ThemeAdapter` object to integrate with any other theme system.
- `apps` MUST have at least one entry — the provider throws on empty array.

## Regions and component map

| Region | Component | Source |
|---|---|---|
| Icon rail | `IconRail` | `src/shell/icon-rail.tsx` |
| Context rail | `ContextRail` | `src/shell/context-rail.tsx` |
| Header | `ShellHeader` + `WorkspaceSwitcher` | `src/shell/shell-header.tsx` |
| Main | `ShellMain` | `src/shell/shell-main.tsx` |
| Right panel | `RightPanel` | `src/shell/right-panel.tsx` |
| Command palette | `CommandPalette` + `CommandRegistryContext` | `src/shell/command-palette.tsx` |

## The flat-rail rule (critical)

**The `IconRail` is a flat list of equal-weight icons. No section headers, no per-group labels, no in-line dividers between groups.**

`IconRail` accepts `mainItems`, `utilityItems`, and a `footer`. Use those three slots — do NOT inject section labels or dividers via `renderLink`, custom items, or a wrapping component.

**Why:** A "Testing" divider above Journeys was specced and built three different ways in 2026-05 (renderLink-injected, a real `IconRailDivider` API in meda, and a consumer `pnpm patch`). All three were abandoned — meda PR #161 and labs PR #162 were closed unmerged; labs PR #163 removed the work. The icon-button slot is 44×44; anything wider overflows and overlaps the next icon, and an icon-only ~60px rail cannot host a text label legibly. **Do not re-propose dividers, group headers, or "mark this surface as testing/ops" rail treatments.**

If a surface needs a type indicator, it lives in the surface itself (a banner, a header pill, a column-header badge) — never in the icon rail.

The existing `RailDivider` in `icon-rail.tsx` is a different pattern: a chevron toggle that **repositions** utility items between top and bottom of the rail. It is spatial, not a group label. Do not generalize it into section headers.

## IconRail item shape + active styling

```ts
interface IconRailItem {
  id: string;
  label: string;          // shown only in tooltip, never inline
  icon: LucideIcon;       // Lucide React only — no other icon libs
  to: string;
  badge?: ReactNode;      // small status indicator, top-right of the slot
}
```

Slot is `h-11 w-11 rounded-xl`. Active state uses `bg-primary/12 text-primary` (a 12%-alpha brand tint, NOT a solid brand fill — this is the legitimate `bg-primary` use case from the `brand` skill's note). Inactive uses `text-muted-foreground hover:bg-accent hover:text-foreground`. Don't override unless you're consciously diverging.

Pass `activeId` to mark which item is active; usually derived from your router's current path.

## `renderLink` — when to use it

`IconRail` and other rail components accept a `renderLink` prop that wraps the default `<a>`:

```tsx
renderLink={({ item, isActive, className, children, linkProps }) => (
  <NextLink href={item.to} className={className} {...linkProps}>
    {children}
  </NextLink>
)}
```

**Use it for:** integrating with Next.js `Link`, TanStack Router, React Router — anything that needs client-side navigation hooks.

**Do NOT use it for:** injecting dividers, headers, badges outside the slot, or any non-link content (see the flat-rail rule). The `className` parameter constrains your wrapper to the 44×44 slot — non-link content overflows.

## Command palette

`CommandPalette` is registry-driven. Components register their commands via the **public hooks** `useCommands` and `useCommandGroup` from `@medalsocial/meda/shell` — both must run inside a `<CommandPalette>` (they throw otherwise).

```tsx
import { useCommands, useCommandGroup } from '@medalsocial/meda/shell';

function MyFeature() {
  // Optional: register the group first so its label + ordering are known.
  useCommandGroup({ id: 'tools', label: 'Tools', priority: 50 });

  useCommands([
    { id: 'my.action', label: 'Run my action', group: 'tools', run: () => doIt() },
  ]);

  return null; // or your real UI
}
```

Each hook auto-handles register-on-mount and unregister-on-unmount via `useEffect`. Lower `priority` numbers render the group earlier (default 100).

`CommandRegistryContext` is internal — don't import or `useContext` it directly. The hooks are the supported API.

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.

## 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`).

## Drag patterns

`RailDropSlot`, `RailDropZones`, `DragModeBanner` are the canonical drag patterns. Don't add custom drag handlers to the rail — use these so the visual + a11y behavior matches across consumers.

## Anti-patterns

| Anti-pattern | Why it's wrong | Correct approach |
|---|---|---|
| Adding a section divider/header to `IconRail` | Three prior attempts abandoned; slot geometry can't host labels | Keep the rail flat; put type indicators in surfaces |
| Using `renderLink` for non-link content | Wraps inside the 44×44 slot — overflows/overlaps | Use `mainItems` / `utilityItems` / `footer` only |
| Picking `'workspace'` variant on a sign-in route | Renders rails on routes with no app context | Use `'auth'` variant; switch to `'workspace'` after auth |
| Re-implementing the theme toggle when overriding `workspace.menuItems` | The package inserts the toggle automatically | Just ship your menu items; toggle is added between items and footer |
| Custom icon library | Inconsistent sizing + brand tone | Lucide React only |
| 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 |