@xeplr/ui-account 1.0.9 → 1.0.10

package/README.md

@@ -54,7 +54,7 @@ createRoot(document.getElementById('root')).render(
 
 ```css
 .app { min-height: 100vh; background: var(--xeplr-bg-primary); color: var(--xeplr-text-primary); }
-.app-main { padding-left: 60px; }            /* room for the collapsed rail */
+.app-main { padding-left: 48px; }            /* room for the collapsed rail */
 ```
 
 Link to auth pages with `authPath(key)` rather than a literal URL: `<Link to={authPath('profile')}>`.
@@ -63,7 +63,7 @@ Link to auth pages with `authPath(key)` rather than a literal URL: `<Link to={au
 
 - **`<ThemeProvider>` is required.** `theme.css` defines every `--xeplr-*` variable only inside the `.xeplr-theme-dark`, `-light`, `-medium` and `-bright` classes — there is no `:root` fallback. Without a theme class above them, every screen renders unstyled and nothing reports an error. `ThemeProvider` renders that class on a wrapper `<div>` (you may instead put the class on a container yourself).
 - **Set the page background on a container inside the theme wrapper, not on `body`.** `body` is outside the wrapper `<div>`, so `var(--xeplr-bg-primary)` there resolves to nothing.
-- **Reserve room for the rail.** The drawer is `position: fixed` at the top-left, full height, `z-index: 500`, 60px wide when collapsed. It never pushes content, so the app must leave that space (e.g. `padding-left: 60px`). Expanded, it overlays the page. A full-screen modal must stack above 500 or the rail shows through it.
+- **Reserve room for the rail.** The drawer is `position: fixed` at the top-left, full height, `z-index: 500`, 48px wide when collapsed (compact, like VS Code's activity bar). It never pushes content, so the app must leave that space (e.g. `padding-left: 48px`). Expanded, it overlays the page. A full-screen modal must stack above 500 or the rail shows through it.
 - **The rail only renders when the person may see at least one drawer item.** If none of `drawerItems` survives the access filter, `NavPage` renders the top bar instead (in normal flow, not fixed). If that can happen in your app, decide the padding with `labelMenuItems(drawerItems, access).length > 0`.
 
 ### Themes
@@ -103,7 +103,8 @@ authRoutes({
   register: false,                                     // drop the route
   profile: <MyProfile />,                              // full replace (same as { element: <MyProfile /> })
   userRoles: { element: <ProtectedRoute roles={['Super Admin']}><UserRolesPage /></ProtectedRoute> },
-  forgotPassword: { path: '/forgot', design: MyForgot } // mount at another path
+  forgotPassword: { path: '/forgot', design: MyForgot }, // mount at another path
+  accessMatrix: { props: { loadWorkspaces } }          // props for the page's controller
 }, { layout: <Shell />, loginPath: '/auth/login', raw: true })
 ```
 
@@ -201,8 +202,8 @@ Every reply must be JSON: an empty body (a `204`, say) throws too. Each failure
 ```jsx
 const navigate = useNavigate()
 const drawerItems = [
-  { key: 'Tasks',   icon: <TaskIcon />,   clickHandler: () => navigate('/tasks') },
-  { key: 'Reports', icon: <ReportIcon />, clickHandler: () => navigate('/reports'), group: 'Insights', badge: 3 },
+  { key: 'Tasks',   icon: <TaskIcon />,   path: '/tasks',   clickHandler: () => navigate('/tasks') },
+  { key: 'Reports', icon: <ReportIcon />, path: '/reports', clickHandler: () => navigate('/reports'), group: 'Insights', badge: 3 },
 ]
 const settingsOverrides = [{ key: 'Admin', path: '/admin' }]
 ```
@@ -210,6 +211,8 @@ const settingsOverrides = [{ key: 'Admin', path: '/admin' }]
 - **An unknown key is dropped silently.** A key that is not in `access.menus` — not seeded, not granted to this role, hidden, or misspelled — simply does not render, with no warning. Seed the menu row in `@xeplr/auth` and grant it before looking anywhere else.
 - **Give every drawer item an `icon`.** The collapsed rail shows icons only; an item without one is an empty button there.
 - `group` is a section header, written in code and shown as is. Ungrouped items come first.
+- `path` marks the item as **the current page** (accent icon on a tinted tile, `aria-current="page"`) when the URL is that path or under it — `/tasks` stays marked on `/tasks/12`. `active: true|false` overrides it. An item with neither is never marked. Give every item one: a rail that does not say where you are makes every click feel unconfirmed.
+- Every rail control (links, logo, bell, settings) is a 36px tile with a hover, a visible press (`:active` shrink), and a keyboard-only focus ring; settings stays pressed while its menu is open.
 - `badge` (number or short string) shows as a pill when expanded and a dot on the icon when collapsed; `0`, `''` and `null` show nothing.
 
 `labelMenuItems(catalog, access)` is the pure function behind this — it returns the items the person may see, each with `key` and `label`, in the server's order.
@@ -240,7 +243,7 @@ Exactly one of two things renders: with at least one visible drawer item, the **
 
 | prop | applies to | meaning |
 |---|---|---|
-| `drawerItems` | drawer | `[{ key, icon, clickHandler, group?, badge? }]` — a non-empty visible list turns the drawer on |
+| `drawerItems` | drawer | `[{ key, icon, clickHandler, path?, active?, group?, badge? }]` — a non-empty visible list turns the drawer on |
 | `settingsOverrides` | both | `[{ key, path }]`, shown above the built-in items in the settings menu |
 | `notifications` | both | `{ count, onClick }` — the bell shows only when this is given **and** `access.menus` contains `Notifications`; a count above 9 shows `9+` |
 | `logo` | both | image URL: the top bar's logo, the collapsed rail's toggle |
@@ -297,15 +300,21 @@ Call `registerMTs(slots)` once at boot with **the same shape** passed to `@xeplr
 | `useActivateController` | — | `token, error, success, loading` |
 | `useChangePasswordController` | `onSuccess` | `currentPassword, setCurrentPassword, newPassword, setNewPassword, confirmPassword, setConfirmPassword, error, success, loading, handleSubmit` |
 | `useProfileController` | `onSuccess` | `form, error, success, loading, fetching, handleChange, handleSubmit` |
-| `useUserRolesController` | — | `users, roles, search, setSearch, loading, error, saving, handleToggle, isAssigned, reload` |
-| `useAccessMatrixController` | — | `roles, modules, uncategorized, uncategorizedCount, uncatSubTab, setUncatSubTab, activeView, setActiveView, search, setSearch, loading, error, handleModuleToggle, handleItemToggle, isItemAssigned, isModuleSaving, isItemSaving, reload` |
-| `useMasterSettingsController` | — | `tabs, activeTab, setActiveTab, currentTab, items, groupNames, search, setSearch, loading, error, saving, editingItem, editForm, startAdd, startEdit, cancelEdit, updateField, handleSave, handleDelete, reload` |
+| `useUserRolesController` | — | `users, roles, search, setSearch, loading, error, saving, handleToggle, isAssigned, reload, newRoleName, setNewRoleName, creatingRole, createRole` |
+| `useAccessMatrixController` | `workspaces` or `loadWorkspaces` | `roles, modules, uncategorized, uncategorizedCount, uncatSubTab, setUncatSubTab, activeView, setActiveView, search, setSearch, loading, error, handleStateChange, handleModuleToggle, handleItemToggle, isItemAssigned, isModuleSaving, isItemSaving, reload, appliesTo, setAppliesTo, scopeId, setScopeId, workspaces, users, statesSupported` |
+| `useMasterSettingsController` | — | `tabs, activeTab, setActiveTab, currentTab, items, groupNames, search, setSearch, loading, error, saving, editingItem, editForm, startAdd, startEdit, cancelEdit, updateField, handleSave, handleDelete, reload, isSuperAdmin, handleScopeToggle, isScopeSaving` |
 | `useNavController` | `drawerItems, settingsOverrides, notifications` | `user, accountItems, notifications, logout, accountOpen, toggleAccount, closeAccount, accountRef, drawerOpen, toggleDrawer, closeDrawer, drawerItems, drawerWidth, drawerResizing, startDrawerResize, resetDrawerWidth, nudgeDrawerWidth, drawerWidthBounds` |
 
 - Login stores the tokens and calls `AccessProvider`'s `onLogin` when a provider is present. A login refused with "Please wait, someone will activate you." navigates to `notActivatedPath` (default `/auth/not-activated`). Supplying `onSuccess` replaces the default navigation entirely.
 - Register, profile: `handleChange` reads `e.target.name`, so inputs need `name="email"` etc. `form` is `{ name, email, phoneNumber, password }` / `{ name, email, phoneNumber }`.
 - Reset and activate read `?token=` (activate also passes `?workflowKey=` back to the server) and activate runs on mount.
 - The access matrix groups items whose group is `module:action` (e.g. `account:view`) under Modules; the rest are Uncategorized. The Super Admin role is left out of its columns.
+- **Super Admin only APIs.** On Master Settings → APIs, a Super Admin sees a "Super Admin only" switch per API (`handleScopeToggle`). Nobody else sees the column. An API pinned by a migration shows ticked and cannot be switched off, and a Super Admin only API cannot be renamed or deleted there. `isSuperAdmin` comes from `AccessProvider`'s `hasRole`.
+- **Admin view tabs.** User Roles, Access Matrix and Master Settings each show a tab bar across the top (`AdminTabs`), so the three are one click apart. The pages and their paths are one list, `ADMIN_PAGES` (`adminPaths.js`), which the routes use too.
+- **Adding a role.** The User Roles page has a New role field (`createRole`). The role appears as a column there and in the Access Matrix straight away. The server allows it for Super Admin only; anyone else sees its refusal.
+- **Access states.** Each Modules cell is three-way, not a checkbox: **Enabled** (shown and usable), **Disabled** (shown, greyed out, not usable) or **Hidden** (not shown). A role only partly granted shows **Mixed**. `handleStateChange(module, action, roleId, state)` saves a change; `handleModuleToggle` still works for designs written before.
+- **Applies to: Roles, Workspace or User.** Roles are the defaults. A workspace or a user can override them per module and action, and an override may be **Inherit** (no override). Workspaces belong to the host product, not the auth service, so the host passes them: `authRoutes({ accessMatrix: { props: { loadWorkspaces } } })`, or `workspaces` directly.
+- **Server support.** Enabled and Hidden on roles are role mappings (`module-role`) and work today. Disabled, and every workspace or user override, are stored states that need `GET /auth/api/admin/module-states` and `POST /auth/api/admin/module-state` in `@xeplr/auth`. Until those exist the matrix says so and refuses to save them, rather than pretending they were saved.
 - `MASTER_TYPES` is `['roles', 'apis', 'pages', 'elements', 'menus']`.
 
 ### Design validation
@@ -320,8 +329,8 @@ Each page (except activate and not-activated) checks its rendered design three s
 | `RESET_PASSWORD_RULES` | `#xeplr-password`, submit |
 | `CHANGE_PASSWORD_RULES` | `#xeplr-current-password`, `#xeplr-new-password`, `#xeplr-confirm-password`, submit |
 | `PROFILE_RULES` | `#xeplr-profile-name`, `#xeplr-profile-email`, submit |
-| `USER_ROLES_MATRIX_RULES` | `#xeplr-admin-user-search`, `[role="grid"]` |
-| `ACCESS_MATRIX_RULES` | `#xeplr-admin-access-search`, `[role="tablist"]` |
+| `USER_ROLES_MATRIX_RULES` | `#xeplr-admin-user-search`, `[role="grid"]`, `#xeplr-admin-new-role` |
+| `ACCESS_MATRIX_RULES` | `#xeplr-admin-access-search`, `[role="tablist"]`, `#xeplr-admin-access-scope` (the Applies-to radiogroup) |
 | `MASTER_SETTINGS_RULES` | `#xeplr-admin-master-search`, `[role="tablist"]` |
 | `NAV_RULES` | `[aria-haspopup="menu"]` |
 
@@ -354,6 +363,9 @@ Admin (auth):
 | `toggleUserRole({ userId, roleId, assign })` | `POST /auth/api/admin/user-role` |
 | `toggleAccessRole({ type, itemId, roleId, assign })` | `POST /auth/api/admin/access-role` |
 | `toggleModuleRole({ module, action, roleId, assign })` | `POST /auth/api/admin/module-role` |
+| `getModuleStates({ scope, scopeId })` | `GET /auth/api/admin/module-states?scope=role\|workspace\|user&scopeId=…` → `[{ module, action, roleId?, state }]`. Server support pending |
+| `setModuleState({ scope, scopeId, module, action, roleId, state })` | `POST /auth/api/admin/module-state`. `state` is `enabled` / `disabled` / `hidden`, or `null` to clear. Server support pending |
+| `setApiScope(id, scope)` | `POST /auth/api/admin/master/apis/scope`. Super Admin only; `scope` is `system` or `company` |
 | `getMasterItems(type)`, `saveMasterItem(type, data)`, `deleteMasterItem(type, id)` | `GET` / `POST /auth/api/admin/master/<type>`, `POST …/<type>/delete` |
 | `listMenuItems`, `saveMenuItems`, `addMenuItem`, `removeMenuItem` | see [Changing the menu](#changing-the-menu) |
 
@@ -370,6 +382,8 @@ src/
   mt.js, activeScope.js    ─ multi-tenant levels and the scope per level
   returnTo.js              ─ where to go after a gate
   menuLabels.js            ─ labelMenuItems
+  adminPaths.js            ─ ADMIN_PAGES: the admin pages, their labels and paths
+  accessStates.js          ─ enabled / disabled / hidden / inherit: cell states and what a change sends
   AccessContext.jsx        ─ AccessProvider, useAccess, useAccessStrict
   ProtectedRoute.jsx, AccessGuard.jsx
   ThemeContext.jsx         ─ ThemeProvider, useTheme

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/ui-account",
-  "version": "1.0.9",
+  "version": "1.0.10",
   "description": "Account UI: auth, profile, RBAC admin, tenant management — React controller hooks and designs",
   "type": "module",
   "main": "src/index.js",

package/src/accessStates.js

@@ -0,0 +1,95 @@
+/**
+ * Access states — model layer for the Access Matrix's three-way cells.
+ * Pure logic, no React dependency.
+ *
+ * A module + action (e.g. reports / view) is, for whoever it applies to:
+ *
+ *   enabled    shown and usable
+ *   disabled   shown, greyed out, not usable — the API refuses it too
+ *   hidden     not shown — the API refuses it
+ *
+ * They apply at three levels. ROLES are the defaults. A WORKSPACE or a USER
+ * can override them, and an override may also be `inherit`: no override,
+ * the roles decide.
+ */
+
+export var STATES = ['enabled', 'disabled', 'hidden'];
+export var OVERRIDE_STATES = ['inherit', 'enabled', 'disabled', 'hidden'];
+
+export var STATE_LABELS = {
+  inherit: 'Inherit',
+  enabled: 'Enabled',
+  disabled: 'Disabled',
+  hidden: 'Hidden',
+  partial: 'Mixed'
+};
+
+export var SCOPES = ['role', 'workspace', 'user'];
+
+/** The map key one stored state lives under. roleId only for scope 'role'. */
+export function stateKey(module, action, roleId) {
+  return module + ':' + action + (roleId ? ':' + roleId : '');
+}
+
+/**
+ * Stored states, as the server sends them, into a lookup:
+ *   [{ module, action, roleId?, state }]  →  { 'reports:view:r1': 'disabled' }
+ * Rows with an unknown state are dropped: a value the UI cannot show must not
+ * be shown as something else.
+ */
+export function indexStates(rows) {
+  var out = {};
+  (rows || []).forEach(function(r) {
+    if (!r || !r.module || !r.action) return;
+    if (STATES.indexOf(r.state) === -1) return;
+    out[stateKey(r.module, r.action, r.roleId)] = r.state;
+  });
+  return out;
+}
+
+/**
+ * What a ROLE cell shows.
+ *
+ * The role's grant decides visibility: every item of the module/action mapped
+ * to the role is `enabled`, none is `hidden`, some is `partial` (a mixed grant,
+ * shown as-is so nobody reads it as a clean answer). A stored `disabled` turns
+ * a granted cell into `disabled` — shown, but not usable.
+ *
+ * @param grant   'all' | 'partial' | 'none'  (from the role mappings)
+ * @param stored  the stored state for this role, or undefined
+ */
+export function roleCellState(grant, stored) {
+  if (grant === 'none') return 'hidden';
+  if (stored === 'disabled') return grant === 'all' ? 'disabled' : 'partial';
+  if (grant === 'all') return 'enabled';
+  return 'partial';
+}
+
+/** What a WORKSPACE or USER cell shows: its override, else inherit. */
+export function overrideCellState(stored) {
+  return STATES.indexOf(stored) === -1 ? 'inherit' : stored;
+}
+
+/**
+ * The server calls a role-cell change needs, in order.
+ *
+ * Visibility is the role mapping (today's module-role endpoint); `disabled` is
+ * a stored state on top of it. So:
+ *   enabled   → grant, and clear any stored state
+ *   disabled  → grant, and store 'disabled'
+ *   hidden    → revoke, and clear any stored state
+ *
+ * @returns [{ call: 'grant'|'revoke'|'setState'|'clearState', state? }]
+ */
+export function roleChangePlan(nextState) {
+  if (nextState === 'enabled') return [{ call: 'grant' }, { call: 'clearState' }];
+  if (nextState === 'disabled') return [{ call: 'grant' }, { call: 'setState', state: 'disabled' }];
+  if (nextState === 'hidden') return [{ call: 'revoke' }, { call: 'clearState' }];
+  throw new Error('Unknown access state: ' + nextState);
+}
+
+/** Does this change need the server's stored states (not just role mappings)? */
+export function needsStoredStates(scope, nextState) {
+  if (scope !== 'role') return true;
+  return nextState === 'disabled';
+}

package/src/adminApi.js

@@ -38,6 +38,29 @@ export function toggleModuleRole({ module, action, roleId, assign }) {
   });
 }
 
+// ── Access states: enabled / disabled / hidden, per role, workspace or user ──
+//
+// Server support is being added alongside this UI. Until the auth service has
+// these routes, getModuleStates fails and the Access Matrix says so, while
+// Enabled / Hidden on roles keep working through module-role above.
+
+/** Stored states for one scope: [{ module, action, roleId?, state }]. scope: 'role' | 'workspace' | 'user'. */
+export function getModuleStates({ scope, scopeId }) {
+  var q = '?scope=' + encodeURIComponent(scope) + (scopeId ? '&scopeId=' + encodeURIComponent(scopeId) : '');
+  return authFetch('/auth/api/admin/module-states' + q);
+}
+
+/**
+ * Store or clear one state. state: 'enabled' | 'disabled' | 'hidden', or
+ * 'inherit' / null to remove the stored state. roleId only for scope 'role'.
+ */
+export function setModuleState({ scope, scopeId, module, action, roleId, state }) {
+  return authFetch('/auth/api/admin/module-state', {
+    method: 'POST',
+    body: JSON.stringify({ scope, scopeId, module, action, roleId, state }),
+  });
+}
+
 // ── Menu items: key, label, order, visibility (Super Admin) ──────────────
 
 /** Every menu item, hidden ones included: [{ name, label, shown, sortOrder, isHidden, isPublic }]. */

package/src/adminPaths.js

@@ -0,0 +1,10 @@
+/**
+ * The admin pages, in the order the admin view's tabs show them.
+ * One list, read by authRoutes' manifest and by the AdminTabs design, so the
+ * tabs and the routes cannot disagree about where a page lives.
+ */
+export var ADMIN_PAGES = [
+  { key: 'userRoles',      label: 'User Roles',      path: '/auth/admin/user-roles' },
+  { key: 'accessMatrix',   label: 'Access Matrix',   path: '/auth/admin/access-matrix' },
+  { key: 'masterSettings', label: 'Master Settings', path: '/auth/admin/master-settings' }
+];

package/src/authRoutes.jsx

@@ -1,3 +1,4 @@
+import { ADMIN_PAGES } from './adminPaths.js';
 import { isValidElement } from 'react';
 import { Route } from 'react-router-dom';
 import { ProtectedRoute } from './ProtectedRoute.jsx';
@@ -23,11 +24,13 @@ var MANIFEST = [
   { key: 'notActivated',   path: '/auth/not-activated',         Page: NotActivatedPage,   group: 'public' },
   { key: 'profile',        path: '/auth/profile',               Page: ProfilePage,        group: 'account' },
   { key: 'changePassword', path: '/auth/change-password',       Page: ChangePasswordPage, group: 'account' },
-  { key: 'userRoles',      path: '/auth/admin/user-roles',      Page: UserRolesPage,      group: 'admin' },
-  { key: 'accessMatrix',   path: '/auth/admin/access-matrix',   Page: AccessMatrixPage,   group: 'admin' },
-  { key: 'masterSettings', path: '/auth/admin/master-settings', Page: MasterSettingsPage, group: 'admin' }
+  { key: 'userRoles',      path: adminPath('userRoles'),      Page: UserRolesPage,      group: 'admin' },
+  { key: 'accessMatrix',   path: adminPath('accessMatrix'),   Page: AccessMatrixPage,   group: 'admin' },
+  { key: 'masterSettings', path: adminPath('masterSettings'), Page: MasterSettingsPage, group: 'admin' }
 ];
 
+function adminPath(key) { return ADMIN_PAGES.find(function (p) { return p.key === key; }).path; }
+
 var _pathByKey = {};
 MANIFEST.forEach(function (e) { _pathByKey[e.key] = e.path; });
 
@@ -51,7 +54,9 @@ function resolveElement(entry, ov) {
   if (!ov) return <Page />;                          // framework default
   if (isValidElement(ov)) return ov;                 // bare element  → full replace
   if (ov.element) return ov.element;                 // { element }   → full replace
-  if (ov.design) return <Page design={ov.design} />; // { design }    → re-skin (keeps controller)
+  if (ov.design || ov.props) {                       // { design, props } → re-skin and/or feed the controller
+    return <Page design={ov.design} {...(ov.props || {})} />;
+  }
   return <Page />;                                   // e.g. only { path } supplied
 }
 
@@ -67,6 +72,8 @@ function resolveElement(entry, ov) {
  * @param {object} [overrides]  map of manifest key → how to render it:
  *   - { design: MyDesign }   re-skin: framework controller + validation, your look
  *                            (design receives the controller's props)
+ *   - { props: {...} }       pass props to the page's controller, e.g.
+ *                            accessMatrix: { props: { loadWorkspaces } }
  *   - { element: <X/> }      full replace: your element, framework logic ignored
  *   - a React element        shorthand for { element }
  *   - false | null           drop this route (app doesn't want it)

package/src/designs/AccessMatrixSample.jsx

@@ -1,7 +1,9 @@
 import './admin.css';
+import AdminTabs from './AdminTabs.jsx';
+import { STATES, OVERRIDE_STATES, STATE_LABELS } from '../accessStates.js';
 
-var ACTION_LABELS = { view: 'View Only', edit: 'Add / Edit', delete: 'Delete' };
-var ACTION_CLASSES = { view: 'xeplr-admin-action-view', edit: 'xeplr-admin-action-edit', delete: 'xeplr-admin-action-delete' };
+var ACTION_LABELS = { view: 'View Only', create: 'Create', edit: 'Add / Edit', delete: 'Delete' };
+var ACTION_CLASSES = { view: 'xeplr-admin-action-view', create: 'xeplr-admin-action-edit', edit: 'xeplr-admin-action-edit', delete: 'xeplr-admin-action-delete' };
 var UNCAT_TABS = [
   { key: 'apis', label: 'APIs' },
   { key: 'pages', label: 'Pages' },
@@ -12,11 +14,13 @@ var UNCAT_TABS = [
 export default function AccessMatrixSample({
   roles, modules, uncategorized, uncategorizedCount, uncatSubTab, setUncatSubTab,
   activeView, setActiveView, search, setSearch,
-  loading, error, handleModuleToggle, handleItemToggle,
-  isItemAssigned, isModuleSaving, isItemSaving, reload
+  loading, error, handleStateChange, handleItemToggle,
+  isItemAssigned, isModuleSaving, isItemSaving, reload,
+  appliesTo, setAppliesTo, scopeId, setScopeId, workspaces, users, statesSupported
 }) {
   return (
     <div className="xeplr-admin-container">
+      <AdminTabs />
       <div className="xeplr-admin-header">
         <h2>Access Matrix</h2>
         <button type="button" onClick={reload} className="xeplr-admin-btn-secondary">Refresh</button>
@@ -43,6 +47,15 @@ export default function AccessMatrixSample({
         </button>
       </div>
 
+      {activeView === 'modules' && renderScopeBar(appliesTo, setAppliesTo, scopeId, setScopeId, workspaces, users)}
+
+      {activeView === 'modules' && statesSupported === false && (
+        <div className="xeplr-admin-alert xeplr-admin-alert-info">
+          The server does not store access states yet. Enabled and Hidden on roles work today;
+          Disabled, and workspace or user overrides, arrive with the server update.
+        </div>
+      )}
+
       {/* Search */}
       <div className="xeplr-admin-toolbar">
         <input
@@ -60,7 +73,7 @@ export default function AccessMatrixSample({
       {loading ? (
         <div className="xeplr-admin-loading">Loading...</div>
       ) : activeView === 'modules' ? (
-        renderModulesView(roles, modules, handleModuleToggle, isModuleSaving)
+        renderModulesView(roles, modules, handleStateChange, isModuleSaving, appliesTo, scopeId)
       ) : (
         renderUncategorizedView(roles, uncategorized, uncatSubTab, setUncatSubTab, handleItemToggle, isItemAssigned, isItemSaving)
       )}
@@ -68,10 +81,61 @@ export default function AccessMatrixSample({
   );
 }
 
-function renderModulesView(roles, modules, handleModuleToggle, isModuleSaving) {
+var SCOPE_OPTIONS = [
+  { key: 'role', label: 'Roles' },
+  { key: 'workspace', label: 'Workspace' },
+  { key: 'user', label: 'User' },
+];
+
+function renderScopeBar(appliesTo, setAppliesTo, scopeId, setScopeId, workspaces, users) {
+  var list = appliesTo === 'workspace' ? (workspaces || []) : appliesTo === 'user' ? (users || []) : [];
+  return (
+    <div className="xeplr-admin-scope-bar">
+      <span className="xeplr-admin-scope-label">Applies to</span>
+      <div id="xeplr-admin-access-scope" role="radiogroup" aria-label="Applies to" className="xeplr-admin-scope-options">
+        {SCOPE_OPTIONS.map(function(opt) {
+          var on = appliesTo === opt.key;
+          return (
+            <button key={opt.key} type="button" role="radio" aria-checked={on}
+              className={'xeplr-admin-scope-option' + (on ? ' xeplr-admin-scope-option-active' : '')}
+              onClick={function() { setAppliesTo(opt.key); }}>
+              {opt.label}
+            </button>
+          );
+        })}
+      </div>
+      {appliesTo !== 'role' && (
+        <select id="xeplr-admin-access-scope-target" className="xeplr-admin-scope-select"
+          value={scopeId} onChange={function(e) { setScopeId(e.target.value); }}>
+          <option value="">{appliesTo === 'workspace' ? 'Choose a workspace…' : 'Choose a user…'}</option>
+          {list.map(function(x) {
+            return <option key={x.id} value={x.id}>{x.name || x.email || x.id}</option>;
+          })}
+        </select>
+      )}
+    </div>
+  );
+}
+
+function stateSelect(value, options, onChange, disabled, label) {
+  return (
+    <select aria-label={label} value={value} disabled={disabled}
+      className={'xeplr-admin-state-select xeplr-admin-state-' + value}
+      onChange={function(e) { onChange(e.target.value); }}>
+      {value === 'partial' && <option value="partial" disabled>{STATE_LABELS.partial}</option>}
+      {options.map(function(s) { return <option key={s} value={s}>{STATE_LABELS[s]}</option>; })}
+    </select>
+  );
+}
+
+function renderModulesView(roles, modules, handleStateChange, isModuleSaving, appliesTo, scopeId) {
   if (modules.length === 0) {
     return <div className="xeplr-admin-empty-box">No modules found. Items need a <code>module:action</code> group value to appear here.</div>;
   }
+  if (appliesTo !== 'role' && !scopeId) {
+    return <div className="xeplr-admin-empty-box">Choose a {appliesTo} above to see and change its overrides.</div>;
+  }
+  var byRole = appliesTo === 'role';
 
   return (
     <div className="xeplr-admin-matrix-wrapper">
@@ -80,9 +144,9 @@ function renderModulesView(roles, modules, handleModuleToggle, isModuleSaving) {
           <tr>
             <th className="xeplr-admin-sticky-col xeplr-admin-module-col">Module</th>
             <th className="xeplr-admin-action-col">Action</th>
-            {roles.map(function(role) {
+            {byRole ? roles.map(function(role) {
               return <th key={role.id} className="xeplr-admin-role-header">{role.name}</th>;
-            })}
+            }) : <th className="xeplr-admin-role-header">State</th>}
           </tr>
         </thead>
         <tbody>
@@ -100,26 +164,23 @@ function renderModulesView(roles, modules, handleModuleToggle, isModuleSaving) {
                   <td className={'xeplr-admin-action-cell ' + actionClass}>
                     {actionLabel}
                   </td>
-                  {roles.map(function(role) {
-                    var state = actionEntry.getRoleState(role.id);
-                    var isSaving = isModuleSaving(mod.name, actionEntry.action, role.id);
+                  {byRole ? roles.map(function(role) {
                     return (
                       <td key={role.id} className="xeplr-admin-cell">
-                        <label className="xeplr-admin-toggle">
-                          <input
-                            type="checkbox"
-                            checked={state === 'all'}
-                            ref={function(el) {
-                              if (el) el.indeterminate = state === 'partial';
-                            }}
-                            disabled={isSaving}
-                            onChange={function() { handleModuleToggle(mod.name, actionEntry.action, role.id, state); }}
-                          />
-                          <span className={'xeplr-admin-checkmark' + (state === 'partial' ? ' xeplr-admin-partial' : '') + (isSaving ? ' xeplr-admin-saving' : '')} />
-                        </label>
+                        {stateSelect(actionEntry.getCellState(role.id), STATES,
+                          function(next) { handleStateChange(mod.name, actionEntry.action, role.id, next); },
+                          isModuleSaving(mod.name, actionEntry.action, role.id),
+                          mod.name + ' ' + actionLabel + ' for ' + role.name)}
                       </td>
                     );
-                  })}
+                  }) : (
+                    <td className="xeplr-admin-cell">
+                      {stateSelect(actionEntry.getOverrideState(), OVERRIDE_STATES,
+                        function(next) { handleStateChange(mod.name, actionEntry.action, null, next); },
+                        isModuleSaving(mod.name, actionEntry.action, null),
+                        mod.name + ' ' + actionLabel)}
+                    </td>
+                  )}
                 </tr>
               );
             });

package/src/designs/AdminTabs.jsx

@@ -0,0 +1,22 @@
+import { NavLink } from 'react-router-dom';
+import { ADMIN_PAGES } from '../adminPaths.js';
+import './admin.css';
+
+/**
+ * The admin view's own navigation: User Roles · Access Matrix · Master
+ * Settings, one click apart. Rendered at the top of each admin page's design.
+ */
+export default function AdminTabs() {
+  return (
+    <nav className="xeplr-admin-pages" aria-label="Admin pages">
+      {ADMIN_PAGES.map(function(page) {
+        return (
+          <NavLink key={page.key} to={page.path} end
+            className={function(s) { return 'xeplr-admin-page-link' + (s.isActive ? ' xeplr-admin-page-link-active' : ''); }}>
+            {page.label}
+          </NavLink>
+        );
+      })}
+    </nav>
+  );
+}

package/src/designs/MasterSettingsSample.jsx

@@ -1,12 +1,17 @@
 import './admin.css';
+import AdminTabs from './AdminTabs.jsx';
 
 export default function MasterSettingsSample({
   tabs, activeTab, setActiveTab, currentTab, items, search, setSearch,
   loading, error, saving, editingItem, editForm, groupNames,
-  startAdd, startEdit, cancelEdit, updateField, handleSave, handleDelete, reload
+  startAdd, startEdit, cancelEdit, updateField, handleSave, handleDelete, reload,
+  isSuperAdmin, handleScopeToggle, isScopeSaving
 }) {
+  // The "Super Admin only" column: APIs tab, Super Admin viewers only.
+  var showScope = activeTab === 'apis' && isSuperAdmin;
   return (
     <div className="xeplr-admin-container">
+      <AdminTabs />
       <div className="xeplr-admin-header">
         <h2>Master Settings</h2>
         <div style={{ display: 'flex', gap: '8px' }}>
@@ -58,6 +63,7 @@ export default function MasterSettingsSample({
                 {currentTab.fields.map(function(field) {
                   return <th key={field.key} className={field.key === 'name' ? 'xeplr-admin-sticky-col' : ''}>{field.label}</th>;
                 })}
+                {showScope && <th className="xeplr-admin-scope-col">Super Admin only</th>}
                 <th className="xeplr-admin-actions-col">Actions</th>
               </tr>
             </thead>
@@ -86,7 +92,7 @@ export default function MasterSettingsSample({
               )}
 
               {items.length === 0 && editingItem !== '__new__' ? (
-                <tr><td colSpan={currentTab.fields.length + 1} className="xeplr-admin-empty">No {currentTab.label.toLowerCase()} found</td></tr>
+                <tr><td colSpan={currentTab.fields.length + (showScope ? 2 : 1)} className="xeplr-admin-empty">No {currentTab.label.toLowerCase()} found</td></tr>
               ) : (
                 items.map(function(item) {
                   var isEditing = editingItem === item.id;
@@ -107,6 +113,11 @@ export default function MasterSettingsSample({
                           </td>
                         );
                       })}
+                      {showScope && (
+                        <td className="xeplr-admin-scope-col">
+                          {renderScopeSwitch(item, handleScopeToggle, isScopeSaving(item.id))}
+                        </td>
+                      )}
                       <td className="xeplr-admin-actions-col">
                         {isEditing ? (
                           <div className="xeplr-admin-action-btns">
@@ -119,10 +130,14 @@ export default function MasterSettingsSample({
                           </div>
                         ) : (
                           <div className="xeplr-admin-action-btns">
-                            <button onClick={function() { startEdit(item); }} className="xeplr-admin-btn-edit" title="Edit" disabled={editingItem !== null}>
+                            <button onClick={function() { startEdit(item); }} className="xeplr-admin-btn-edit"
+                              title={item.scope === 'system' ? 'A Super Admin only API cannot be renamed' : 'Edit'}
+                              disabled={editingItem !== null || item.scope === 'system'}>
                               {'\u270E'}
                             </button>
-                            <button onClick={function() { if (confirm('Delete this item?')) handleDelete(item.id); }} className="xeplr-admin-btn-delete" title="Delete" disabled={saving || editingItem !== null}>
+                            <button onClick={function() { if (confirm('Delete this item?')) handleDelete(item.id); }} className="xeplr-admin-btn-delete"
+                              title={item.scope === 'system' ? 'A Super Admin only API cannot be deleted' : 'Delete'}
+                              disabled={saving || editingItem !== null || item.scope === 'system'}>
                               {'\u2715'}
                             </button>
                           </div>
@@ -204,3 +219,17 @@ function renderValue(field, value) {
 
   return <span className={field.key === 'name' ? 'xeplr-admin-item-name' : ''}>{value || '\u2014'}</span>;
 }
+
+function renderScopeSwitch(item, onToggle, busy) {
+  var on = item.scope === 'system';
+  var locked = !!item.scopeLocked;
+  return (
+    <label className="xeplr-admin-toggle"
+      title={locked ? 'Pinned as Super Admin only by a migration' : on ? 'Only Super Admin can use this API' : 'Make this API Super Admin only'}>
+      <input type="checkbox" checked={on} disabled={busy || locked}
+        aria-label={'Super Admin only: ' + item.name}
+        onChange={function() { onToggle(item); }} />
+      <span className={'xeplr-admin-checkmark' + (busy ? ' xeplr-admin-saving' : '') + (locked ? ' xeplr-admin-locked' : '')} />
+    </label>
+  );
+}

package/src/designs/UserRolesMatrixSample.jsx

@@ -1,10 +1,13 @@
 import './admin.css';
+import AdminTabs from './AdminTabs.jsx';
 
 export default function UserRolesMatrixSample({
-  users, roles, search, setSearch, loading, error, saving, handleToggle, isAssigned, reload
+  users, roles, search, setSearch, loading, error, saving, handleToggle, isAssigned, reload,
+  newRoleName, setNewRoleName, creatingRole, createRole
 }) {
   return (
     <div className="xeplr-admin-container">
+      <AdminTabs />
       <div className="xeplr-admin-header">
         <h2>User Roles</h2>
         <div className="xeplr-admin-toolbar">
@@ -20,6 +23,21 @@ export default function UserRolesMatrixSample({
         </div>
       </div>
 
+      <form className="xeplr-admin-new-role"
+        onSubmit={function(e) { e.preventDefault(); createRole(); }}>
+        <input
+          id="xeplr-admin-new-role"
+          type="text"
+          placeholder="New role, e.g. Workspace Admin"
+          value={newRoleName}
+          onChange={function(e) { setNewRoleName(e.target.value); }}
+          className="xeplr-admin-search"
+        />
+        <button type="submit" className="xeplr-admin-btn-primary" disabled={creatingRole || !newRoleName.trim()}>
+          {creatingRole ? 'Adding…' : 'Add role'}
+        </button>
+      </form>
+
       {error && <div className="xeplr-admin-alert xeplr-admin-alert-error">{error}</div>}
 
       {loading ? (

package/src/designs/admin.css

@@ -533,3 +533,115 @@
   color: var(--xeplr-danger);
   border: 1px solid var(--xeplr-danger-border);
 }
+
+/* ── Access Matrix: who it applies to, and three-way cells ─────────────── */
+
+.xeplr-admin-scope-bar {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 10px;
+  margin: 12px 0;
+}
+
+.xeplr-admin-scope-label {
+  font-size: 13px;
+  color: var(--xeplr-text-muted);
+}
+
+.xeplr-admin-scope-options {
+  display: inline-flex;
+  border: 1px solid var(--xeplr-input-border);
+  border-radius: 6px;
+  overflow: hidden;
+}
+
+.xeplr-admin-scope-option {
+  padding: 6px 14px;
+  border: none;
+  border-right: 1px solid var(--xeplr-input-border);
+  background: var(--xeplr-input-bg);
+  color: var(--xeplr-text-primary);
+  font-size: 13px;
+  cursor: pointer;
+}
+
+.xeplr-admin-scope-option:last-child { border-right: none; }
+.xeplr-admin-scope-option:hover { background: var(--xeplr-bg-hover); }
+
+.xeplr-admin-scope-option-active,
+.xeplr-admin-scope-option-active:hover {
+  background: var(--xeplr-accent);
+  color: var(--xeplr-accent-text);
+}
+
+.xeplr-admin-scope-select,
+.xeplr-admin-state-select {
+  padding: 5px 8px;
+  border: 1px solid var(--xeplr-input-border);
+  border-radius: 6px;
+  background: var(--xeplr-input-bg);
+  color: var(--xeplr-input-text);
+  font-size: 13px;
+}
+
+.xeplr-admin-scope-select { min-width: 220px; }
+.xeplr-admin-state-select { min-width: 104px; cursor: pointer; }
+.xeplr-admin-state-select:disabled { opacity: 0.6; cursor: progress; }
+
+/* The state is readable at a glance, not only after opening the select. */
+.xeplr-admin-state-enabled  { color: var(--xeplr-success); border-color: var(--xeplr-success-border); }
+.xeplr-admin-state-disabled { color: var(--xeplr-warning); }
+.xeplr-admin-state-hidden   { color: var(--xeplr-text-muted); }
+.xeplr-admin-state-inherit  { color: var(--xeplr-text-muted); font-style: italic; }
+.xeplr-admin-state-partial  { color: var(--xeplr-info); }
+
+.xeplr-admin-alert-info {
+  border: 1px solid var(--xeplr-info-border);
+  background: var(--xeplr-info-bg);
+  color: var(--xeplr-info);
+}
+
+/* ── Admin page: add a role ─────────────────────────────────────────────── */
+
+.xeplr-admin-new-role {
+  display: flex;
+  gap: 8px;
+  margin: 12px 0;
+  max-width: 480px;
+}
+
+.xeplr-admin-new-role .xeplr-admin-search { flex: 1; }
+.xeplr-admin-new-role button:disabled { opacity: 0.5; cursor: not-allowed; }
+
+/* ── Master Settings: the "Super Admin only" switch (Super Admin viewers only) ── */
+
+.xeplr-admin-scope-col { text-align: center; white-space: nowrap; }
+.xeplr-admin-locked { opacity: 0.55; cursor: not-allowed; }
+
+/* ── Admin view: the pages, one click apart ─────────────────────────────── */
+
+.xeplr-admin-pages {
+  display: flex;
+  gap: 4px;
+  margin-bottom: 18px;
+  padding-bottom: 10px;
+  border-bottom: 1px solid var(--xeplr-border-primary);
+}
+
+.xeplr-admin-page-link {
+  padding: 6px 12px;
+  border-radius: 6px;
+  color: var(--xeplr-text-muted);
+  text-decoration: none;
+  font-size: 13px;
+  font-weight: 500;
+}
+
+.xeplr-admin-page-link:hover { background: var(--xeplr-bg-hover); color: var(--xeplr-text-primary); }
+
+.xeplr-admin-page-link-active,
+.xeplr-admin-page-link-active:hover {
+  background: var(--xeplr-accent-muted);
+  color: var(--xeplr-accent);
+}

package/src/designs/index.js

@@ -14,3 +14,4 @@ export { default as AccountMenu } from './AccountMenu.jsx';
 export { default as NavDrawer } from './NavDrawer.jsx';
 export { default as NavFloatingSettings } from './NavFloatingSettings.jsx';
 export { default as NotificationsBell } from './NotificationsBell.jsx';
+export { default as AdminTabs } from './AdminTabs.jsx';

package/src/index.js

@@ -56,3 +56,4 @@ export { LoginPage, RegisterPage, ForgotPasswordPage, ResetPasswordPage, Activat
 
 // One-call auth routing — mount every auth page with no boilerplate; override just what you want
 export { authRoutes, authPath } from './authRoutes.jsx';
+export { ADMIN_PAGES } from './adminPaths.js';

package/src/masterApi.js

@@ -26,3 +26,15 @@ export function deleteMasterItem(type, id) {
 }
 
 export { TYPES as MASTER_TYPES };
+
+/**
+ * Move an API in or out of system scope — "Super Admin only". scope:
+ * 'system' | 'company'. The server allows it for Super Admin only and refuses
+ * an API a migration pinned (scopeLocked).
+ */
+export function setApiScope(id, scope) {
+  return authFetch('/auth/api/admin/master/apis/scope', {
+    method: 'POST',
+    body: JSON.stringify({ id, scope }),
+  });
+}

package/src/useAccessMatrixController.js

@@ -1,5 +1,6 @@
 import { useState, useEffect, useMemo, useCallback } from 'react';
-import { getRoles, getAccessItems, toggleModuleRole, toggleAccessRole } from './adminApi.js';
+import { getRoles, getAccessItems, getUsers, toggleModuleRole, toggleAccessRole, getModuleStates, setModuleState } from './adminApi.js';
+import { stateKey, indexStates, roleCellState, overrideCellState, roleChangePlan, needsStoredStates } from './accessStates.js';
 
 var GROUP_FIELDS = {
   apis: 'apiGroup',
@@ -10,7 +11,7 @@ var GROUP_FIELDS = {
 
 var TYPES = ['apis', 'pages', 'elements', 'menus'];
 
-var ACTION_ORDER = { view: 0, edit: 1, delete: 2 };
+var ACTION_ORDER = { view: 0, create: 1, edit: 2, delete: 3 };
 
 function parseModuleGroup(groupValue) {
   if (!groupValue) return null;
@@ -19,7 +20,14 @@ function parseModuleGroup(groupValue) {
   return { module: parts[0], action: parts[1] };
 }
 
-export function useAccessMatrixController() {
+/**
+ * @param props.workspaces      [{ id, name }] the host app's workspaces, for the
+ *                              "Applies to: Workspace" picker. Workspaces live in
+ *                              the product (BI), not in the auth service.
+ * @param props.loadWorkspaces  async () => [{ id, name }], instead of `workspaces`
+ */
+export function useAccessMatrixController(props) {
+  props = props || {};
   var [roles, setRoles] = useState([]);
   var [rawItems, setRawItems] = useState({ apis: [], pages: [], elements: [], menus: [] });
   var [activeView, setActiveView] = useState('modules');
@@ -29,6 +37,40 @@ export function useAccessMatrixController() {
   var [error, setError] = useState('');
   var [saving, setSaving] = useState({});
 
+  // ── who the matrix applies to: roles (the defaults), a workspace, a user ──
+  var [appliesTo, setAppliesToState] = useState('role');
+  var [scopeId, setScopeIdState] = useState('');
+  var [workspaces, setWorkspaces] = useState(props.workspaces || []);
+  var [users, setUsers] = useState([]);
+  // Stored states for the current scope: { 'reports:view[:roleId]': state }.
+  var [storedStates, setStoredStates] = useState({});
+  // null = not known yet; false = the server has no access-state routes yet.
+  var [statesSupported, setStatesSupported] = useState(null);
+
+  useEffect(function() {
+    if (props.workspaces) { setWorkspaces(props.workspaces); return; }
+    if (typeof props.loadWorkspaces !== 'function') return;
+    var alive = true;
+    Promise.resolve(props.loadWorkspaces()).then(function(list) {
+      if (alive) setWorkspaces(list || []);
+    }).catch(function(err) { if (alive) setError(err.message); });
+    return function() { alive = false; };
+  }, [props.workspaces, props.loadWorkspaces]);
+
+  async function loadStates(scope, id) {
+    if (scope !== 'role' && !id) { setStoredStates({}); return; }
+    try {
+      var rows = await getModuleStates({ scope: scope, scopeId: scope === 'role' ? null : id });
+      setStoredStates(indexStates(rows));
+      setStatesSupported(true);
+    } catch (err) {
+      // No server support yet: roles still work through their mappings, and
+      // the design shows a notice rather than pretending overrides exist.
+      setStoredStates({});
+      setStatesSupported(false);
+    }
+  }
+
   useEffect(function() {
     loadData();
   }, []);
@@ -40,6 +82,7 @@ export function useAccessMatrixController() {
       var [rolesData, itemsData] = await Promise.all([getRoles(), getAccessItems()]);
       setRoles(rolesData.filter(function(r) { return r.name !== 'Super Admin'; }));
       setRawItems(itemsData);
+      await loadStates(appliesTo, scopeId);
     } catch (err) {
       setError(err.message);
     } finally {
@@ -93,21 +136,30 @@ export function useAccessMatrixController() {
           action: action,
           itemCount: data.items.length,
           items: data.items,
-          getRoleState: function(roleId) {
-            var info = data.roleIds[roleId];
-            if (!info || info.total === 0) return 'none';
-            if (info.assigned === info.total) return 'all';
-            if (info.assigned > 0) return 'partial';
-            return 'none';
+          getRoleState: getRoleState,
+          // Three-way cell for a role: enabled / disabled / hidden (or partial).
+          getCellState: function(roleId) {
+            return roleCellState(getRoleState(roleId), storedStates[stateKey(name, action, roleId)]);
+          },
+          // Three-way cell plus inherit, for the chosen workspace or user.
+          getOverrideState: function() {
+            return overrideCellState(storedStates[stateKey(name, action)]);
           }
         };
+        function getRoleState(roleId) {
+          var info = data.roleIds[roleId];
+          if (!info || info.total === 0) return 'none';
+          if (info.assigned === info.total) return 'all';
+          if (info.assigned > 0) return 'partial';
+          return 'none';
+        }
       });
 
       return { name: name, actions: actions };
     });
 
     return result;
-  }, [rawItems, roles, search]);
+  }, [rawItems, roles, search, storedStates]);
 
   // ─── Uncategorized view: items without module:action group ───
   var uncategorized = useMemo(function() {
@@ -135,45 +187,111 @@ export function useAccessMatrixController() {
     return count;
   }, [uncategorized]);
 
-  // ─── Module toggle (bulk) ───
-  var handleModuleToggle = useCallback(async function(moduleName, action, roleId, currentState) {
-    var assign = currentState !== 'all';
-    var key = 'module:' + moduleName + ':' + action + ':' + roleId;
-    setSaving(function(prev) { var next = { ...prev }; next[key] = true; return next; });
-
-    try {
-      await toggleModuleRole({ module: moduleName, action: action, roleId: roleId, assign: assign });
+  // Grant or revoke a module/action for a role, and mirror it locally.
+  async function applyGrant(moduleName, action, roleId, assign) {
+    await toggleModuleRole({ module: moduleName, action: action, roleId: roleId, assign: assign });
+    setRawItems(function(prev) {
+      var updated = {};
+      TYPES.forEach(function(type) {
+        var groupField = GROUP_FIELDS[type];
+        updated[type] = prev[type].map(function(item) {
+          var parsed = parseModuleGroup(item[groupField]);
+          if (!parsed || parsed.module !== moduleName || parsed.action !== action) return item;
 
-      // Optimistic: update local state
-      setRawItems(function(prev) {
-        var updated = {};
-        TYPES.forEach(function(type) {
-          var groupField = GROUP_FIELDS[type];
-          updated[type] = prev[type].map(function(item) {
-            var parsed = parseModuleGroup(item[groupField]);
-            if (!parsed || parsed.module !== moduleName || parsed.action !== action) return item;
-
-            var newRoles;
-            if (assign) {
-              var hasRole = item.roles && item.roles.some(function(r) { return r.id === roleId; });
-              if (hasRole) return item;
-              var role = roles.find(function(r) { return r.id === roleId; });
-              newRoles = (item.roles || []).concat(role ? [role] : []);
-            } else {
-              newRoles = (item.roles || []).filter(function(r) { return r.id !== roleId; });
-            }
-            return { ...item, roles: newRoles };
-          });
+          var newRoles;
+          if (assign) {
+            var hasRole = item.roles && item.roles.some(function(r) { return r.id === roleId; });
+            if (hasRole) return item;
+            var role = roles.find(function(r) { return r.id === roleId; });
+            newRoles = (item.roles || []).concat(role ? [role] : []);
+          } else {
+            newRoles = (item.roles || []).filter(function(r) { return r.id !== roleId; });
+          }
+          return { ...item, roles: newRoles };
         });
-        return updated;
       });
+      return updated;
+    });
+  }
+
+  function markSaving(key, on) {
+    setSaving(function(prev) { var next = { ...prev }; if (on) next[key] = true; else delete next[key]; return next; });
+  }
+
+  // ─── Module toggle (bulk) — kept for designs written before three-way cells ───
+  var handleModuleToggle = useCallback(async function(moduleName, action, roleId, currentState) {
+    var key = 'module:' + moduleName + ':' + action + ':' + roleId;
+    markSaving(key, true);
+    try {
+      await applyGrant(moduleName, action, roleId, currentState !== 'all');
     } catch (err) {
       setError(err.message);
     } finally {
-      setSaving(function(prev) { var next = { ...prev }; delete next[key]; return next; });
+      markSaving(key, false);
     }
   }, [roles]);
 
+  // ─── Three-way cell change: enabled / disabled / hidden (/ inherit) ───
+  //
+  // roleId is set for the Roles view and null for a workspace or user.
+  var handleStateChange = useCallback(async function(moduleName, action, roleId, nextState) {
+    if (needsStoredStates(appliesTo, nextState) && statesSupported === false) {
+      setError('The server does not store access states yet, so "' + nextState + '" cannot be saved' +
+        (appliesTo === 'role' ? ' for a role.' : ' for a ' + appliesTo + '.') +
+        ' Enabled and Hidden on roles work today.');
+      return;
+    }
+    var key = 'module:' + moduleName + ':' + action + ':' + (roleId || appliesTo);
+    markSaving(key, true);
+    setError('');
+    try {
+      if (appliesTo === 'role') {
+        var plan = roleChangePlan(nextState);
+        for (var i = 0; i < plan.length; i++) {
+          var step = plan[i];
+          if (step.call === 'grant') await applyGrant(moduleName, action, roleId, true);
+          else if (step.call === 'revoke') await applyGrant(moduleName, action, roleId, false);
+          else if (statesSupported) {
+            await setModuleState({ scope: 'role', scopeId: roleId, module: moduleName, action: action, roleId: roleId,
+              state: step.call === 'setState' ? step.state : null });
+          }
+        }
+        rememberState(stateKey(moduleName, action, roleId), nextState === 'disabled' ? 'disabled' : null);
+      } else {
+        await setModuleState({ scope: appliesTo, scopeId: scopeId, module: moduleName, action: action,
+          state: nextState === 'inherit' ? null : nextState });
+        rememberState(stateKey(moduleName, action), nextState === 'inherit' ? null : nextState);
+      }
+    } catch (err) {
+      setError(err.message);
+    } finally {
+      markSaving(key, false);
+    }
+  }, [roles, appliesTo, scopeId, statesSupported]);
+
+  function rememberState(k, state) {
+    setStoredStates(function(prev) {
+      var next = { ...prev };
+      if (state) next[k] = state; else delete next[k];
+      return next;
+    });
+  }
+
+  var setAppliesTo = useCallback(function(scope) {
+    setAppliesToState(scope);
+    setScopeIdState('');
+    setError('');
+    if (scope === 'user' && users.length === 0) {
+      getUsers().then(function(list) { setUsers(list || []); }).catch(function(err) { setError(err.message); });
+    }
+    loadStates(scope, '');
+  }, [users]);
+
+  var setScopeId = useCallback(function(id) {
+    setScopeIdState(id);
+    loadStates(appliesTo, id);
+  }, [appliesTo]);
+
   // ─── Single item toggle (for uncategorized) ───
   var handleItemToggle = useCallback(async function(type, itemId, roleId, currentlyAssigned) {
     var key = 'item:' + type + ':' + itemId + ':' + roleId;
@@ -209,7 +327,7 @@ export function useAccessMatrixController() {
   }
 
   function isModuleSaving(moduleName, action, roleId) {
-    return !!saving['module:' + moduleName + ':' + action + ':' + roleId];
+    return !!saving['module:' + moduleName + ':' + action + ':' + (roleId || appliesTo)];
   }
 
   function isItemSaving(type, itemId, roleId) {
@@ -235,7 +353,15 @@ export function useAccessMatrixController() {
     loading,
     error,
     handleModuleToggle,
+    handleStateChange,
     handleItemToggle,
+    appliesTo,
+    setAppliesTo,
+    scopeId,
+    setScopeId,
+    workspaces,
+    users,
+    statesSupported,
     isItemAssigned,
     isModuleSaving,
     isItemSaving,

package/src/useMasterSettingsController.js

@@ -1,5 +1,6 @@
 import { useState, useEffect, useMemo, useCallback } from 'react';
-import { getMasterItems, saveMasterItem, deleteMasterItem } from './masterApi.js';
+import { getMasterItems, saveMasterItem, deleteMasterItem, setApiScope } from './masterApi.js';
+import { useAccess } from './AccessContext.jsx';
 
 var TABS = [
   { key: 'roles', label: 'Roles', fields: [{ key: 'name', label: 'Name', required: true }] },
@@ -33,6 +34,12 @@ export function useMasterSettingsController() {
   var [saving, setSaving] = useState(false);
   var [editingItem, setEditingItem] = useState(null);
   var [editForm, setEditForm] = useState({});
+  var [scopeSaving, setScopeSaving] = useState({});
+
+  // Only Super Admin sees the "Super Admin only" switch at all; the server
+  // refuses the change for anyone else anyway.
+  var access = useAccess();
+  var isSuperAdmin = !!(access && access.hasRole && access.hasRole('Super Admin'));
 
   useEffect(function() {
     loadItems(activeTab);
@@ -153,6 +160,27 @@ export function useMasterSettingsController() {
     }
   }
 
+  // Move an API in or out of system scope. Effective at once on the server.
+  async function handleScopeToggle(item) {
+    var next = item.scope === 'system' ? 'company' : 'system';
+    setScopeSaving(function(prev) { var n = { ...prev }; n[item.id] = true; return n; });
+    setError('');
+    try {
+      await setApiScope(item.id, next);
+      setItems(function(prev) {
+        var n = { ...prev };
+        n.apis = (n.apis || []).map(function(x) { return x.id === item.id ? { ...x, scope: next } : x; });
+        return n;
+      });
+    } catch (err) {
+      setError(err.message);
+    } finally {
+      setScopeSaving(function(prev) { var n = { ...prev }; delete n[item.id]; return n; });
+    }
+  }
+
+  function isScopeSaving(id) { return !!scopeSaving[id]; }
+
   async function handleDelete(id) {
     setSaving(true);
     setError('');
@@ -194,6 +222,9 @@ export function useMasterSettingsController() {
     updateField,
     handleSave,
     handleDelete,
+    isSuperAdmin,
+    handleScopeToggle,
+    isScopeSaving,
     reload: function() { loadItems(activeTab); },
   };
 }

package/src/useUserRolesController.js

@@ -1,5 +1,6 @@
 import { useState, useEffect, useMemo, useCallback } from 'react';
 import { getUsers, getRoles, toggleUserRole } from './adminApi.js';
+import { saveMasterItem } from './masterApi.js';
 
 export function useUserRolesController() {
   var [users, setUsers] = useState([]);
@@ -8,6 +9,8 @@ export function useUserRolesController() {
   var [loading, setLoading] = useState(true);
   var [error, setError] = useState('');
   var [saving, setSaving] = useState({});
+  var [newRoleName, setNewRoleName] = useState('');
+  var [creatingRole, setCreatingRole] = useState(false);
 
   useEffect(function() {
     loadData();
@@ -62,6 +65,25 @@ export function useUserRolesController() {
     }
   }, [roles]);
 
+  // A new role becomes a column here and in the Access Matrix: both read the
+  // role list from the server. Creating one is Super Admin only; anyone else
+  // gets the server's refusal as the error.
+  var createRole = useCallback(async function() {
+    var name = newRoleName.trim();
+    if (!name) return;
+    setCreatingRole(true);
+    setError('');
+    try {
+      var made = await saveMasterItem('roles', { name: name });
+      setRoles(function(prev) { return prev.concat([{ id: made.id, name: name }]); });
+      setNewRoleName('');
+    } catch (err) {
+      setError(err.message);
+    } finally {
+      setCreatingRole(false);
+    }
+  }, [newRoleName]);
+
   function isAssigned(user, roleId) {
     return user.roles && user.roles.some(function(r) { return r.id === roleId; });
   }
@@ -76,6 +98,10 @@ export function useUserRolesController() {
     saving,
     handleToggle,
     isAssigned,
+    newRoleName,
+    setNewRoleName,
+    creatingRole,
+    createRole,
     reload: loadData,
   };
 }

package/src/validateDesign.js

@@ -99,12 +99,14 @@ export var PROFILE_RULES = [
 
 export var USER_ROLES_MATRIX_RULES = [
   { id: 'xeplr-admin-user-search', label: 'User search input' },
-  { role: 'grid', label: 'Matrix grid table' }
+  { role: 'grid', label: 'Matrix grid table' },
+  { id: 'xeplr-admin-new-role', label: 'New role name input' }
 ];
 
 export var ACCESS_MATRIX_RULES = [
   { id: 'xeplr-admin-access-search', label: 'Access search input' },
-  { role: 'tablist', label: 'Tab list for Modules/Uncategorized' }
+  { role: 'tablist', label: 'Tab list for Modules/Uncategorized' },
+  { id: 'xeplr-admin-access-scope', label: 'Applies to: Roles / Workspace / User (role="radiogroup")' }
 ];
 
 export var MASTER_SETTINGS_RULES = [