Large UX/docs batch: ESC/outside modal close, moderation queue ergonomics, naming consistency, policy+test docs

Author: wilhel1812

README.md

@@ -72,6 +72,17 @@ This repository now includes:
 Detailed setup steps:
 
 - [docs/cloudflare-auth-setup.md](./docs/cloudflare-auth-setup.md)
+- [docs/access-policy-templates.md](./docs/access-policy-templates.md)
+
+## Testing
+
+- Test plan: [docs/testing-plan.md](./docs/testing-plan.md)
+- Run baseline checks:
+
+```bash
+npm test
+npm run build
+```
 
 ## Running with Docker Compose
 

docs/BACKLOG.md

@@ -17,6 +17,7 @@ State: stabilization pass (no net-new product features unless explicitly approve
 - [ ] E-mail notifications (starting with account approval)
 - [ ] Rehaul of dockumentation (readme.md)
 - [ ] Set up a compehensive testing plan
+- [x] Set up a compehensive testing plan
 - [ ] Branding
 - [ ] Elevation plot visibility toggle
 - [x] Instead of showing actions on the users in the admin panel, show a simple list of users and make open the profile popover when clicking the names. This should be the same popover that appears anywhere else. Admin gets extra moderation buttons.
@@ -59,17 +60,20 @@ State: stabilization pass (no net-new product features unless explicitly approve
 - [ ] Full terminology pass (Project/Simulation/Setup/Snapshot/etc.)
 - [x] Move crowded metadata out of list rows and into details panels
 - [ ] Clean sidebar information density and progressive disclosure
+- Progress: simplified library/action labels and streamlined user moderation list flow.
 - [ ] Unify labels/buttons across libraries and managers
+- Progress: aligned labels for library open/save/add actions and moderation wording.
 - [ ] Standardize error messages across endpoints and UI surfaces
 - Progress: backend endpoints now use centralized error normalization and status mapping; UI surface pass still pending.
+- [x] Modal UX: support ESC and click-outside to close dialogs (in addition to close button)
 
 ### Simulation quality clarity
 - [ ] Improve explanatory info for FSPL / TwoRay / ITM and defaults
 - [ ] Document map sampling strategies clearly in UI help
 - [ ] Recheck pass/fail interpretation and communication around terrain blocking
 
 ### Security and access hardening
-- [ ] Productize Access policy templates in-app docs and setup checklist
+- [x] Productize Access policy templates in-app docs and setup checklist
 - [x] Add admin warning surfaces for unsafe auth/access configuration
 
 ## Hardening execution paths (agreed, no further discussion required now)

docs/access-policy-templates.md

@@ -0,0 +1,53 @@
+# Cloudflare Access Policy Templates
+
+## Objective
+Provide a safe baseline for LinkSim without over-complicated guardrails.
+
+## Recommended baseline
+
+### Application
+- Protect the LinkSim app hostname with Cloudflare Access.
+- Identity providers:
+  - GitHub (primary)
+  - One-time PIN (fallback)
+
+### Session duration
+- Recommended: `24h` to `7d` depending on team preference.
+- Keep lower for admin-heavy deployments.
+
+### App policy (minimum)
+- Action: `Allow`
+- Include:
+  - Allowed email domains OR specific emails/groups
+- Exclude:
+  - Explicitly blocked users/groups (if used)
+
+### LinkSim app-level approval
+- Keep `REGISTRATION_MODE=approval_required`.
+- Cloudflare Access answers “who can sign in”.
+- LinkSim approval answers “who can use simulation features”.
+
+## Hardened profile (optional)
+- Restrict to one IdP per environment.
+- Reduce session duration for admin users.
+- Add country/IP device posture restrictions if required by org policy.
+
+## Required env variables
+- `ACCESS_TEAM_DOMAIN`
+- `ACCESS_AUD`
+- `REGISTRATION_MODE=approval_required`
+- `ADMIN_USER_IDS=<comma-separated admin ids>`
+- `AUTH_OBSERVABILITY=true` (recommended)
+
+## Validation checklist
+1. Unauthenticated user gets Access challenge.
+2. Authenticated non-approved user lands in pending flow.
+3. Admin can open:
+   - `/api/auth-diagnostics`
+   - `/api/schema-diagnostics`
+4. App denies privileged endpoints for non-admin users.
+
+## Common misconfigurations
+- Missing `ACCESS_AUD` or `ACCESS_TEAM_DOMAIN`.
+- `ALLOW_INSECURE_DEV_AUTH=true` in production.
+- Expecting Access policy alone to replace LinkSim role/approval controls.

docs/cloudflare-auth-setup.md

@@ -103,3 +103,8 @@ npm run dev:edge
 ```
 
 This is for local testing only.
+
+## Related docs
+
+- Access policy templates: `docs/access-policy-templates.md`
+- Testing plan: `docs/testing-plan.md`

docs/testing-plan.md

@@ -0,0 +1,56 @@
+# LinkSim Testing Plan
+
+## Goals
+- Prevent auth/permission regressions.
+- Validate simulation correctness stability.
+- Keep UI workflow regressions visible.
+- Make cloud deployment checks repeatable.
+
+## Layers
+
+### 1) Unit tests (fast, every commit)
+- Location: `src/**/*.test.ts`, `functions/**/*.test.ts`
+- Focus:
+  - RF model math (`propagation`, `coverage`, `terrainLoss`)
+  - Auth source resolution and fallback behavior
+  - Error normalization/status mapping
+
+### 2) API behavior tests (local edge)
+- Run against local `dev:edge` with D1.
+- Focus:
+  - `me`, `users`, `users/[id]`, `library`, `notifications`, `changes`
+  - Admin vs non-admin permissions
+  - Pending/revoked/deleted session behavior
+  - Metadata repair endpoints
+
+### 3) UI smoke checks
+- Existing smoke scripts in `scripts/`.
+- Focus:
+  - Map render + sidebar interaction
+  - Path profile updates
+  - Modal stack behavior
+  - User settings open/save/logout
+
+### 4) Deployment checks (preview/prod)
+- Cloudflare Access gate active.
+- D1 migration applied.
+- Diagnostics endpoints for admins:
+  - `/api/auth-diagnostics`
+  - `/api/schema-diagnostics`
+
+## Required checks before push
+1. `npm test`
+2. `npm run build`
+3. Manual quick pass:
+  - open app
+  - open/close nested modals
+  - load simulation library + site library
+  - open user settings and verify user state loads
+
+## Priority expansion
+- Add permission-matrix API tests for:
+  - self-role protection
+  - pending user restrictions
+  - revoked/deleted session handling
+  - admin-only moderation routes
+- Add end-to-end scenario for metadata repair and creator/editor attribution.

src/components/ModalOverlay.tsx

@@ -4,33 +4,60 @@ import { createPortal } from "react-dom";
 type ModalOverlayProps = {
   "aria-label": string;
   children: ReactNode;
+  onClose?: () => void;
 };
 
-let modalStackCounter = 0;
+let modalIdCounter = 0;
 let openModalCount = 0;
+const openModalStack: number[] = [];
 
-const nextModalZIndex = (): number => {
-  modalStackCounter += 1;
-  return 2000 + modalStackCounter * 10;
-};
-
-export function ModalOverlay({ children, ...rest }: ModalOverlayProps) {
-  const zIndex = useMemo(() => nextModalZIndex(), []);
+export function ModalOverlay({ children, onClose, ...rest }: ModalOverlayProps) {
+  const modalId = useMemo(() => {
+    modalIdCounter += 1;
+    return modalIdCounter;
+  }, []);
+  const zIndex = useMemo(() => 2000 + modalId * 10, [modalId]);
 
   useEffect(() => {
     openModalCount += 1;
+    openModalStack.push(modalId);
     const previousOverflow = document.body.style.overflow;
     document.body.style.overflow = "hidden";
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== "Escape") return;
+      const top = openModalStack[openModalStack.length - 1];
+      if (top !== modalId) return;
+      if (!onClose) return;
+      event.preventDefault();
+      onClose();
+    };
+    window.addEventListener("keydown", onKeyDown);
     return () => {
+      window.removeEventListener("keydown", onKeyDown);
       openModalCount = Math.max(0, openModalCount - 1);
+      const idx = openModalStack.lastIndexOf(modalId);
+      if (idx >= 0) openModalStack.splice(idx, 1);
       if (openModalCount === 0) {
         document.body.style.overflow = previousOverflow;
       }
     };
-  }, []);
+  }, [modalId, onClose]);
 
   return createPortal(
-    <div aria-modal="true" className="library-manager-overlay" role="dialog" style={{ zIndex }} {...rest}>
+    <div
+      aria-modal="true"
+      className="library-manager-overlay"
+      onMouseDown={(event) => {
+        if (!onClose) return;
+        if (event.target !== event.currentTarget) return;
+        const top = openModalStack[openModalStack.length - 1];
+        if (top !== modalId) return;
+        onClose();
+      }}
+      role="dialog"
+      style={{ zIndex }}
+      {...rest}
+    >
       {children}
     </div>,
     document.body,

src/components/Sidebar.tsx

@@ -1072,10 +1072,10 @@ export function Sidebar() {
             onClick={() => setShowSimulationLibraryManager(true)}
             type="button"
           >
-            Open Simulation Library
+            Simulation Library
           </button>
           <button className="inline-action" onClick={saveSimulationAsNew} type="button">
-            Save Current Simulation
+            Save Simulation
           </button>
         </div>
         {simulationSaveStatus ? <p className="field-help">{simulationSaveStatus}</p> : null}
@@ -1120,7 +1120,7 @@ export function Sidebar() {
         <p className="field-help">Use Site Library to add/edit sites, then add selected sites to this simulation.</p>
         <div className="chip-group">
           <button className="inline-action" onClick={() => setShowSiteLibraryManager(true)} type="button">
-            Open Site Library
+            Site Library
           </button>
           {siteLibrary.length ? (
             <button className="inline-action" onClick={() => insertSiteFromLibrary(siteLibrary[0].id)} type="button">
@@ -1748,7 +1748,7 @@ export function Sidebar() {
       </section>
 
       {profilePopupUser ? (
-        <ModalOverlay aria-label="User Profile">
+        <ModalOverlay aria-label="User Profile" onClose={() => setProfilePopupUser(null)}>
           <div className="library-manager-card user-profile-popup">
             <div className="library-manager-header">
               <h2>User Profile</h2>
@@ -1783,7 +1783,7 @@ export function Sidebar() {
       ) : null}
 
       {changeLogPopup ? (
-        <ModalOverlay aria-label="Change Log">
+        <ModalOverlay aria-label="Change Log" onClose={() => setChangeLogPopup(null)}>
           <div className="library-manager-card">
             <div className="library-manager-header">
               <h2>Change Log · {changeLogPopup.label}</h2>
@@ -1818,7 +1818,7 @@ export function Sidebar() {
       ) : null}
 
       {resourceDetailsPopup ? (
-        <ModalOverlay aria-label="Resource Details">
+        <ModalOverlay aria-label="Resource Details" onClose={() => setResourceDetailsPopup(null)}>
           <div className="library-manager-card user-profile-popup">
             <div className="library-manager-header">
               <h2>Details · {resourceDetailsPopup.label}</h2>
@@ -1863,7 +1863,7 @@ export function Sidebar() {
       ) : null}
 
       {showSimulationLibraryManager ? (
-        <ModalOverlay aria-label="Simulation Library">
+        <ModalOverlay aria-label="Simulation Library" onClose={() => setShowSimulationLibraryManager(false)}>
           <div className="library-manager-card">
             <div className="library-manager-header">
               <h2>Simulation Library</h2>
@@ -1895,7 +1895,7 @@ export function Sidebar() {
             </label>
             <div className="chip-group">
               <button className="inline-action" onClick={saveSimulationAsNew} type="button">
-                Save Current Simulation
+                Save Simulation
               </button>
             </div>
             {simulationSaveStatus ? <p className="field-help">{simulationSaveStatus}</p> : null}
@@ -2014,7 +2014,7 @@ export function Sidebar() {
         </ModalOverlay>
       ) : null}
       {showSiteLibraryManager ? (
-        <ModalOverlay aria-label="Site Library">
+        <ModalOverlay aria-label="Site Library" onClose={() => setShowSiteLibraryManager(false)}>
           <div className="library-manager-card">
             <div className="library-manager-header">
               <h2>Site Library</h2>
@@ -2040,7 +2040,7 @@ export function Sidebar() {
                 onClick={() => setShowAddLibraryForm((current) => !current)}
                 type="button"
               >
-                {showAddLibraryForm ? "Hide Add" : "Add Library Site"}
+                {showAddLibraryForm ? "Hide Add Form" : "Add Site"}
               </button>
               <button
                 className="inline-action"
@@ -2077,7 +2077,7 @@ export function Sidebar() {
             </div>
             {showAddLibraryForm ? (
               <div className="library-editor">
-                <h3>Add Library Site</h3>
+                <h3>Add Site</h3>
                 <label className="field-grid">
                   <span>Name</span>
                   <input