@medalsocial/meda 0.3.0 → 1.1.0

package/dist/shell/motion.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Motion tokens (spec §14).
+ *
+ * Numeric values are unitless milliseconds — consumers append `ms`:
+ *   `transition-duration: ${motion.default}ms`
+ *
+ * Mirrored as CSS custom properties in `src/styles/tokens.css` for use
+ * via Tailwind arbitrary values (e.g. `duration-[var(--motion-default)]`).
+ *
+ * `spring` is JS-only (no CSS analogue); for Framer Motion / react-spring.
+ */
+export declare const motion: {
+    readonly fast: 140;
+    readonly default: 200;
+    readonly panel: 240;
+    readonly fullscreen: 280;
+    readonly ease: "cubic-bezier(0.2, 0.8, 0.2, 1)";
+    readonly spring: {
+        readonly stiffness: 420;
+        readonly damping: 34;
+    };
+};

package/dist/shell/motion.js

@@ -0,0 +1,19 @@
+/**
+ * Motion tokens (spec §14).
+ *
+ * Numeric values are unitless milliseconds — consumers append `ms`:
+ *   `transition-duration: ${motion.default}ms`
+ *
+ * Mirrored as CSS custom properties in `src/styles/tokens.css` for use
+ * via Tailwind arbitrary values (e.g. `duration-[var(--motion-default)]`).
+ *
+ * `spring` is JS-only (no CSS analogue); for Framer Motion / react-spring.
+ */
+export const motion = {
+    fast: 140,
+    default: 200,
+    panel: 240,
+    fullscreen: 280,
+    ease: 'cubic-bezier(0.2, 0.8, 0.2, 1)',
+    spring: { stiffness: 420, damping: 34 },
+};

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

@@ -0,0 +1,45 @@
+/**
+ * ResizableShell — shadcn-style wrapper around react-resizable-panels v4.
+ *
+ * API surface: Group → ResizableShell, Panel → ResizableShellPanel,
+ * Separator → ResizableHandle.
+ *
+ * Note: react-resizable-panels v4 renamed the exports:
+ *   PanelGroup → Group, PanelResizeHandle → Separator
+ * The v4 prop for layout direction is `orientation` (not `direction`).
+ *
+ * Persistence: left intentionally to consumers (ContextRail, RightPanel) because
+ * they own the (workspaceId, appId) key needed to key useShellLayoutState.
+ * ResizableShell is a layout primitive; don't couple it to the shell context hook.
+ */
+import type { ReactNode } from 'react';
+import type { OnPanelResize } from 'react-resizable-panels';
+export interface ResizableShellProps {
+    /** Default: 'horizontal'. */
+    orientation?: 'horizontal' | 'vertical';
+    className?: string;
+    children: ReactNode;
+}
+export declare function ResizableShell({ orientation, className, children, }: ResizableShellProps): import("react/jsx-runtime").JSX.Element;
+export interface ResizableShellPanelProps {
+    /** Percent (0–100). */
+    defaultSize?: number;
+    /** Minimum size in percent. Token-aligned default: none (set by consumer). */
+    minSize?: number;
+    /** Maximum size in percent. Token-aligned default: none (set by consumer). */
+    maxSize?: number;
+    id?: string;
+    collapsible?: boolean;
+    collapsedSize?: number;
+    /** Called on each resize. Uses the react-resizable-panels v4 signature. */
+    onResize?: OnPanelResize;
+    className?: string;
+    children: ReactNode;
+}
+export declare function ResizableShellPanel({ className, children, onResize, ...props }: ResizableShellPanelProps): import("react/jsx-runtime").JSX.Element;
+export interface ResizableHandleProps {
+    className?: string;
+    /** When true, renders a visible drag-indicator bar inside the handle. */
+    withHandle?: boolean;
+}
+export declare function ResizableHandle({ className, withHandle }: ResizableHandleProps): import("react/jsx-runtime").JSX.Element;

package/dist/shell/resizable-shell.js

@@ -0,0 +1,15 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Group, Panel, Separator } from 'react-resizable-panels';
+import { cn } from '../lib/utils.js';
+export function ResizableShell({ orientation = 'horizontal', className, children, }) {
+    return (_jsx(Group, { orientation: orientation, className: cn('flex h-full w-full', className), children: children }));
+}
+export function ResizableShellPanel({ className, children, onResize, ...props }) {
+    return (_jsx(Panel, { className: cn('h-full', className), onResize: onResize, ...props, children: children }));
+}
+export function ResizableHandle({ className, withHandle = false }) {
+    return (_jsx(Separator, { className: cn(
+        // 4px wide, transparent until hover/active — then ring-color line
+        'group relative w-1 shrink-0 cursor-col-resize transition-colors', 'bg-transparent hover:bg-ring data-[separator]:hover:bg-ring', 'focus-visible:bg-ring focus-visible:outline-none', className), children: withHandle && (_jsx("div", { "data-testid": "resize-handle-indicator", className: cn('absolute top-1/2 left-1/2 h-6 w-1 -translate-x-1/2 -translate-y-1/2', 'rounded-sm bg-border opacity-0 transition-opacity group-hover:opacity-100') })) }));
+}

package/dist/shell/right-panel.d.ts

@@ -0,0 +1,15 @@
+import type { PanelMode, PanelView } from './types.js';
+export interface RightPanelProps {
+    /** Views to render as tabs in the panel header. */
+    panelViews?: PanelView[];
+    /** Default active view id — set on mount when no activeView is set in context. */
+    defaultView?: string;
+    /**
+     * Which open-modes this consumer allows.
+     * Default is all three: ['panel', 'expanded', 'fullscreen'].
+     * If only ['panel'], the cycle button is hidden.
+     */
+    modes?: PanelMode[];
+    className?: string;
+}
+export declare function RightPanel({ panelViews, defaultView, modes, className, }: RightPanelProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/shell/right-panel.js

@@ -0,0 +1,126 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * RightPanel — spec §12
+ *
+ * Four-mode right panel: closed (0px), panel (resizable 300–520px),
+ * expanded (~60vw), fullscreen (100vw/100vh takeover).
+ *
+ * Mode state lives in MedaShellProvider (panel.mode / panel.setMode).
+ * Width is persisted per-(workspaceId, appId) via panel.width / panel.setWidth.
+ *
+ * Resize note (Pattern B):
+ * Uses its own pointer-event resize handle on the LEFT edge instead of
+ * wrapping in <ResizableShell>. Pattern A requires migrating <AppShellBody>
+ * to a PanelGroup layout.
+ * TODO(phase-15-refactor): swap to ResizableShell once AppShellBody is a PanelGroup
+ */
+import { Maximize2, Minimize2, X } from 'lucide-react';
+import { useEffect, useRef, useState } from 'react';
+import { cn } from '../lib/utils.js';
+import { useMedaShell } from './shell-provider.js';
+import { useShellViewport } from './use-shell-viewport.js';
+// ---------------------------------------------------------------------------
+// Constants — spec §12 dimensions
+// ---------------------------------------------------------------------------
+const MIN_WIDTH = 300;
+const MAX_WIDTH = 520;
+function ResizeHandle({ currentWidth, onResize, onCommit }) {
+    const startWidthRef = useRef(currentWidth);
+    const startXRef = useRef(0);
+    const draggingRef = useRef(false);
+    const handlePointerDown = (e) => {
+        try {
+            e.currentTarget.setPointerCapture(e.pointerId);
+        }
+        catch {
+            // ignore — drag still functions via draggingRef
+        }
+        startWidthRef.current = currentWidth;
+        startXRef.current = e.clientX;
+        draggingRef.current = true;
+    };
+    const handlePointerMove = (e) => {
+        if (!draggingRef.current)
+            return;
+        // Left edge: drag left (clientX decreasing) widens panel
+        const delta = startXRef.current - e.clientX;
+        const next = Math.min(MAX_WIDTH, Math.max(MIN_WIDTH, startWidthRef.current + delta));
+        onResize(next);
+    };
+    const handlePointerUp = (e) => {
+        if (!draggingRef.current)
+            return;
+        draggingRef.current = false;
+        const delta = startXRef.current - e.clientX;
+        const next = Math.min(MAX_WIDTH, Math.max(MIN_WIDTH, startWidthRef.current + delta));
+        onCommit(next);
+    };
+    return (_jsx("div", { role: "separator", "aria-orientation": "vertical", "aria-label": "Resize panel", "aria-valuenow": currentWidth, "aria-valuemin": MIN_WIDTH, "aria-valuemax": MAX_WIDTH, tabIndex: 0, className: cn('absolute top-0 left-0 h-full w-1 cursor-col-resize', 'opacity-0 transition-opacity hover:opacity-100 hover:bg-ring'), onPointerDown: handlePointerDown, onPointerMove: handlePointerMove, onPointerUp: handlePointerUp }));
+}
+// ---------------------------------------------------------------------------
+// RightPanel
+// ---------------------------------------------------------------------------
+export function RightPanel({ panelViews = [], defaultView, modes = ['panel', 'expanded', 'fullscreen'], className, }) {
+    const band = useShellViewport();
+    const ctx = useMedaShell();
+    const { mode, activeView, width, setMode, setActiveView, setWidth } = ctx.panel;
+    // Hydrate defaultView on mount if no active view set
+    // biome-ignore lint/correctness/useExhaustiveDependencies: intentional one-time mount effect
+    useEffect(() => {
+        if (!activeView && defaultView) {
+            setActiveView(defaultView);
+        }
+    }, []);
+    // Local display width tracks pointer-move updates live;
+    // setWidth (persist) is called on pointerUp.
+    const [displayWidth, setDisplayWidth] = useState(null);
+    const resolvedWidth = displayWidth ?? width;
+    // On mobile, the right panel renders as a drawer via <MobileDrawers > PanelsDrawer />.
+    // The desktop-shaped <RightPanel> hides; consumers must mount <MobileDrawers> to expose
+    // panel views on mobile.
+    if (band === 'mobile')
+        return null;
+    const renderCtx = {
+        workspaceId: ctx.workspace.id,
+        appId: ctx.activeAppId,
+    };
+    // Cycle through allowed open modes only (skip 'closed')
+    const cycleOpenMode = () => {
+        if (mode === 'closed')
+            return;
+        const openModes = modes.filter((m) => m !== 'closed');
+        const idx = openModes.indexOf(mode);
+        const next = openModes[(idx + 1) % openModes.length] ?? mode;
+        setMode(next);
+    };
+    // Mode → inline width style
+    const widthStyle = (() => {
+        switch (mode) {
+            case 'closed':
+                return { width: 0, pointerEvents: 'none' };
+            case 'panel':
+                return { width: `${resolvedWidth}px` };
+            case 'expanded':
+                return { width: '60vw' };
+            case 'fullscreen':
+                return { width: '100vw' };
+        }
+    })();
+    // Z-index escalation: fullscreen covers header + rails
+    const zIndexClass = mode === 'fullscreen' ? 'z-[var(--z-shell-fullscreen)]' : 'z-[var(--z-shell-panel)]';
+    const activePanelView = panelViews.find((v) => v.id === activeView);
+    const cycleAriaLabel = mode === 'panel' ? 'Expand panel' : mode === 'expanded' ? 'Maximize panel' : 'Restore panel';
+    const handleResize = (w) => setDisplayWidth(w);
+    const handleCommit = (w) => {
+        setDisplayWidth(null);
+        setWidth(w);
+    };
+    return (_jsx("aside", { "data-meda-panel-mode": mode, "aria-hidden": mode === 'closed' ? 'true' : undefined, className: cn('relative h-full shrink-0 overflow-hidden border-l border-shell-border bg-shell-panel', 'transition-[width] ease-[var(--motion-ease)] duration-[var(--motion-panel)]', mode === 'fullscreen' && 'fixed inset-0 h-screen w-screen border-none', zIndexClass, className), style: widthStyle, children: mode !== 'closed' && (_jsxs("div", { className: "flex h-full flex-col", children: [_jsxs("div", { className: "flex items-center justify-between border-b border-shell-border px-3 py-2", children: [_jsx("div", { className: "flex items-center gap-1", children: panelViews.map((view) => {
+                                const isActive = view.id === activeView;
+                                const Icon = view.icon;
+                                return (_jsxs("button", { type: "button", "aria-current": isActive ? 'true' : undefined, onClick: () => setActiveView(view.id), className: cn('inline-flex items-center gap-1.5 rounded-md px-2 py-1 text-xs font-medium transition-colors', isActive
+                                        ? 'bg-accent text-accent-foreground'
+                                        : 'text-muted-foreground hover:bg-accent hover:text-foreground'), children: [_jsx(Icon, { size: 14, "aria-hidden": "true" }), _jsx("span", { children: view.label })] }, view.id));
+                            }) }), _jsxs("div", { className: "flex items-center gap-1", children: [modes.length > 1 && (_jsx("button", { type: "button", "aria-label": cycleAriaLabel, onClick: cycleOpenMode, className: "inline-flex h-7 w-7 items-center justify-center rounded-md text-muted-foreground hover:bg-accent hover:text-foreground", children: mode === 'fullscreen' ? (_jsx(Minimize2, { size: 14, "aria-hidden": "true" })) : (_jsx(Maximize2, { size: 14, "aria-hidden": "true" })) })), _jsx("button", { type: "button", "aria-label": "Close panel", onClick: () => setMode('closed'), className: "inline-flex h-7 w-7 items-center justify-center rounded-md text-muted-foreground hover:bg-accent hover:text-foreground", children: _jsx(X, { size: 14, "aria-hidden": "true" }) })] })] }), _jsx("div", { className: "flex-1 overflow-y-auto", children: activePanelView != null ? (activePanelView.render(renderCtx)) : (_jsx("div", { className: "p-4 text-muted-foreground text-sm", children: "No panel view selected" })) }), mode === 'panel' && (_jsx(ResizeHandle, { currentWidth: resolvedWidth, onResize: handleResize, onCommit: handleCommit }))] })) }));
+}

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

@@ -1,11 +1,12 @@
 import type { ReactNode } from 'react';
-export declare function ShellHeaderFrame({ left, center, right, className, }: {
-    left: ReactNode;
-    center?: ReactNode;
-    right?: ReactNode;
+export interface WorkspaceSwitcherProps {
+    workspaceMenuFooter?: ReactNode;
+}
+export declare function WorkspaceSwitcher({ workspaceMenuFooter }?: WorkspaceSwitcherProps): import("react/jsx-runtime").JSX.Element;
+export declare function AppTabs(): import("react/jsx-runtime").JSX.Element;
+export declare function PanelToggle(): import("react/jsx-runtime").JSX.Element;
+export interface ShellHeaderProps {
+    globalActions?: ReactNode;
     className?: string;
-}): import("react/jsx-runtime").JSX.Element;
-export declare function ShellPanelToggle({ panelOpen, onToggle, }: {
-    panelOpen: boolean;
-    onToggle: () => void;
-}): import("react/jsx-runtime").JSX.Element;
+}
+export declare function ShellHeader({ globalActions, className }?: ShellHeaderProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/shell/shell-header.js

@@ -1,15 +1,58 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { PanelRightClose, PanelRightOpen } from 'lucide-react';
-export function ShellHeaderFrame({ left, center, right, className, }) {
-    return (_jsxs("header", { className: [
-            'relative z-[var(--z-sticky)] grid h-[var(--header-height)] w-full grid-cols-[auto_minmax(0,1fr)_auto] items-center gap-3 bg-[var(--header)] px-3 shadow-[var(--shadow-header)] sm:px-4',
-            className,
-        ]
-            .filter(Boolean)
-            .join(' '), children: [left, _jsx("div", { className: "min-w-0", children: center }), _jsx("div", { "data-testid": "shell-header-actions", className: "hidden items-center justify-end gap-2 md:flex", children: right })] }));
-}
-export function ShellPanelToggle({ panelOpen, onToggle, }) {
-    return (_jsx("button", { type: "button", "aria-label": panelOpen ? 'Close panel' : 'Open panel', onClick: onToggle, className: panelOpen
-            ? 'inline-flex h-9 items-center justify-center rounded-xl border border-[var(--primary)]/30 bg-[var(--primary)]/12 px-2.5 text-[var(--primary)] transition-[background-color,color,border-color] duration-200 hover:bg-[var(--primary)]/18'
-            : 'inline-flex h-9 items-center justify-center rounded-xl border border-[var(--border-subtle)] bg-[var(--surface-1)] px-2.5 text-[var(--muted-foreground)] transition-[background-color,color,border-color] duration-200 hover:bg-[var(--sidebar-accent)] hover:text-[var(--foreground)]', children: panelOpen ? _jsx(PanelRightClose, { size: 18 }) : _jsx(PanelRightOpen, { size: 18 }) }));
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { ChevronDown, Monitor, Moon, PanelRightClose, PanelRightOpen, Sun } from 'lucide-react';
+import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuTrigger, } from '../components/ui/dropdown-menu.js';
+import { cn } from '../lib/utils.js';
+import { useMedaShell } from './shell-provider.js';
+import { useTheme } from './theme.js';
+import { useShellViewport } from './use-shell-viewport.js';
+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 ThemeToggleMenuItem() {
+    const { theme, setTheme } = useTheme();
+    const Icon = THEME_ICON[theme];
+    return (_jsxs(DropdownMenuItem, { onClick: () => setTheme(NEXT_THEME[theme]), children: [_jsx(Icon, { size: 16, "aria-hidden": "true" }), THEME_LABEL[theme]] }));
+}
+export function WorkspaceSwitcher({ workspaceMenuFooter } = {}) {
+    const { workspace, workspaces } = useMedaShell();
+    return (_jsxs(DropdownMenu, { children: [_jsxs(DropdownMenuTrigger, { render: _jsx("button", { type: "button", className: "flex items-center gap-1.5 rounded-md px-2 py-1.5 text-sm font-medium hover:bg-accent" }), children: [workspace.icon != null && (_jsx("span", { className: "shrink-0", "aria-hidden": "true", children: workspace.icon })), _jsx("span", { children: workspace.name }), _jsx(ChevronDown, { size: 14, "aria-hidden": "true" })] }), _jsxs(DropdownMenuContent, { className: "min-w-[200px]", children: [workspaces.length > 0 && (_jsxs(_Fragment, { children: [workspaces.map((ws) => (_jsxs(DropdownMenuItem, { children: [ws.icon != null && _jsx("span", { "aria-hidden": "true", children: ws.icon }), ws.name] }, ws.id))), _jsx(DropdownMenuSeparator, {})] })), _jsx(DropdownMenuItem, { children: "Manage workspaces" }), _jsx(DropdownMenuSeparator, {}), _jsx(DropdownMenuItem, { children: "Settings" }), _jsx(DropdownMenuItem, { children: "Profile" }), _jsx(DropdownMenuSeparator, {}), _jsx(ThemeToggleMenuItem, {}), _jsx(DropdownMenuSeparator, {}), _jsx(DropdownMenuItem, { children: "Sign out" }), workspaceMenuFooter] })] }));
+}
+// ---------------------------------------------------------------------------
+// AppTabs
+// ---------------------------------------------------------------------------
+export function AppTabs() {
+    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));
+        }) }));
+}
+// ---------------------------------------------------------------------------
+// PanelToggle
+// ---------------------------------------------------------------------------
+export function PanelToggle() {
+    const { panel } = useMedaShell();
+    const isOpen = panel.mode !== 'closed';
+    const handleClick = () => {
+        panel.setMode(isOpen ? 'closed' : 'panel');
+    };
+    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 } = {}) {
+    const band = useShellViewport();
+    if (band === 'mobile')
+        return null;
+    return (_jsxs("header", { className: cn('flex h-[var(--shell-header-height)] w-full items-center justify-between', 'border-b border-border bg-background px-3', className), children: [_jsxs("div", { className: "flex items-center", children: [_jsx(WorkspaceSwitcher, {}), _jsx(AppTabs, {})] }), _jsxs("div", { className: "flex items-center gap-2", children: [globalActions, _jsx(PanelToggle, {})] })] }));
 }

package/dist/shell/shell-layout-utils.d.ts

@@ -1,5 +1,5 @@
-import type { ShellContentLayout, ShellViewportBand } from './types.js';
-export declare function getShellContentMaxWidth(layout: ShellContentLayout, viewportBand: ShellViewportBand): 1120 | 1280 | 1400 | 1440 | 1760 | 1920 | undefined;
+import type { ShellContentLayout, ShellViewportBand } from './extras/types.js';
+export declare function getShellContentMaxWidth(layout: ShellContentLayout, viewportBand: ShellViewportBand): 1440 | 1760 | 1920 | 1120 | 1280 | 1400 | undefined;
 export declare function getResolvedShellPanelWidth({ preferredWidth, viewportWidth, sidebarOpen, sidebarWidth, }: {
     preferredWidth: number;
     viewportWidth: number;

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

@@ -0,0 +1,8 @@
+import type { ReactNode } from 'react';
+import type { ShellMainLayout } from './types.js';
+export interface ShellMainProps {
+    layout?: ShellMainLayout;
+    className?: string;
+    children: ReactNode;
+}
+export declare function ShellMain({ layout, className, children }: ShellMainProps): import("react/jsx-runtime").JSX.Element;

package/dist/shell/shell-main.js

@@ -0,0 +1,11 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from '../lib/utils.js';
+const layoutClass = {
+    workspace: 'mx-auto w-full max-w-[1280px] px-4 py-6 sm:px-6 lg:px-8',
+    centered: 'mx-auto w-full max-w-2xl px-4 py-6 sm:px-6',
+    fullbleed: 'w-full',
+};
+export function ShellMain({ layout = 'workspace', className, children }) {
+    return (_jsx("main", { "data-meda-shell-main-layout": layout, className: cn('flex-1 min-w-0 overflow-y-auto bg-shell-main', '[content-visibility:auto]', layoutClass[layout], className), children: children }));
+}

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

@@ -0,0 +1,65 @@
+import { type ReactNode } from 'react';
+import { type ShellStorageAdapter } from './layout-state.js';
+import type { AppDefinition, MobileBottomNavItem, PanelMode, ThemeAdapter, WorkspaceDefinition } from './types.js';
+export type MobileDrawerKind = 'menu-drawer' | 'module-drawer' | 'panels-drawer' | 'ai-drawer' | (string & {}) | null;
+interface MedaShellContextValue {
+    workspace: WorkspaceDefinition;
+    workspaces: WorkspaceDefinition[];
+    apps: AppDefinition[];
+    activeAppId: string;
+    setActiveApp: (id: string) => void;
+    panel: {
+        mode: PanelMode;
+        activeView: string | null;
+        width: number;
+        setMode: (m: PanelMode) => void;
+        setActiveView: (v: string | null) => void;
+        setWidth: (w: number) => void;
+        /** Opens panel + switches to viewId in one call.
+         * Sugar for app keyboard shortcuts (e.g. Cmd+J → panel.focus('ai')).
+         * If already open in 'panel', 'expanded', or 'fullscreen', the existing
+         * mode is preserved — only flips closed → panel. */
+        focus: (viewId: string) => void;
+    };
+    contextRail: {
+        width: number;
+        collapsed: boolean;
+        setWidth: (w: number) => void;
+        setCollapsed: (c: boolean) => void;
+    };
+    mobileBottomNav: MobileBottomNavItem[];
+    mobileDrawer: {
+        open: MobileDrawerKind;
+        setOpen: (kind: MobileDrawerKind) => void;
+    };
+    commandPalette: {
+        open: boolean;
+        setOpen: (open: boolean) => void;
+    };
+    commandPaletteHotkey: string;
+    /** Selection bridge between main workspace and right panel views (spec §17). */
+    selection: unknown | null;
+    setSelection: (value: unknown | null) => void;
+}
+export declare function useMedaShell(): MedaShellContextValue;
+/**
+ * Selection bridge between main workspace and right panel views (spec §17).
+ *
+ * `T` is consumer-typed: setSelection writes whatever shape you pass; the
+ * matching getter narrows to `T | null`. The shell does not validate the
+ * shape — coordinate types between writer and readers in your app.
+ */
+export declare function useShellSelection<T>(): readonly [T | null, (value: T | null) => void];
+export interface MedaShellProviderProps {
+    workspace: WorkspaceDefinition;
+    workspaces?: WorkspaceDefinition[];
+    apps: AppDefinition[];
+    defaultActiveApp?: string;
+    storage?: ShellStorageAdapter;
+    mobileBottomNav?: MobileBottomNavItem[];
+    commandPaletteHotkey?: string;
+    themeAdapter?: 'default' | 'next-themes' | ThemeAdapter;
+    children: ReactNode;
+}
+export declare function MedaShellProvider(props: MedaShellProviderProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/shell/shell-provider.js

@@ -0,0 +1,152 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { LayoutGrid, Menu, PanelTop, Sparkles } from 'lucide-react';
+import { createContext, lazy, Suspense, useContext, useMemo, useState, } from 'react';
+import { createLocalStorageAdapter, useShellLayoutState, } from './layout-state.js';
+import { DefaultThemeProvider, ThemeCtx } from './theme.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.
+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 });
+}
+function pickTheme(themeAdapter, children) {
+    const adapter = themeAdapter ?? 'default';
+    if (adapter === 'default') {
+        return _jsx(DefaultThemeProvider, { children: children });
+    }
+    if (adapter === 'next-themes') {
+        return (_jsx(Suspense, { fallback: null, children: _jsx(NextThemesAdapter, { children: children }) }));
+    }
+    // Custom ThemeAdapter object
+    return _jsx(CustomThemeBridge, { adapter: adapter, children: children });
+}
+// ---------------------------------------------------------------------------
+// Default mobile bottom nav (canonical 4-item set, per spec §16)
+// Full icons ship here; the per-app customisation point is the mobileBottomNav
+// prop. For RC.1 the canonical drawer wire-up is a Phase 13 concern — only
+// the shape is locked here.
+// ---------------------------------------------------------------------------
+const defaultMobileBottomNav = [
+    { id: 'menu', label: 'Menu', icon: Menu, opens: 'menu-drawer' },
+    { id: 'module', label: 'Module', icon: LayoutGrid, opens: 'module-drawer' },
+    { id: 'panels', label: 'Panels', icon: PanelTop, opens: 'panels-drawer' },
+    { id: 'ai', label: 'AI', icon: Sparkles, opens: 'ai-drawer' },
+];
+const Ctx = createContext(null);
+export function useMedaShell() {
+    const v = useContext(Ctx);
+    if (!v)
+        throw new Error('useMedaShell must be used inside <MedaShellProvider>');
+    return v;
+}
+/**
+ * Selection bridge between main workspace and right panel views (spec §17).
+ *
+ * `T` is consumer-typed: setSelection writes whatever shape you pass; the
+ * matching getter narrows to `T | null`. The shell does not validate the
+ * shape — coordinate types between writer and readers in your app.
+ */
+export function useShellSelection() {
+    const ctx = useMedaShell();
+    return [ctx.selection, ctx.setSelection];
+}
+// ---------------------------------------------------------------------------
+// Provider implementation
+// ---------------------------------------------------------------------------
+export function MedaShellProvider(props) {
+    // Guard: apps array must not be empty
+    if (props.apps.length === 0) {
+        throw new Error('MedaShellProvider: apps must contain at least one AppDefinition');
+    }
+    // Stable storage reference — prevents useShellLayoutState's hydration
+    // effect from looping when an inline adapter would change identity each render.
+    const storage = useMemo(() => props.storage ?? createLocalStorageAdapter(), [props.storage]);
+    const [activeAppId, setActiveApp] = useState(props.defaultActiveApp ?? props.apps[0]?.id ?? '');
+    const [selection, setSelection] = useState(null);
+    const [mobileDrawerOpen, setMobileDrawerOpen] = useState(null);
+    const mobileDrawer = useMemo(() => ({
+        open: mobileDrawerOpen,
+        setOpen: setMobileDrawerOpen,
+    }), [mobileDrawerOpen]);
+    const [commandPaletteOpen, setCommandPaletteOpen] = useState(false);
+    const commandPalette = useMemo(() => ({
+        open: commandPaletteOpen,
+        setOpen: setCommandPaletteOpen,
+    }), [commandPaletteOpen]);
+    const [layoutState, setLayoutState] = useShellLayoutState({
+        workspaceId: props.workspace.id,
+        appId: activeAppId,
+        storage,
+    });
+    const panel = useMemo(() => ({
+        mode: layoutState.rightPanel.mode,
+        activeView: layoutState.rightPanel.activeView,
+        width: layoutState.rightPanel.width,
+        setMode: (mode) => setLayoutState((prev) => ({
+            ...prev,
+            rightPanel: { ...prev.rightPanel, mode },
+        })),
+        setActiveView: (activeView) => setLayoutState((prev) => ({
+            ...prev,
+            rightPanel: { ...prev.rightPanel, activeView },
+        })),
+        setWidth: (width) => setLayoutState((prev) => ({
+            ...prev,
+            rightPanel: { ...prev.rightPanel, width },
+        })),
+        // focus(viewId) — opens panel + switches to view in one call.
+        // Only flips closed → panel; preserves expanded / fullscreen modes.
+        focus: (viewId) => setLayoutState((prev) => {
+            const nextMode = prev.rightPanel.mode === 'closed' ? 'panel' : prev.rightPanel.mode;
+            return {
+                ...prev,
+                rightPanel: { ...prev.rightPanel, mode: nextMode, activeView: viewId },
+            };
+        }),
+    }), [layoutState, setLayoutState]);
+    const contextRail = useMemo(() => ({
+        width: layoutState.contextRail.width,
+        collapsed: layoutState.contextRail.collapsed,
+        setWidth: (width) => setLayoutState((prev) => ({
+            ...prev,
+            contextRail: { ...prev.contextRail, width },
+        })),
+        setCollapsed: (collapsed) => setLayoutState((prev) => ({
+            ...prev,
+            contextRail: { ...prev.contextRail, collapsed },
+        })),
+    }), [layoutState, setLayoutState]);
+    const value = useMemo(() => ({
+        workspace: props.workspace,
+        workspaces: props.workspaces ?? [props.workspace],
+        apps: props.apps,
+        activeAppId,
+        setActiveApp,
+        panel,
+        contextRail,
+        mobileBottomNav: props.mobileBottomNav ?? defaultMobileBottomNav,
+        mobileDrawer,
+        commandPalette,
+        commandPaletteHotkey: props.commandPaletteHotkey ?? 'mod+k',
+        selection,
+        setSelection,
+    }), [
+        props.workspace,
+        props.workspaces,
+        props.apps,
+        activeAppId,
+        panel,
+        contextRail,
+        props.mobileBottomNav,
+        mobileDrawer,
+        commandPalette,
+        props.commandPaletteHotkey,
+        selection,
+    ]);
+    return _jsx(Ctx.Provider, { value: value, children: pickTheme(props.themeAdapter, props.children) });
+}

package/dist/shell/shell-route-utils.d.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from 'react';
-import type { ShellContentLayout, ShellTab } from './types.js';
+import type { ShellContentLayout, ShellTab } from './extras/types.js';
 interface ShellRouteMatchLike {
     handle?: unknown;
     params?: Record<string, string | undefined>;

package/dist/shell/{navigation-area.d.ts → theme-next-themes.d.ts}

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

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

@@ -0,0 +1,24 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { ThemeProvider as NextThemesProvider, useTheme as useNextTheme } from 'next-themes';
+import { ThemeCtx } from './theme.js';
+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 _jsx(ThemeCtx.Provider, { value: value, children: children });
+}
+export function NextThemesAdapter({ children }) {
+    return (_jsx(NextThemesProvider, { attribute: "class", enableSystem: true, defaultTheme: "system", children: _jsx(NextThemesBridge, { children: children }) }));
+}