ModalDef[]          useModalResolver()           ModalRenderer
  (static config) ──► (RBAC filter pipeline) ──► (lazy load + render)
                           │
                     ModalManagerContext
                     (imperative open/close/confirm API)

interface ModalDef {
  id: string;                      // e.g. 'users-invite'
  component: () => Promise<any>;   // lazy import factory
  select: (mod: any) => ComponentType<ModalRendererProps<any>>;
  size?: ModalSize;                // 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full'
  permissions?: Permission[];      // OR gate
  roles?: SystemRole[];            // OR gate
  variant: ModalVariant;           // 'modal' | 'dialog' | 'confirm' | 'drawer'
  scope: ModalScope;               // 'global' | 'feature'
}

// src/features/users/modals.registry.ts
import { Permission } from '@/shared/auth/contracts';
import type { ModalDef } from '@/components/modals/modal.types';

export const userModals: ModalDef[] = [
  {
    id: 'users-invite',
    component: () => import('./components/InviteUserModal'),
    select: (mod) => mod.default,
    size: 'md',
    permissions: [Permission.INVITE_USER],
    variant: 'modal',
    scope: 'global',
  },
];

import { userModals } from '@/features/users/modals.registry';

export const MODAL_REGISTRY: ModalDef[] = [
  ...userModals,
  // ...add feature registries here
];

const { open, confirm } = useModalManager();

// Open a registered modal with typed payload
open('users-invite', { prefillEmail: 'john@example.com' });

// Imperative confirm (promise-based)
const ok = await confirm({
  title: 'Delete Project?',
  description: 'This cannot be undone.',
  confirmText: 'Delete',
  variant: 'destructive',
});

RBACProvider
  └─ ModalManagerProvider          ← imperative API
       └─ UpgradeModalProvider     ← thin wrapper, delegates to ModalManager
            └─ SearchProvider
                 └─ ...children
                      └─ ModalOrchestrator  ← resolver + renderer

  PageDef             usePageResolver()            PageShell
  (static config) ──► (RBAC filter pipeline) ──► (PageLayout + PageHeader + PageTabs)
                           │
                     RBAC context
                     Route params
                     Handler map

interface PageDef extends RouteConfig {
  id: string;
  title: string | ((params: Record<string, string | undefined>) => string);
  description?: string;
  icon?: ElementType;
  permissions?: Permission[];
  roles?: SystemRole[];
  featureFlag?: string;
  maxWidth?: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full';
  padding?: 'default' | 'compact' | 'none';
  actions?: PageActionDef[];
  tabs?: PageTabDef[];
  breadcrumbs?: BreadcrumbDef[];
}

// src/features/projects/pages.config.ts
export const projectsPageDef: PageDef = {
  id: 'projects',
  path: '/projects',
  title: 'Projects',
  icon: FolderKanban,
  maxWidth: 'full',
  tabs: [
    { value: 'overview', title: 'Overview', icon: LayoutDashboard },
    { value: 'portfolio', title: 'Portfolio', icon: PieChart,
      roles: [SystemRole.ADMIN, SystemRole.MANAGER] },
  ],
  actions: [
    { id: 'new-project', label: 'New Project', icon: Plus,
      handlerKey: 'handleNewProject',
      permissions: [Permission.MANAGE_PROJECTS] },
  ],
};

import { projectsPageDef } from './pages.config';
import { usePageResolver } from '@/routes/usePageResolver';
import { PageShell } from '@/components/layout/PageShell';

const ProjectsPage: FC = () => {
  const [activeTab, setActiveTab] = useState('overview');
  const handlers = useMemo(() => ({
    handleNewProject: () => { /* ... */ },
  }), []);

  const config = usePageResolver(projectsPageDef, { handlers });

  return (
    <PageShell config={config} activeTab={activeTab} onTabChange={setActiveTab}>
      {activeTab === 'overview' && <OverviewTab />}
      {activeTab === 'portfolio' && <PortfolioTab />}
    </PageShell>
  );
};

import { isModalVisible } from '@/components/modals/useModalResolver';

it('hides modal when user lacks permission', () => {
  const def = { permissions: [Permission.MANAGE_TEAM], roles: [] } as ModalDef;
  const ctx = { hasAnyPermission: () => false, hasRole: () => false };
  expect(isModalVisible(def, ctx)).toBe(false);
});

import { isTabVisible } from '@/routes/usePageResolver';

it('hides tab when role gate fails', () => {
  const tab = { roles: [SystemRole.ADMIN] } as PageTabDef;
  const ctx = { hasAnyPermission: () => true, hasRole: () => false };
  expect(isTabVisible(tab, ctx)).toBe(false);
});

// Type-safe — payload must match the registered type
const { openTyped } = useModalManager();
openTyped('users-invite', { onInvite: handleInvite }); // ✅ type-checked
openTyped('users-invite', { wrong: true });             // ❌ compile error

declare module '@/components/modals/modal.types' {
  interface ModalPayloadMap {
    'my-feature-modal': { entityId: string };
  }
}

{
  id: 'ai-grant-writer',
  featureFlag: 'VITE_ENABLE_AI_GRANT_WRITER',
  launchCheck: () => isLaunchPathEnabled('/ai-assistant'),
  // ...
}

tabs: [
  { value: 'overview', title: 'Overview' },
  { value: 'gantt', title: 'Gantt Chart', deviceTypes: ['desktop'] }, // hidden on mobile
],

// In route config
{
  path: '/compliance',
  element: (
    <ProtectedPageRoute pageDef={compliancePageDef}>
      <CompliancePage />
    </ProtectedPageRoute>
  ),
}

<ModalManagerProvider onModalOpen={(id, payload) => analytics.track('modal_opened', { id })}>
  {children}
</ModalManagerProvider>