@xeplr/ui-account 1.0.1 → 1.0.2

package/package.json

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

package/src/AccessContext.jsx

@@ -1,14 +1,16 @@
-import { createContext, useContext, useState, useEffect } from 'react';
+import { createContext, useContext, useState, useEffect, useRef } from 'react';
+import { raiseSnackbar } from '@xeplr/ui-utils';
 import { getToken, getUser } from './token.js';
-import { logoutUser } from './api.js';
+import { logoutUser, getMe, setSessionExpiredHandler } from './api.js';
 
 const AccessContext = createContext(null);
 
 /**
  * AccessProvider — wraps your app to provide access state.
  *
- * On mount, loads access from localStorage (set during login).
- * Provides helpers: hasPage, hasApi, hasMenu, hasElement, hasRole.
+ * Seeds from localStorage (written at login) and then RE-READS IT FROM THE
+ * SERVER on mount. Provides helpers: hasPage, hasApi, hasMenu, hasElement,
+ * hasRole.
  *
  * Usage:
  *   <AccessProvider>
@@ -57,6 +59,85 @@ export function AccessProvider({ children }) {
     setAccess(result.access);
   }
 
+  // ── re-read access from the server ──────────────────────────────────
+  //
+  // WHAT THIS FIXES. `access` was written to localStorage at login and read
+  // once, here, forever after. So it was a snapshot of what the user could see
+  // at the moment they signed in — and nothing on the server could change it.
+  // Seed a menu, grant a role, take a page away: none of it reached a
+  // signed-in browser until that person happened to log out, which could be
+  // weeks. Restarting the API did not help, because the API was never the
+  // thing holding the stale copy.
+  //
+  // It went unnoticed because the failure is silent in exactly the wrong
+  // direction: useNavController drops a drawer item whose name is not in
+  // `access.menus` without an error, so a new page simply is not in the rail
+  // and nothing anywhere says why.
+  //
+  // ON MOUNT, which on a SPA means once per full page load. That is the
+  // shortest honest promise: a change lands on next reload rather than next
+  // login.
+  /**
+   * Ask the server again. Also exposed on the context, so a screen that CHANGES
+   * access can show its own effect — the access matrix is the obvious one: an
+   * admin who grants a role and sees nothing happen has no way to tell a saved
+   * change from a broken one.
+   *
+   * Resolves either way. A caller awaiting it is waiting for "we tried", not
+   * for "it worked" — there is nothing useful for a nav bar to do about a
+   * failed refresh except carry on with what it had.
+   */
+  async function refreshAccess() {
+    try {
+      const result = await getMe();
+      if (!result) return null;
+      // REPLACED, not merged. Access is the whole answer to "what may this
+      // person see", and merging would keep a page that has just been revoked
+      // — the direction you least want to be wrong in.
+      if (result.access) setAccess(result.access);
+      if (result.user) setUser(result.user);
+      return result.access || null;
+    } catch (err) {
+      // KEEP WHAT WE HAVE. A network blip, a restarting API, a laptop that woke
+      // up on a train — none of those mean the user lost their permissions, and
+      // blanking `access` would empty the nav and bounce them out of the page
+      // they were reading. A genuinely dead session is handled separately, by
+      // the setSessionExpiredHandler(logout) effect below.
+      //
+      // But silently keeping stale state used to mean silently keeping the
+      // user in the dark too — this used to fail with zero indication
+      // anything was wrong. Still don't blank anything; just say so.
+      raiseSnackbar(err.message || 'Could not reach the server to refresh your access.', { design: 'error' });
+      return null;
+    }
+  }
+
+  // A dead session (refresh token missing, or rejected) is discovered inside
+  // authFetch — outside React entirely — which can wipe localStorage but has
+  // no way to flip THIS component's `authenticated` state on its own. Without
+  // this, clearAuth() runs and nothing downstream ever notices: ProtectedRoute
+  // keeps reading a stale `authenticated: true` and the app just sits there
+  // throwing errors on every call instead of bouncing to login.
+  useEffect(() => {
+    setSessionExpiredHandler(logout);
+    return () => setSessionExpiredHandler(null);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const refreshedRef = useRef(false);
+  useEffect(() => {
+    // Nothing to refresh for a signed-out visitor, and asking would be a 401 on
+    // every login screen.
+    if (!authenticated) return;
+    // StrictMode double-invokes effects in development. One request, not two.
+    // Not reset on logout either: signing back in goes through onLogin, which
+    // already carries fresh access from the login response.
+    if (refreshedRef.current) return;
+    refreshedRef.current = true;
+    refreshAccess();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [authenticated]);
+
   // Access checkers
   function hasPage(pageName) {
     if (!access) return false;
@@ -90,6 +171,7 @@ export function AccessProvider({ children }) {
     onLogin,
     logout,
     setAccess,
+    refreshAccess,
     hasPage,
     hasApi,
     hasMenu,

package/src/ProtectedRoute.jsx

@@ -1,5 +1,6 @@
-import { Navigate } from 'react-router-dom';
+import { Navigate, useLocation } from 'react-router-dom';
 import { useAccessStrict } from './AccessContext.jsx';
+import { saveReturnTo } from './returnTo.js';
 
 /**
  * ProtectedRoute — guards a route based on auth and access.
@@ -35,8 +36,10 @@ export function ProtectedRoute({
   deniedPath = '/auth/login'
 }) {
   const { authenticated, hasPage, hasRole } = useAccessStrict();
+  const location = useLocation();
 
   if (!authenticated) {
+    saveReturnTo(location);
     return <Navigate to={loginPath} replace />;
   }
 

package/src/activeScope.js

@@ -27,6 +27,31 @@ export function setActiveScope(level, scope) {
   } catch (e) {}
 }
 
+const LAST_STORAGE_PREFIX = 'xeplr:lastScope:';
+
+/**
+ * The last value set at a given level, independent of the ACTIVE scope above
+ * and deliberately untouched by clearActiveScope() — so an app can offer to
+ * resume the same company/workspace after a logout without silently
+ * bypassing whatever cleared the active scope. A caller decides whether and
+ * how to re-verify eligibility before trusting this; auth doesn't.
+ */
+export function getLastScope(level) {
+  try {
+    const raw = localStorage.getItem(LAST_STORAGE_PREFIX + level);
+    return raw ? JSON.parse(raw) : null;
+  } catch (e) {
+    return null;
+  }
+}
+
+export function setLastScope(level, scope) {
+  try {
+    if (scope) localStorage.setItem(LAST_STORAGE_PREFIX + level, JSON.stringify(scope));
+    else localStorage.removeItem(LAST_STORAGE_PREFIX + level);
+  } catch (e) {}
+}
+
 /**
  * Clear one level's scope, or every level if omitted (e.g. on logout).
  */

package/src/api.js

@@ -14,13 +14,238 @@ let _refreshPromise = null;
  */
 export function configure(baseUrl, options = {}) {
   _baseUrl = baseUrl;
-  _onSessionExpired = options.onSessionExpired || null;
+  if (options.onSessionExpired) _onSessionExpired = options.onSessionExpired;
+}
+
+/**
+ * Register the session-expired handler on its own, separate from configure().
+ *
+ * configure(baseUrl) runs at module load, before React mounts — AccessProvider
+ * (the thing that actually owns `authenticated` state and a real logout()) does
+ * not exist yet at that point. AccessProvider calls this itself, once, from a
+ * mount effect — so every consumer of this package gets a session-expired
+ * handler wired to its own auth state automatically, without the app having to
+ * remember to pass onSessionExpired through configure() by hand.
+ */
+export function setSessionExpiredHandler(fn) {
+  _onSessionExpired = fn || null;
 }
 
 function getBaseUrl() {
   return _baseUrl || '';
 }
 
+/**
+ * How much of an unreadable body to keep. Enough to recognise a login page, a
+ * proxy's 502 template or a stack trace; not so much that one bad response
+ * fills the console and buries the request that caused it.
+ */
+const BODY_SNIPPET_LIMIT = 600;
+
+/**
+ * What the body looks like, said in one word.
+ *
+ * Nine times in ten the answer is already here — "it's an HTML page" means a
+ * proxy or a dev server answered instead of the API, and "it's empty" means
+ * the connection closed before anything was written. Naming the shape saves
+ * reading the snippet at all.
+ */
+function describeBody(text, contentType) {
+  const body = (text || '').trim();
+  if (!body) return 'the body was empty';
+  const head = body.slice(0, 200).toLowerCase();
+  if (head.startsWith('<!doctype html') || head.startsWith('<html')) {
+    return 'the body is an HTML page, not JSON — something other than the API answered (a proxy, a dev server, or a login redirect)';
+  }
+  if (head.startsWith('<')) return 'the body is markup, not JSON';
+  if (head.startsWith('<?xml')) return 'the body is XML, not JSON';
+  if (contentType && contentType.indexOf('json') === -1) {
+    return `the body is ${contentType}, not JSON`;
+  }
+  return 'the body starts like JSON but does not parse — it is probably truncated';
+}
+
+/**
+ * res.json() throws a raw, user-facing-unfriendly SyntaxError ("Unexpected
+ * end of JSON input") when the body isn't valid JSON — a restarting API, a
+ * proxy timeout, or an unhandled exception upstream (e.g. a downstream DB
+ * dependency being down) all produce exactly this. Every caller of authFetch/
+ * request needs a real Error with a message worth showing, not a parser
+ * crash — this is the one place that guarantees it.
+ *
+ * ── and it has to say WHY, not only that ────────────────────────────────
+ *
+ * "The server sent back something we could not read" is a fine sentence for
+ * the person using the app and useless to the person fixing it. It is the same
+ * sentence whether the API was restarting, a proxy returned its own HTML error
+ * page, the response was truncated mid-flight, or an auth redirect landed the
+ * login page on a JSON endpoint — four different problems with four different
+ * fixes, reported identically. Somebody then has to reproduce it with devtools
+ * open to learn what a failed request already knew.
+ *
+ * So the console gets everything the moment it happens: which request, the
+ * status, the content type, how many bytes arrived, what the body appears to
+ * be, and the first {BODY_SNIPPET_LIMIT} characters of it verbatim. Same
+ * bargain the movement log makes — the sentence is for a human, the facts are
+ * for whoever has to answer for it, and neither replaces the other.
+ *
+ * Read via text() rather than json() on purpose: json() consumes the stream,
+ * so by the time it throws the body cannot be read back to find out what it
+ * was. Parsing the text ourselves is the same result on the happy path and
+ * leaves the evidence intact on the unhappy one.
+ */
+async function parseJsonResponse(res, sent) {
+  const contentType = (res.headers && res.headers.get('content-type')) || '';
+  const label = sent ? `${sent.method || 'GET'} ${sent.url || ''}` : (res.url || 'request');
+
+  let text;
+  try {
+    text = await res.text();
+  } catch (e) {
+    // The stream itself failed — a connection dropped mid-body. There is no
+    // snippet to show, and saying so is better than an empty one implying the
+    // server sent nothing.
+    console.error(
+      `[api] ${label} — the response body could not be read (status ${res.status}): ${e.message}`
+    );
+    const err = new Error('The connection dropped while the server was replying. Please try again.');
+    err.status = res.status;
+    return Promise.reject(err);
+  }
+
+  try {
+    // '' is not valid JSON, which is the behaviour we want for a 204 or an
+    // empty error body — it lands in the catch below with "the body was empty"
+    // rather than silently becoming null.
+    return JSON.parse(text);
+  } catch (e) {
+    const shape = describeBody(text, contentType);
+    const snippet = (text || '').slice(0, BODY_SNIPPET_LIMIT);
+
+    // console.error, not warn: nothing downstream can recover from this, and a
+    // warning is what people filter out.
+    console.error(
+      `[api] ${label} — could not read the reply as JSON.\n` +
+      `      status       : ${res.status}${res.statusText ? ' ' + res.statusText : ''}\n` +
+      `      content-type : ${contentType || '(none sent)'}\n` +
+      `      body length  : ${(text || '').length} character(s)\n` +
+      `      looks like   : ${shape}\n` +
+      `      parser said  : ${e.message}\n` +
+      `      body starts  : ${snippet || '(nothing)'}` +
+      ((text || '').length > BODY_SNIPPET_LIMIT ? `\n      (truncated — ${(text || '').length - BODY_SNIPPET_LIMIT} more character(s))` : '')
+    );
+
+    const err = new Error(
+      res.ok
+        ? `The server sent back something we could not read (${shape}). Please try again.`
+        : `The server is not responding correctly (status ${res.status}). It may be restarting — please try again in a moment.`
+    );
+    // Carried on the error as well as logged: a caller that wants to show the
+    // detail in a snackbar, or attach it to a bug report, should not have to
+    // ask the user to open devtools and copy a console line.
+    err.status = res.status;
+    err.contentType = contentType || null;
+    err.rawBody = snippet;
+    err.bodyLength = (text || '').length;
+    err.parseError = e.message;
+    err.request = label;
+    throw err;
+  }
+}
+
+/**
+ * The most useful sentence in a failed response.
+ *
+ * `error` is a STRING on a handled refusal ("Not authorized for companyId …")
+ * and an OBJECT on an unhandled one — the framework's error handler sends
+ * { code, message, error: { name, message, nativeError } }. This used to be
+ * `data.error || 'Something went wrong'`, which for the object case built
+ * `new Error({...})` and produced the message "[object Object]".
+ *
+ * That is the worst possible outcome for the one place every request funnels
+ * through: the server said "column reportTimezone of relation cubes does not
+ * exist" and the screen said nothing at all. Every caller shows err.message,
+ * so what this picks is what the user is told.
+ *
+ * Order matters. The nested `error.message` is the specific one; `message` at
+ * the top level is usually the generic "Internal server error" that would tell
+ * somebody nothing.
+ */
+function errorMessage(data) {
+  if (!data) return 'Something went wrong';
+  if (typeof data.error === 'string' && data.error) return data.error;
+  if (data.error && typeof data.error.message === 'string' && data.error.message) {
+    return data.error.message;
+  }
+  if (typeof data.message === 'string' && data.message) return data.message;
+  return 'Something went wrong';
+}
+
+/**
+ * The Error every failed request throws — carrying WHY, not just what.
+ *
+ * `new Error(message)` discards the status code and the response body, so
+ * every caller could see the sentence and nothing else. That flattens two very
+ * different things into one: "you did something wrong" and "this is not ready
+ * yet, ask again shortly".
+ *
+ * It cost a real bug. A cube profile answers 409 with `busy: true` while a
+ * table is still being copied — a WAIT — and the screen rendered it as a red
+ * error banner, so a table doing exactly what it should looked like a failure
+ * and stopped the user.
+ *
+ * So the status and the body ride along. Existing callers read `err.message`
+ * and are unaffected; callers that care can now tell a 409 from a 400.
+ */
+function httpError(data, res, sent) {
+  const err = new Error(errorMessage(data));
+  err.status = res ? res.status : 0;
+  err.body = data || null;
+  // Hoisted for the flags a server sets deliberately, so a caller writes
+  // `err.busy` rather than `err.body && err.body.busy`.
+  if (data && typeof data === 'object') {
+    if (data.busy !== undefined) err.busy = data.busy;
+    if (data.code !== undefined) err.code = data.code;
+  }
+
+  // ── WHICH REQUEST FAILED, said out loud, every time ────────────────────
+  //
+  // The thrown Error carries a sentence, and a sentence is all the snackbar
+  // shows: "Not authorized for companyId", "column reportTimezone does not
+  // exist". Neither says which URL produced it — and the same sentence can
+  // come from several endpoints, so the first question after seeing one is
+  // always "coming from where?", answered today by opening the network tab
+  // and reproducing it.
+  //
+  // Every failure funnels through here, so this is the one place that can
+  // answer it for free. A failed request is rare by definition; there is no
+  // volume argument for staying quiet about it.
+  //
+  // `res.url` is the resolved, final URL — after redirects — which is
+  // occasionally the actual answer (a request that ended up somewhere other
+  // than the API is exactly why the reply did not parse).
+  const label = sent
+    ? `${sent.method || 'GET'} ${sent.url || ''}`
+    : ((res && res.url) || 'request');
+  err.request = label;
+
+  const detail = data && typeof data === 'object' && data.error && typeof data.error === 'object'
+    ? data.error
+    : null;
+
+  console.error(
+    `[api] ${label} failed — ${res ? res.status : 0}${res && res.statusText ? ' ' + res.statusText : ''}: ${err.message}` +
+    (err.code !== undefined ? `\n      code   : ${err.code}` : '') +
+    (err.busy !== undefined ? `\n      busy   : ${err.busy}` : '') +
+    // The server's own error object when it sent one — the name and the
+    // native database/driver message under the friendly sentence.
+    (detail && detail.name ? `\n      name   : ${detail.name}` : '') +
+    (detail && detail.nativeError ? `\n      native : ${typeof detail.nativeError === 'string' ? detail.nativeError : JSON.stringify(detail.nativeError)}` : '')
+  );
+
+  return err;
+}
+
 /**
  * Refresh the access token using the stored refresh token.
  * Returns true if refresh succeeded, false if session is dead.
@@ -32,7 +257,14 @@ async function refreshAccessToken() {
 
   _refreshPromise = (async () => {
     const refreshToken = getRefreshToken();
-    if (!refreshToken) return false;
+    if (!refreshToken) {
+      // No refresh token to even try — this session is just as dead as one
+      // where the refresh call gets rejected below, and needs the same
+      // cleanup + notification, not a silent no-op.
+      clearAuth();
+      if (_onSessionExpired) _onSessionExpired();
+      return false;
+    }
 
     try {
       const res = await fetch(`${getBaseUrl()}/auth/api/refresh`, {
@@ -121,9 +353,9 @@ export async function authFetch(endpoint, options = {}) {
     }
   }
 
-  const data = await res.json();
+  const data = await parseJsonResponse(res, { method: options.method || 'GET', url: url });
   if (!res.ok) {
-    throw new Error(data.error || 'Something went wrong');
+    throw httpError(data, res, { method: options.method || 'GET', url: url });
   }
   return data;
 }
@@ -136,9 +368,10 @@ async function request(endpoint, options = {}) {
     headers: { 'Content-Type': 'application/json' },
     ...options,
   });
-  const data = await res.json();
+  const requested = { method: options.method || 'GET', url: `${getBaseUrl()}${endpoint}` };
+  const data = await parseJsonResponse(res, requested);
   if (!res.ok) {
-    throw new Error(data.error || 'Something went wrong');
+    throw httpError(data, res, requested);
   }
   return data;
 }
@@ -150,8 +383,14 @@ export function registerUser({ email, password, name, phoneNumber }) {
   });
 }
 
-export function activateAccount(token) {
-  return request('/auth/api/activate?token=' + encodeURIComponent(token));
+export function activateAccount(token, workflowKey) {
+  // workflowKey travels in the activation link and is handed straight back —
+  // it releases a workflow step that was waiting for this person to activate
+  // (see @xeplr/auth's configureWorkflowResume). Absent for an ordinary
+  // registration, and the server treats it as optional.
+  var url = '/auth/api/activate?token=' + encodeURIComponent(token);
+  if (workflowKey) url += '&workflowKey=' + encodeURIComponent(workflowKey);
+  return request(url);
 }
 
 export function loginUser({ email, password }) {
@@ -182,6 +421,22 @@ export function changePassword({ currentPassword, newPassword }) {
   });
 }
 
+/**
+ * WHO AM I AND WHAT MAY I SEE — answered fresh by the server.
+ *
+ * Returns { user, access }. The same object login hands back, which is the
+ * point: it is the one shape AccessProvider stores, so re-reading it is a
+ * replacement rather than a merge.
+ *
+ * Exists because access was written to localStorage at login and never read
+ * again from anywhere else. Grant somebody a role, seed a menu, take a page
+ * away — none of it reached a signed-in browser until that person happened to
+ * log out, which could be weeks. See AccessProvider.
+ */
+export function getMe() {
+  return authFetch('/auth/api/me');
+}
+
 export function getProfile() {
   return authFetch('/auth/api/profile');
 }
@@ -211,9 +466,10 @@ export async function uploadAvatar(file) {
     headers,
     body: formData,
   });
-  const data = await res.json();
+  const avatarRequest = { method: 'POST', url: `${getBaseUrl()}/auth/api/profile/avatar` };
+  const data = await parseJsonResponse(res, avatarRequest);
   if (!res.ok) {
-    throw new Error(data.error || 'Something went wrong');
+    throw httpError(data, res, avatarRequest);
   }
   return data;
 }

package/src/designs/NavDrawer.jsx

@@ -34,10 +34,24 @@ function bucketItems(items) {
 
 function NavDrawer({
   drawerOpen, toggleDrawer, drawerItems, expandedLogo, logo, drawerPromo,
-  user, accountItems, notifications, accountOpen, toggleAccount, closeAccount, accountRef, logout
+  user, accountItems, notifications, accountOpen, toggleAccount, closeAccount, accountRef, logout,
+  hideFooterIcons,
+  drawerWidth, drawerResizing, startDrawerResize, resetDrawerWidth, nudgeDrawerWidth, drawerWidthBounds
 }) {
   var [query, setQuery] = useState('');
 
+  var bounds = drawerWidthBounds || { min: 180, max: 480, step: 16 };
+
+  // Arrow keys resize, Home/End jump to the stops — the handle is focusable,
+  // so everything the drag does has to be reachable from the keyboard too.
+  function onResizeKeyDown(e) {
+    if (e.key === 'ArrowLeft') { e.preventDefault(); nudgeDrawerWidth(-bounds.step); }
+    else if (e.key === 'ArrowRight') { e.preventDefault(); nudgeDrawerWidth(bounds.step); }
+    else if (e.key === 'Home') { e.preventDefault(); nudgeDrawerWidth(-Infinity); }
+    else if (e.key === 'End') { e.preventDefault(); nudgeDrawerWidth(Infinity); }
+    else if (e.key === 'Enter') { e.preventDefault(); resetDrawerWidth(); }
+  }
+
   var visibleItems = useMemo(function() {
     if (!drawerOpen || !query.trim()) return drawerItems;
     var q = query.trim().toLowerCase();
@@ -47,22 +61,51 @@ function NavDrawer({
   var buckets = useMemo(function() { return bucketItems(visibleItems); }, [visibleItems]);
 
   function renderItem(item) {
+    // A COUNT THAT HAS TO BE SEEN FROM WHEREVER YOU ARE.
+    //
+    // Optional `item.badge` — a number or a short string. It renders as a pill
+    // beside the label when the drawer is expanded and as a dot on the icon
+    // when it is collapsed, because the collapsed rail is the state most
+    // people leave it in and a badge only visible when expanded is a badge
+    // that does not do its job.
+    //
+    // 0, null and undefined all render NOTHING. A pill reading "0" is noise
+    // that trains people to stop looking at the pill.
+    var badge = item.badge === 0 || item.badge == null || item.badge === '' ? null : item.badge;
     return (
       <button
         key={item.name}
         type="button"
-        className="xeplr-nav-drawer-link"
+        className={'xeplr-nav-drawer-link' + (badge ? ' xeplr-nav-drawer-link-badged' : '')}
         onClick={item.clickHandler}
-        title={item.name}
+        // The count belongs in the tooltip too — the collapsed dot says
+        // "something", and the hover has to say how many.
+        title={badge ? item.name + ' (' + badge + ')' : item.name}
       >
-        {item.icon && <span className="xeplr-nav-drawer-icon">{item.icon}</span>}
+        {item.icon && (
+          <span className="xeplr-nav-drawer-icon">
+            {item.icon}
+            {badge && !drawerOpen && <span className="xeplr-nav-drawer-dot" aria-hidden="true" />}
+          </span>
+        )}
         {drawerOpen && <span className="xeplr-nav-drawer-label">{item.name}</span>}
+        {drawerOpen && badge && <span className="xeplr-nav-drawer-badge">{badge}</span>}
       </button>
     );
   }
 
   return (
-    <aside className={'xeplr-nav-drawer' + (drawerOpen ? ' xeplr-nav-drawer-expanded' : ' xeplr-nav-drawer-collapsed')}>
+    <aside
+      className={
+        'xeplr-nav-drawer'
+        + (drawerOpen ? ' xeplr-nav-drawer-expanded' : ' xeplr-nav-drawer-collapsed')
+        + (drawerResizing ? ' xeplr-nav-drawer-resizing' : '')
+      }
+      /* Inline width ONLY when expanded — collapsed is the fixed icon rail and
+         nav.css keeps owning that number. Inline because it changes per
+         pointermove; a stylesheet cannot express a live drag. */
+      style={drawerOpen && drawerWidth ? { width: drawerWidth + 'px' } : undefined}
+    >
       <button
         type="button"
         className="xeplr-nav-drawer-toggle"
@@ -70,12 +113,19 @@ function NavDrawer({
         aria-label={drawerOpen ? 'Collapse menu' : 'Expand menu'}
         aria-expanded={drawerOpen}
       >
-        {logo && <img src={logo} alt="" className="xeplr-nav-drawer-logo" />}
+        {/* ONE MARK AT A TIME.
+            expandedLogo is a stacked icon+wordmark lockup — it CONTAINS this
+            icon — so rendering both put the same mark on screen twice, one
+            above the other. Collapsed, the icon is the brand and the thing you
+            click to expand; open, the lockup is the brand and this is only the
+            collapse control, which the chevron says better than a second copy
+            of the logo. */}
+        {drawerOpen && expandedLogo
+          ? <span className="xeplr-nav-drawer-collapse" aria-hidden="true">«</span>
+          : (logo && <img src={logo} alt="" className="xeplr-nav-drawer-logo" />)}
       </button>
-      {/* Own row below the toggle, not squeezed inline beside it — expandedLogo
-          is typically a stacked icon+wordmark lockup (near-square, not a wide
-          banner), so it needs real height to stay legible, not the icon's 22px.
-          Additive, not a swap of the toggle's own image — no flicker either way. */}
+      {/* Own row below the toggle, not squeezed inline beside it — a stacked
+          lockup needs real height to stay legible, not the icon's 22px. */}
       {drawerOpen && expandedLogo && (
         <img src={expandedLogo} alt="" className="xeplr-nav-drawer-expanded-logo" />
       )}
@@ -105,15 +155,38 @@ function NavDrawer({
 
       {drawerOpen && drawerPromo && <div className="xeplr-nav-drawer-promo">{drawerPromo}</div>}
 
-      <div className="xeplr-nav-drawer-footer">
-        <NotificationsBell notifications={notifications} label={drawerOpen ? 'Notifications' : undefined} />
-        <AccountMenu
-          placement="top" triggerLabel={drawerOpen ? 'Settings' : undefined}
-          user={user} accountItems={accountItems}
-          accountOpen={accountOpen} toggleAccount={toggleAccount} closeAccount={closeAccount}
-          accountRef={accountRef} logout={logout}
+      {!hideFooterIcons && (
+        <div className="xeplr-nav-drawer-footer">
+          <NotificationsBell notifications={notifications} label={drawerOpen ? 'Notifications' : undefined} />
+          <AccountMenu
+            placement="top" triggerLabel={drawerOpen ? 'Settings' : undefined}
+            user={user} accountItems={accountItems}
+            accountOpen={accountOpen} toggleAccount={toggleAccount} closeAccount={closeAccount}
+            accountRef={accountRef} logout={logout}
+          />
+        </div>
+      )}
+
+      {/* LAST child and absolutely positioned, so it sits over the drawer's
+          right border at any height without taking part in the column layout
+          above it. Only when expanded: there is nothing to widen on a 60px
+          icon rail, and a resize handle there would just fight the toggle. */}
+      {drawerOpen && (
+        <div
+          className="xeplr-nav-drawer-resize"
+          role="separator"
+          aria-orientation="vertical"
+          aria-label="Resize menu"
+          aria-valuenow={drawerWidth}
+          aria-valuemin={bounds.min}
+          aria-valuemax={bounds.max}
+          tabIndex={0}
+          onPointerDown={startDrawerResize}
+          onDoubleClick={resetDrawerWidth}
+          onKeyDown={onResizeKeyDown}
+          title="Drag to resize — double-click to reset"
         />
-      </div>
+      )}
     </aside>
   );
 }

package/src/designs/NavFloatingSettings.jsx

@@ -0,0 +1,25 @@
+import { memo } from 'react';
+import AccountMenu from './AccountMenu.jsx';
+import NotificationsBell from './NotificationsBell.jsx';
+import './nav.css';
+
+// A minimal top-right overlay — just the notifications bell + account/settings
+// trigger, no logo/middle slot/header bar around them. Opt-in via NavPage's
+// `floatingSettings` prop, for layouts (e.g. an icon drawer) that want these
+// two floating over the page instead of pinned to the drawer's own footer.
+function NavFloatingSettings({
+  user, accountItems, notifications, accountOpen, toggleAccount, closeAccount, accountRef, logout
+}) {
+  return (
+    <div className="xeplr-nav-floating">
+      <NotificationsBell notifications={notifications} />
+      <AccountMenu
+        user={user} accountItems={accountItems}
+        accountOpen={accountOpen} toggleAccount={toggleAccount} closeAccount={closeAccount}
+        accountRef={accountRef} logout={logout}
+      />
+    </div>
+  );
+}
+
+export default memo(NavFloatingSettings);

package/src/designs/index.js

@@ -12,4 +12,5 @@ export { default as MasterSettingsSample } from './MasterSettingsSample.jsx';
 export { default as NavTopSample } from './NavTopSample.jsx';
 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';

package/src/designs/nav.css

@@ -197,7 +197,18 @@
   position: fixed;
   top: 0;
   left: 0;
-  z-index: 90;
+  /* ABOVE .xeplr-nav-floating (400). Both are global chrome, so the tie goes
+     to the one being operated: widen the drawer and it reaches under the
+     floating bell/settings in the top-right corner, where those two icons
+     swallow clicks meant for the drawer — the resize handle's top edge
+     included. The floating cluster keeps 400 and still outranks page-level
+     chrome, which is what that value is actually for.
+
+     THE CEILING THIS SETS: a real full-screen modal must out-stack this, or
+     the rail punches through it. Consumers with one are expected to sit above
+     500 — xeplr-bi's .dsh-expanded-backdrop was moved to 600 when this
+     changed. */
+  z-index: 500;
   display: flex;
   flex-direction: column;
   height: 100vh;
@@ -210,8 +221,52 @@
 }
 
 .xeplr-nav-drawer-collapsed { width: 60px; }
+/* The 240px is the DEFAULT only — NavDrawer sets an inline width from the
+   remembered drag, which outranks this. Kept here so the drawer still has a
+   sane width if the controller's stored value is unreadable. */
 .xeplr-nav-drawer-expanded { width: 240px; padding: 16px; }
 
+/* Mid-drag the width changes every pointermove, and a 0.15s transition on it
+   means the edge chases the cursor instead of tracking it. Kill it for the
+   duration; the toggle animation is unaffected because it never coincides
+   with a drag. */
+.xeplr-nav-drawer-resizing { transition: none; }
+
+/* ── the resize handle ─────────────────────────────────────────────────
+   Straddles the right border (right: -3px on a 6px strip) rather than sitting
+   inside it, so the grab target covers the edge the user is actually aiming
+   at — an inside-only strip makes you undershoot into the nav. */
+.xeplr-nav-drawer-resize {
+  position: absolute;
+  top: 0;
+  right: -3px;
+  width: 6px;
+  height: 100%;
+  cursor: col-resize;
+  /* Invisible until wanted: an always-on divider line reads as a border and
+     invites clicks that do nothing. */
+  background: transparent;
+  transition: background 0.12s;
+  /* Above the drawer's own content so the grab always lands on the handle.
+     Local to the drawer's stacking context, so it stays under the footer's
+     account popup rather than competing with the page. */
+  z-index: 1;
+}
+.xeplr-nav-drawer-resize:hover,
+.xeplr-nav-drawer-resize:focus-visible,
+.xeplr-nav-drawer-resizing .xeplr-nav-drawer-resize {
+  background: var(--xeplr-accent, #2563eb);
+}
+/* The focus ring would be a 6px sliver and easy to miss; the accent fill above
+   is the visible focus state, so the default outline only gets in its way. */
+.xeplr-nav-drawer-resize:focus-visible { outline: none; }
+
+/* Set on <body> for the length of the drag (see useNavController). A drag
+   routinely outruns the 6px handle, and without this the cursor flips back to
+   a caret and the page starts blue-selecting the moment it does. */
+body.xeplr-nav-resizing { user-select: none; }
+body.xeplr-nav-resizing * { cursor: col-resize !important; }
+
 .xeplr-nav-drawer-toggle {
   display: block;
   flex-shrink: 0;
@@ -222,6 +277,23 @@
   cursor: pointer;
   align-self: flex-start;
 }
+/* CENTRED WHEN COLLAPSED, like everything under it.
+   The rail's links get `justify-content: center`, so their icons sit in the
+   middle of the 40px of content width. The toggle had `padding: 0` and
+   `align-self: flex-start`, which pinned the logo hard against the left edge —
+   so the mark and the first menu icon were visibly on two different vertical
+   lines, which is the one thing a rail of icons cannot afford. */
+.xeplr-nav-drawer-collapsed .xeplr-nav-drawer-toggle { align-self: center; }
+
+/* The collapse affordance, when the lockup below is carrying the brand. */
+.xeplr-nav-drawer-collapse {
+  display: block;
+  width: 22px;
+  line-height: 22px;
+  text-align: center;
+  font-size: 15px;
+  color: var(--xeplr-text-secondary, #8b8f9a);
+}
 
 /* Fixed, small, and never swapped for a different image (see NavDrawer.jsx) —
    deliberately smaller than the collapsed rail's content width (60px rail -
@@ -289,6 +361,42 @@
 .xeplr-nav-drawer-icon { display: grid; place-items: center; flex-shrink: 0; }
 .xeplr-nav-drawer-label { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 
+/* ── item badges ─────────────────────────────────────────────────────────
+   Optional `item.badge`. The pill takes the remaining width (margin-left
+   auto) so counts line up down the rail instead of tracking label lengths.
+   The label keeps flex:1 so a long name still ellipsises rather than pushing
+   the pill off the edge. */
+.xeplr-nav-drawer-link-badged .xeplr-nav-drawer-label { flex: 1; }
+.xeplr-nav-drawer-badge {
+  margin-left: auto;
+  flex-shrink: 0;
+  min-width: 18px;
+  padding: 1px 6px;
+  border-radius: 9px;
+  background: var(--xeplr-danger, #c0392b);
+  color: #fff;
+  font-size: 11px;
+  font-weight: 600;
+  line-height: 16px;
+  text-align: center;
+}
+/* Collapsed: the rail is icons only, so the count becomes a dot pinned to the
+   icon's corner. `position: relative` on the icon rather than the button
+   because the button is centred and the icon is what the eye is on. */
+.xeplr-nav-drawer-collapsed .xeplr-nav-drawer-icon { position: relative; }
+.xeplr-nav-drawer-dot {
+  position: absolute;
+  top: -2px;
+  right: -3px;
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: var(--xeplr-danger, #c0392b);
+  /* Against the rail's own background, so the dot reads as ON the icon rather
+     than as part of it. */
+  box-shadow: 0 0 0 2px var(--xeplr-bg-elevated, #fff);
+}
+
 .xeplr-nav-drawer-empty { padding: 10px 12px; color: var(--xeplr-text-muted); font-size: 13px; }
 
 .xeplr-nav-drawer-promo { padding-top: 12px; }
@@ -309,3 +417,23 @@
   margin-top: 12px;
   border-top: 1px solid var(--xeplr-border-secondary);
 }
+
+/* Opt-in alternative to the drawer footer above (see NavPage's `floatingSettings`
+   prop) — same bell + account trigger, floating over the page instead of
+   pinned to the drawer. Just the two icons themselves, no card/box around
+   them — no background, border, or shadow.
+
+   z-index sits above page-level floating chrome, not below it. The icons
+   themselves never overlap anything, but the account menu drops DOWN over the
+   page — and a settings menu that opens behind a page toolbar is unusable.
+   Global chrome wins over page tools; a consumer's own floating toolbar
+   should stay below this and position itself clear of the icons. */
+.xeplr-nav-floating {
+  position: fixed;
+  top: 16px;
+  right: 16px;
+  z-index: 400;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}

package/src/index.js

@@ -1,5 +1,5 @@
 // API client
-export { configure, registerUser, loginUser, activateAccount, forgotPassword, resetPassword, changePassword, getProfile, updateProfile, uploadAvatar, logoutUser, authFetch } from './api.js';
+export { configure, setSessionExpiredHandler, registerUser, loginUser, activateAccount, forgotPassword, resetPassword, changePassword, getMe, getProfile, updateProfile, uploadAvatar, logoutUser, authFetch } from './api.js';
 
 // Token helpers
 export { getToken, setToken, getRefreshToken, setRefreshToken, getUser, setUser, clearAuth, isAuthenticated } from './token.js';
@@ -12,7 +12,12 @@ export { registerMTs, getMtConfig } from './mt.js';
 // Active scope (e.g. company/workspace), keyed by MT level (l1, l2, ...) — a
 // bare, app-interpreted value per level, attached to every authFetch call as
 // that level's configured header. See activeScope.js.
-export { getActiveScope, setActiveScope, clearActiveScope } from './activeScope.js';
+export { getActiveScope, setActiveScope, clearActiveScope, getLastScope, setLastScope } from './activeScope.js';
+
+// Where to send the user once a redirect-driven gate (auth, or an app's own
+// gate) resolves — e.g. back to the exact dashboard a deep link pointed at,
+// rather than always home. See returnTo.js.
+export { saveReturnTo, consumeReturnTo } from './returnTo.js';
 
 // Controller hooks
 export { useLoginController } from './useLoginController.js';
@@ -43,7 +48,7 @@ export { getMasterItems, saveMasterItem, deleteMasterItem, MASTER_TYPES } from '
 export { useDesignValidator, LOGIN_RULES, REGISTER_RULES, FORGOT_PASSWORD_RULES, RESET_PASSWORD_RULES, CHANGE_PASSWORD_RULES, PROFILE_RULES, USER_ROLES_MATRIX_RULES, ACCESS_MATRIX_RULES, MASTER_SETTINGS_RULES, NAV_RULES } from './validateDesign.js';
 
 // Sample designs (use as reference or starting point)
-export { LoginSample, RegisterSample, ForgotPasswordSample, ResetPasswordSample, ActivateSample, NotActivatedSample, ChangePasswordSample, ProfileSample, UserRolesMatrixSample, AccessMatrixSample, MasterSettingsSample, NavTopSample, AccountMenu, NavDrawer, NotificationsBell } from './designs/index.js';
+export { LoginSample, RegisterSample, ForgotPasswordSample, ResetPasswordSample, ActivateSample, NotActivatedSample, ChangePasswordSample, ProfileSample, UserRolesMatrixSample, AccessMatrixSample, MasterSettingsSample, NavTopSample, AccountMenu, NavDrawer, NavFloatingSettings, NotificationsBell } from './designs/index.js';
 
 // Ready-made pages (controller + sample design wired together; each takes an optional `design` prop)
 export { LoginPage, RegisterPage, ForgotPasswordPage, ResetPasswordPage, ActivatePage, NotActivatedPage, ChangePasswordPage, ProfilePage, UserRolesPage, AccessMatrixPage, MasterSettingsPage, NavPage } from './pages.jsx';

package/src/pages.jsx

@@ -10,7 +10,7 @@ import { useUserRolesController } from './useUserRolesController.js';
 import { useAccessMatrixController } from './useAccessMatrixController.js';
 import { useMasterSettingsController } from './useMasterSettingsController.js';
 import { useNavController } from './useNavController.js';
-import { LoginSample, RegisterSample, ForgotPasswordSample, ResetPasswordSample, ActivateSample, NotActivatedSample, ChangePasswordSample, ProfileSample, UserRolesMatrixSample, AccessMatrixSample, MasterSettingsSample, NavTopSample, NavDrawer } from './designs/index.js';
+import { LoginSample, RegisterSample, ForgotPasswordSample, ResetPasswordSample, ActivateSample, NotActivatedSample, ChangePasswordSample, ProfileSample, UserRolesMatrixSample, AccessMatrixSample, MasterSettingsSample, NavTopSample, NavDrawer, NavFloatingSettings } from './designs/index.js';
 import { useDesignValidator, LOGIN_RULES, REGISTER_RULES, FORGOT_PASSWORD_RULES, RESET_PASSWORD_RULES, CHANGE_PASSWORD_RULES, PROFILE_RULES, USER_ROLES_MATRIX_RULES, ACCESS_MATRIX_RULES, MASTER_SETTINGS_RULES, NAV_RULES } from './validateDesign.js';
 
 /**
@@ -111,11 +111,19 @@ export function MasterSettingsPage({ design, ...props }) {
 // vertical rail) — it's simply unused whenever a drawer is present.
 // See useNavController.js for the drawerItems/settingsOverrides/notifications
 // props this accepts.
-function NavPageImpl({ design, logo, expandedLogo, navMiddle, drawerPromo, ...props }) {
+//
+// `floatingSettings` (optional, default false): when true AND a drawer is in
+// use, the drawer's own bottom-pinned bell/settings are suppressed and
+// replaced by NavFloatingSettings — the same two controls floating in the
+// page's top-right corner instead. A no-op without a drawer: the plain
+// top-bar path already renders them inline at top-right (NavTopSample's
+// `.xeplr-nav-right`), so there's nothing to move there.
+function NavPageImpl({ design, logo, expandedLogo, navMiddle, drawerPromo, floatingSettings, ...props }) {
   var controller = useNavController(props);
   var ref = useDesignValidator('NavPage', NAV_RULES);
   var TopBar = design || NavTopSample;
   var hasDrawer = controller.drawerItems.length > 0;
+  var floating = floatingSettings && hasDrawer;
   return (
     <div ref={ref}>
       {hasDrawer ? (
@@ -124,6 +132,7 @@ function NavPageImpl({ design, logo, expandedLogo, navMiddle, drawerPromo, ...pr
           logo={logo}
           expandedLogo={expandedLogo}
           drawerPromo={drawerPromo}
+          hideFooterIcons={floating}
         />
       ) : (
         <TopBar
@@ -132,6 +141,7 @@ function NavPageImpl({ design, logo, expandedLogo, navMiddle, drawerPromo, ...pr
           navMiddle={navMiddle}
         />
       )}
+      {floating && <NavFloatingSettings {...controller} />}
     </div>
   );
 }

package/src/returnTo.js

@@ -0,0 +1,24 @@
+const KEY = 'xeplr:returnTo';
+
+/**
+ * Where a redirect-driven gate (auth, or an app's own e.g. company gate)
+ * sends the user next, once whatever it was waiting for resolves. Tab-scoped
+ * (sessionStorage) — this is for "the token expired mid-session, send me
+ * back to what I was doing", not a link resurrected days later.
+ */
+export function saveReturnTo(location) {
+  try {
+    sessionStorage.setItem(KEY, location.pathname + location.search);
+  } catch (e) {}
+}
+
+/** Reads and clears in one step — call only at the point the user actually lands. */
+export function consumeReturnTo() {
+  try {
+    const value = sessionStorage.getItem(KEY);
+    sessionStorage.removeItem(KEY);
+    return value;
+  } catch (e) {
+    return null;
+  }
+}

package/src/useActivateController.js

@@ -6,6 +6,10 @@ import { activateAccount } from './api.js';
 export function useActivateController() {
   var [searchParams] = useSearchParams();
   var token = searchParams.get('token');
+  // Put there by @xeplr/auth's register() when the registration was one step
+  // of a workflow. Handed back untouched so the server can release the step
+  // that was waiting — this page never interprets it.
+  var workflowKey = searchParams.get('workflowKey');
   var [error, setError] = useState('');
   var [success, setSuccess] = useState('');
   var [loading, setLoading] = useState(false);
@@ -24,7 +28,7 @@ export function useActivateController() {
     setLoading(true);
     setError('');
     setSuccess('');
-    activateAccount(token)
+    activateAccount(token, workflowKey)
       .then(function(result) {
         var message = result.message || 'Account activated successfully';
         setSuccess(message);
@@ -37,7 +41,7 @@ export function useActivateController() {
       .finally(function() {
         setLoading(false);
       });
-  }, [token]);
+  }, [token, workflowKey]);
 
   return {
     token,

package/src/useLoginController.js

@@ -4,6 +4,7 @@ import { raiseSnackbar } from '@xeplr/ui-utils';
 import { loginUser } from './api.js';
 import { setToken, setRefreshToken } from './token.js';
 import { useAccess } from './AccessContext.jsx';
+import { consumeReturnTo } from './returnTo.js';
 
 export function useLoginController(options = {}) {
   const [email, setEmail] = useState('');
@@ -15,7 +16,11 @@ export function useLoginController(options = {}) {
   // Safe — returns null if no AccessProvider wraps the app
   const accessCtx = useAccess();
 
-  const onSuccess = options.onSuccess || (() => navigate('/'));
+  // Default: back to wherever a gate (ProtectedRoute, or an app's own gate)
+  // sent the user here from, not always home — see returnTo.js. A caller
+  // that supplies its own onSuccess owns navigation entirely; this default
+  // only applies when they don't.
+  const onSuccess = options.onSuccess || (() => navigate(consumeReturnTo() || '/'));
   const notActivatedPath = options.notActivatedPath || '/auth/not-activated';
 
   async function handleSubmit(e) {

package/src/useNavController.js

@@ -14,6 +14,56 @@ var BUILTIN_SETTINGS_ITEMS = [
 ];
 var NOTIFICATIONS_MENU_NAME = 'Notifications';
 
+// ── drawer width ────────────────────────────────────────────────────────
+// Only the EXPANDED drawer is resizable. Collapsed is a 60px icon rail whose
+// width is the icon's, not a preference — there is nothing in it to give room
+// to, so nav.css keeps owning that number.
+//
+// The width is remembered because re-dragging it on every page load is the
+// whole reason a fixed width was annoying enough to change. Kept per browser
+// (localStorage) rather than on the user record: it is a property of the
+// screen you are sitting at, and the same account on a laptop and a wide
+// monitor wants two different answers.
+var DRAWER_WIDTH_KEY = 'xeplr-nav-drawer-width';
+var DRAWER_WIDTH_DEFAULT = 240;
+// Floors and ceilings, not taste. Below MIN the labels this width exists to
+// show start truncating, so the expanded state stops being different from the
+// collapsed one; past MAX the nav is competing with the page for the screen.
+var DRAWER_WIDTH_MIN = 180;
+var DRAWER_WIDTH_MAX = 480;
+// What an arrow key moves. Big enough to get somewhere, small enough to land.
+var DRAWER_WIDTH_STEP = 16;
+
+// Frozen module constant, so the identity is stable across renders and a
+// memoized View is not re-rendered by a fresh object every time.
+var DRAWER_WIDTH_BOUNDS = {
+  min: DRAWER_WIDTH_MIN,
+  max: DRAWER_WIDTH_MAX,
+  step: DRAWER_WIDTH_STEP,
+  default: DRAWER_WIDTH_DEFAULT
+};
+
+// Only NaN falls back to the default — ±Infinity is deliberately allowed
+// through, because Math.min/max turn it into exactly the near/far stop, which
+// is what the Home/End keys pass in.
+function clampDrawerWidth(px) {
+  if (typeof px !== 'number' || isNaN(px)) return DRAWER_WIDTH_DEFAULT;
+  return Math.min(DRAWER_WIDTH_MAX, Math.max(DRAWER_WIDTH_MIN, Math.round(px)));
+}
+
+// Wrapped because localStorage THROWS rather than returning null in Safari
+// private mode and under a blocked-cookies policy — an unguarded read here
+// would take the whole nav down at first render.
+function readStoredDrawerWidth() {
+  try {
+    var raw = window.localStorage.getItem(DRAWER_WIDTH_KEY);
+    if (!raw) return DRAWER_WIDTH_DEFAULT;
+    return clampDrawerWidth(parseInt(raw, 10));
+  } catch (err) {
+    return DRAWER_WIDTH_DEFAULT;
+  }
+}
+
 /**
  * Nav is self-contained by design: it reads access/user from context (which only
  * changes on login/logout/access updates) and owns its OWN open/closed UI state.
@@ -47,6 +97,11 @@ export function useNavController(props) {
   var [accountOpen, setAccountOpen] = useState(false);
   var [drawerOpen, setDrawerOpen] = useState(false);
 
+  // Lazy initialiser (function, not value) so localStorage is read ONCE on
+  // mount instead of on every render.
+  var [drawerWidth, setDrawerWidth] = useState(readStoredDrawerWidth);
+  var [drawerResizing, setDrawerResizing] = useState(false);
+
   var accountRef = useRef(null);
 
   var toggleAccount = useCallback(function() { setAccountOpen(function(v) { return !v; }); }, []);
@@ -54,6 +109,64 @@ export function useNavController(props) {
   var toggleDrawer = useCallback(function() { setDrawerOpen(function(v) { return !v; }); }, []);
   var closeDrawer = useCallback(function() { setDrawerOpen(false); }, []);
 
+  // ── resizing ──────────────────────────────────────────────────────────
+  // The handle only starts the gesture; the move/end listeners go on the
+  // DOCUMENT (below), not the handle, because a drag routinely outruns a 6px
+  // strip — listening on the handle alone would drop the gesture the moment
+  // the pointer got ahead of the edge, which is most of the time.
+  var startDrawerResize = useCallback(function(e) {
+    // Stops the browser starting a text/image selection drag instead, which
+    // would leave the page blue-highlighted for the whole gesture.
+    if (e && e.preventDefault) e.preventDefault();
+    setDrawerResizing(true);
+  }, []);
+
+  var resetDrawerWidth = useCallback(function() {
+    setDrawerWidth(DRAWER_WIDTH_DEFAULT);
+  }, []);
+
+  // Keyboard equivalent of the drag — the handle is focusable, so a resize
+  // must be reachable without a pointer at all.
+  var nudgeDrawerWidth = useCallback(function(delta) {
+    setDrawerWidth(function(w) { return clampDrawerWidth(w + delta); });
+  }, []);
+
+  useEffect(function() {
+    if (!drawerResizing) return;
+    // The drawer is `position: fixed; left: 0`, so the pointer's viewport x IS
+    // the width being dragged to — no offset bookkeeping needed.
+    function onMove(e) { setDrawerWidth(clampDrawerWidth(e.clientX)); }
+    function onUp() { setDrawerResizing(false); }
+    document.addEventListener('pointermove', onMove);
+    document.addEventListener('pointerup', onUp);
+    // pointercancel fires when the browser takes the gesture away (touch
+    // scroll taking over, window losing focus). Without it the drag would
+    // never end and every later mouse move would keep resizing.
+    document.addEventListener('pointercancel', onUp);
+    // Suppresses selection + forces the col-resize cursor everywhere for the
+    // duration, so the cursor doesn't flicker back to a caret whenever the
+    // pointer outruns the handle.
+    document.body.classList.add('xeplr-nav-resizing');
+    return function() {
+      document.removeEventListener('pointermove', onMove);
+      document.removeEventListener('pointerup', onUp);
+      document.removeEventListener('pointercancel', onUp);
+      document.body.classList.remove('xeplr-nav-resizing');
+    };
+  }, [drawerResizing]);
+
+  // Written once the gesture SETTLES, not on every pointermove — a drag fires
+  // these by the hundred, and localStorage is synchronous.
+  useEffect(function() {
+    if (drawerResizing) return;
+    try {
+      window.localStorage.setItem(DRAWER_WIDTH_KEY, String(drawerWidth));
+    } catch (err) {
+      // Storage unavailable (see readStoredDrawerWidth) — the width still
+      // works for this session, it just won't be remembered.
+    }
+  }, [drawerWidth, drawerResizing]);
+
   // Click-outside for the settings menu only — the drawer closes via its own overlay.
   useEffect(function() {
     if (!accountOpen) return;
@@ -97,6 +210,15 @@ export function useNavController(props) {
     drawerOpen: drawerOpen,
     toggleDrawer: toggleDrawer,
     closeDrawer: closeDrawer,
-    drawerItems: drawerItems
+    drawerItems: drawerItems,
+
+    drawerWidth: drawerWidth,
+    drawerResizing: drawerResizing,
+    startDrawerResize: startDrawerResize,
+    resetDrawerWidth: resetDrawerWidth,
+    nudgeDrawerWidth: nudgeDrawerWidth,
+    // Handed out so the View can fill in aria-valuemin/max and its own key
+    // handling without re-declaring the numbers and drifting from them.
+    drawerWidthBounds: DRAWER_WIDTH_BOUNDS
   };
 }

package/src/validateDesign.js

@@ -4,8 +4,13 @@ import { useEffect, useRef } from 'react';
  * Validates that required elements exist in the rendered design.
  * Throws a visible error if any required element is missing.
  *
+ * A rule matches by id, role or selector. `anyOf` takes a list of selectors
+ * and passes when ANY one is present — which is what a design with tabs or
+ * steps needs, since only the current one is mounted and demanding all of
+ * them at once can never pass.
+ *
  * @param {string} componentName - Name of the page (for error messages)
- * @param {Array<{id?: string, role?: string, selector?: string, label: string}>} requiredElements
+ * @param {Array<{id?: string, role?: string, selector?: string, anyOf?: string[], label: string}>} requiredElements
  */
 export function useDesignValidator(componentName, requiredElements) {
   var containerRef = useRef(null);
@@ -26,12 +31,19 @@ export function useDesignValidator(componentName, requiredElements) {
           found = !!containerRef.current.querySelector('#' + rule.id);
         } else if (rule.role) {
           found = !!containerRef.current.querySelector('[role="' + rule.role + '"]');
+        } else if (rule.anyOf) {
+          for (var j = 0; j < rule.anyOf.length && !found; j++) {
+            found = !!containerRef.current.querySelector(rule.anyOf[j]);
+          }
         } else if (rule.selector) {
           found = !!containerRef.current.querySelector(rule.selector);
         }
 
         if (!found) {
-          missing.push(rule.label + (rule.id ? ' (id="' + rule.id + '")' : '') + (rule.selector ? ' (' + rule.selector + ')' : ''));
+          var where = rule.id ? ' (id="' + rule.id + '")'
+            : rule.anyOf ? ' (one of: ' + rule.anyOf.join(', ') + ')'
+            : rule.selector ? ' (' + rule.selector + ')' : '';
+          missing.push(rule.label + where);
         }
       }