web.php

<?php
declare(strict_types=1);

use Slim\App;
use Slim\Psr7\Response;
use App\Controllers\AutoriController;
use App\Controllers\LibriController;
use App\Controllers\PrestitiController;
use App\Controllers\AuthController;
use App\Controllers\DashboardController;
use App\Controllers\RegistrationController;
use App\Controllers\PasswordController;
use App\Controllers\ProfileController;
use App\Controllers\UserActionsController;
use App\Controllers\UserWishlistController;
use App\Middleware\AuthMiddleware;
use App\Controllers\SeoController;
use App\Controllers\DeweyApiController;
use App\Controllers\GeneriApiController;
use App\Controllers\GeneriController;
use App\Controllers\ReservationsController;
use App\Controllers\LoanApprovalController;
use App\Controllers\CollocazioneController;
use App\Controllers\UserDashboardController;
use App\Controllers\MaintenanceController;
use App\Controllers\SettingsController;
use App\Controllers\LanguageController;
use App\Controllers\ReservationsAdminController;
use App\Middleware\CsrfMiddleware;
use App\Middleware\AdminAuthMiddleware;
use App\Middleware\SessionRoleRefreshMiddleware;
use App\Support\RouteTranslator;
use App\Support\I18n;

return function (App $app): void {
    $installationLocale = I18n::getInstallationLocale();
    // Supported locales for multi-language route variants
    // Content routes (book, author, publisher, genre) are registered
    // in all languages to support language switching without 404s
    $supportedLocales = array_keys(I18n::getAvailableLocales());
    if ($supportedLocales === []) {
        $supportedLocales = [$installationLocale ?: 'it_IT'];
    }

    // Track registered routes to avoid duplicates (some routes are identical across languages)
    $registeredRoutes = [];

    // Helper function to register route only if not already registered
    $registerRouteIfUnique = function (string $method, string $pattern, callable $handler, ?array $middleware = null) use ($app, &$registeredRoutes) {
        $routeKey = $method . ':' . $pattern;

        if (isset($registeredRoutes[$routeKey])) {
            return; // Already registered, skip
        }

        $registeredRoutes[$routeKey] = true;

        // Use specific HTTP method instead of map() for better compatibility
        $route = match (strtoupper($method)) {
            'GET' => $app->get($pattern, $handler),
            'POST' => $app->post($pattern, $handler),
            'PUT' => $app->put($pattern, $handler),
            'DELETE' => $app->delete($pattern, $handler),
            'PATCH' => $app->patch($pattern, $handler),
            default => $app->map([$method], $pattern, $handler),
        };

        if ($middleware) {
            foreach ($middleware as $mw) {
                $route->add($mw);
            }
        }
    };


    // ==========================================
    // Plugin Routes Hook (register early)
    // ==========================================
    try {
        $hookManager = $app->getContainer()->get('hookManager');
        $hookManager->doAction('app.routes.register', [$app]);
    } catch (\Throwable $e) {
        error_log('[Routes] Error loading plugin routes: ' . $e->getMessage());
    }

    $app->get('/', function ($request, $response) use ($app) {
        // Redirect to frontend home page
        $container = $app->getContainer();
        $controller = new \App\Controllers\FrontendController($container);
        $db = $container->get('db');
        return $controller->home($request, $response, $db, $container);
    });

    // English fallback for events (always available regardless of locale list)
    $registerRouteIfUnique('GET', '/events', function ($request, $response) use ($app) {
        $container = $app->getContainer();
        $controller = new \App\Controllers\FrontendController($container);
        $db = $container->get('db');
        return $controller->events($request, $response, $db);
    });
    $registerRouteIfUnique('GET', '/events/{slug}', function ($request, $response, $args) use ($app) {
        $container = $app->getContainer();
        $controller = new \App\Controllers\FrontendController($container);
        $db = $container->get('db');
        return $controller->event($request, $response, $db, $args);
    });

    // Frontend Events routes (all language variants)
    foreach ($supportedLocales as $locale) {
        $registerRouteIfUnique('GET', RouteTranslator::getRouteForLocale('events', $locale), function ($request, $response) use ($app) {
            $container = $app->getContainer();
            $controller = new \App\Controllers\FrontendController($container);
            $db = $container->get('db');
            return $controller->events($request, $response, $db);
        });

        $registerRouteIfUnique('GET', RouteTranslator::getRouteForLocale('events', $locale) . '/{slug}', function ($request, $response, $args) use ($app) {
            $container = $app->getContainer();
            $controller = new \App\Controllers\FrontendController($container);
            $db = $container->get('db');
            return $controller->event($request, $response, $db, $args);
        });
    }

    $app->get('/health', function ($request, $response) {
        $data = ['status' => 'ok'];
        $payload = json_encode($data, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);
        $response->getBody()->write($payload);
        return $response->withHeader('Content-Type', 'application/json');
    });

    // TEST-ONLY page-cache flush (E2E infrastructure, NOT a production route).
    // E2E specs that mutate the DB directly (bypassing the app code and its
    // ContentCache generation bumps) call this endpoint before asserting on a
    // cached frontend page, replicating the invalidation a real edit performs.
    // Gated STRICTLY on a server-side env var that only the CI virtual host
    // sets (`SetEnv PINAKES_E2E_CACHE_FLUSH 1`, next to the existing
    // PINAKES_E2E_* flags): nothing client-controllable — no header, cookie or
    // query parameter — is consulted, so a remote caller cannot enable it.
    // When the flag is absent/empty the route throws the same
    // HttpNotFoundException an unregistered path produces, making it inert in
    // production. GET is deliberate: it keeps the call outside CsrfMiddleware
    // and the only side effect is dropping cache entries (idempotent).
    $app->get('/_e2e/flush-cache', function ($request, $response) {
        $flag = $_ENV['PINAKES_E2E_CACHE_FLUSH']
            ?? getenv('PINAKES_E2E_CACHE_FLUSH')
            ?: '';
        if ($flag !== '1' && strtolower((string) $flag) !== 'true') {
            throw new \Slim\Exception\HttpNotFoundException($request);
        }
        // Honour the flush result: a false return means a real apcu_delete /
        // unlink failure. Surface it as HTTP 500 so the E2E helper can fail the
        // run loudly instead of proceeding to read a stale cached page.
        $flushed = \App\Support\QueryCache::flush();
        $response->getBody()->write((string) json_encode(['flushed' => $flushed]));
        return $response
            ->withStatus($flushed ? 200 : 500)
            ->withHeader('Content-Type', 'application/json; charset=UTF-8')
            ->withHeader('Cache-Control', 'no-store, private');
    });

    // Authenticated loopback target used by CLI/import jobs to turn their
    // durable purge queue into a LiteSpeed response header. The secret is
    // operator-managed via environment, never stored or rendered in admin UI.
    $app->post('/_pinakes/litespeed-purge', function ($request, $response) {
        $provided = trim($request->getHeaderLine('X-Pinakes-Purge-Secret'));
        if (!\App\Support\LiteSpeedCache::authorizesPurgeSecret($provided)) {
            throw new \Slim\Exception\HttpNotFoundException($request);
        }

        $tags = \App\Support\LiteSpeedCache::consumeQueuedPurge();
        $response->getBody()->write((string) json_encode(['purged' => $tags !== [], 'tags' => count($tags)]));
        $response = $response
            ->withHeader('Content-Type', 'application/json; charset=UTF-8')
            ->withHeader('Cache-Control', 'no-store, private')
            ->withHeader('X-LiteSpeed-Cache-Control', 'no-cache');
        if ($tags !== []) {
            $response = $response->withHeader('X-LiteSpeed-Purge', \App\Support\LiteSpeedCache::purgeHeader($tags));
        }
        return $response;
    });

    // Lazy CSRF endpoint (issue #387 step 6). Sessionless anonymous pages
    // carry no CSRF token in their cacheable HTML; JS fetches one from here
    // right before a state-changing request (see public/assets/js/
    // csrf-helper.js). Starting the session on demand mints the same
    // session-backed token CsrfMiddleware validates — protection is
    // unchanged, only WHEN the token is minted moves. The hardened session
    // ini parameters were already applied unconditionally in public/index.php,
    // so this lazy session_start() uses the exact same secure cookie settings.
    // The same-origin policy keeps the JSON unreadable cross-site (no CORS
    // headers are emitted) and no-store keeps any cache from persisting a
    // per-visitor token. Technical endpoint → literal path, like /health.
    $app->get('/csrf-token', function ($request, $response) {
        if (session_status() !== PHP_SESSION_ACTIVE) {
            session_start();
        }
        $payload = json_encode(['token' => \App\Support\Csrf::ensureToken()], JSON_HEX_TAG);
        $response->getBody()->write((string) $payload);
        return $response
            ->withHeader('Content-Type', 'application/json; charset=UTF-8')
            ->withHeader('Cache-Control', 'no-store, private')
            ->withHeader('Pragma', 'no-cache')
            ->withHeader('Vary', 'Cookie')
            ->withHeader('X-Content-Type-Options', 'nosniff');
    });

    $app->get(RouteTranslator::getRouteForLocale('api_edge_availability', 'en_US'), function ($request, $response) use ($app) {
        $container = $app->getContainer();
        $controller = new \App\Controllers\FrontendController($container);
        return $controller->edgeAvailability($request, $response, $container->get('db'));
    })->add(new \App\Middleware\RateLimitMiddleware(300, 60, 'edge-availability'));

    // Private uploaded files (digital-library content, archive documents,
    // generic storage). public/.htaccess routes ONLY these private prefixes
    // here instead of serving them directly, so the global middleware stack
    // (PrivateModeMiddleware) governs access. Public uploads (covers, events,
    // CMS, branding) are still served straight from disk by the web server and
    // never reach this route; the controller enforces realpath containment.
    // HEAD as well: audio players probe a file before streaming it. The database lets
    // the controller ask DigitalAccess who may open a Digital Library file.
    $app->map(['GET', 'HEAD'], '/uploads/{path:.*}', function ($request, $response, $args) use ($app) {
        $controller = new \App\Controllers\ProtectedUploadController($app->getContainer()->get('db'));
        return $controller->serve($request, $response, $args);
    });

    $app->get('/robots.txt', function ($request, $response) {
        $controller = new SeoController();
        return $controller->robots($request, $response);
    });

    $app->get('/sitemap.xml', function ($request, $response) use ($app) {
        $controller = new SeoController();
        $db = $app->getContainer()->get('db');
        return $controller->sitemap($request, $response, $db);
    });

    $app->get('/feed.xml', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\FeedController();
        $db = $app->getContainer()->get('db');
        return $controller->rssFeed($request, $response, $db);
    });

    $app->get('/llms.txt', function ($request, $response) use ($app) {
        $controller = new SeoController();
        $db = $app->getContainer()->get('db');
        return $controller->llmsTxt($request, $response, $db);
    });

    // JavaScript translation table, one cacheable script per locale (layouts load
    // it instead of inlining the whole table in every page). No ".js" in the path:
    // nginx configs send every *.js to a static-file location that answers 404
    // without reaching PHP (.nginx.conf.example), and those configs are not
    // updated with the code.
    $app->get('/i18n/{locale:[a-z]{2}_[A-Z]{2}}', function ($request, $response, $args) {
        $body = \App\Support\TranslationScript::body((string) $args['locale']);
        if ($body === null) {
            throw new \Slim\Exception\HttpNotFoundException($request);
        }
        $response->getBody()->write($body);
        // The URL carries the file's version (?v=), so the content behind it never
        // changes and the browser can keep it for a year.
        return $response
            ->withHeader('Content-Type', 'application/javascript; charset=UTF-8')
            ->withHeader('Cache-Control', 'public, max-age=31536000, immutable')
            ->withHeader('X-Content-Type-Options', 'nosniff');
    });

    // Public language switch endpoint
    $app->get('/language/{locale}', function ($request, $response, $args) use ($app) {
        $controller = new LanguageController();
        $db = $app->getContainer()->get('db');
        return $controller->switchLanguage($request, $response, $db, $args);
    });

    // Admin area redirect
    $app->get('/admin', function ($request, $response) {
        // Redirect to dashboard if logged in; else to login
        if (!empty($_SESSION['user'])) {
            // Backend access decides which dashboard to show
            if (\App\Support\Permissions::can('backend.access')) {
                return $response->withHeader('Location', '/admin/dashboard')->withStatus(302);
            } else {
                // For standard users, show user dashboard
                return $response->withHeader('Location', RouteTranslator::route('user_dashboard'))->withStatus(302);
            }
        }
        return $response->withHeader('Location', RouteTranslator::route('login'))->withStatus(302);
    });

    // User Dashboard (separate from admin)
    // User dashboard (multi-language variants)
    foreach ($supportedLocales as $locale) {
        $dashboardRoute = RouteTranslator::getRouteForLocale('user_dashboard', $locale);

        $registerRouteIfUnique('GET', $dashboardRoute, function ($request, $response) use ($app) {
            $db = $app->getContainer()->get('db');
            $controller = new \App\Controllers\UserDashboardController();
            return $controller->index($request, $response, $db);
        }, [new AuthMiddleware(['admin', 'staff', 'standard', 'premium'])]);
    }

    // Auth routes (translated based on installation locale)
    // Ensure legacy/common paths also work by redirecting them to the canonical translated routes

    // Legacy Italian login URL -> redirect to current login route
    $app->get('/login.php', function ($request, $response) {
        return $response->withHeader('Location', \App\Support\RouteTranslator::route('login'))->withStatus(301);
    });

    // Legacy Italian register URL -> redirect to current register route (e.g. /registrati or /register)
    $app->get('/registra', function ($request, $response) {
        return $response->withHeader('Location', \App\Support\RouteTranslator::route('register'))->withStatus(301);
    });

    // Login - all language variants + English fallback
    $loginGetHandler = function ($request, $response) {
        // If already logged in, redirect appropriately
        if (!empty($_SESSION['user'])) {
            if (\App\Support\Permissions::can('backend.access')) {
                return $response->withHeader('Location', '/admin/dashboard')->withStatus(302);
            } else {
                return $response->withHeader('Location', RouteTranslator::route('user_dashboard'))->withStatus(302);
            }
        }
        $controller = new AuthController();
        return $controller->loginForm($request, $response);
    };
    $registerRouteIfUnique('GET', '/login', $loginGetHandler); // English fallback (always works)
    foreach ($supportedLocales as $locale) {
        $registerRouteIfUnique('GET', RouteTranslator::getRouteForLocale('login', $locale), $loginGetHandler);
    }

    $loginPostHandler = function ($request, $response) use ($app) {
        $controller = new AuthController();
        return $controller->login($request, $response, $app->getContainer()->get('db'));
    };
    $registerRouteIfUnique('POST', '/login', $loginPostHandler, [new \App\Middleware\RateLimitMiddleware(15, 300, 'login'), new CsrfMiddleware()]); // English fallback
    foreach ($supportedLocales as $locale) {
        $registerRouteIfUnique('POST', RouteTranslator::getRouteForLocale('login', $locale), $loginPostHandler, [new \App\Middleware\RateLimitMiddleware(15, 300, 'login'), new CsrfMiddleware()]);
    }

    // Logout - all language variants + English fallback
    $logoutHandler = function ($request, $response) use ($app) {
        $controller = new AuthController();
        return $controller->logout($request, $response, $app->getContainer()->get('db'));
    };
    // Logout is a state-changing action → POST + CSRF only. A GET logout lets any
    // cross-site link/redirect (SameSite=Lax permits top-level GET navigation) log
    // the admin out without consent. The UI submits a small CSRF-protected form.
    $registerRouteIfUnique('POST', '/logout', $logoutHandler, [new CsrfMiddleware()]); // English fallback
    foreach ($supportedLocales as $locale) {
        $registerRouteIfUnique('POST', RouteTranslator::getRouteForLocale('logout', $locale), $logoutHandler, [new CsrfMiddleware()]);
    }

    // User profile (multi-language variants)
    foreach ($supportedLocales as $locale) {
        $profileRoute = RouteTranslator::getRouteForLocale('profile', $locale);

        $registerRouteIfUnique('GET', $profileRoute, function ($request, $response) use ($app) {
            $container = $app->getContainer();
            $db = $container->get('db');
            $controller = new ProfileController();
            return $controller->show($request, $response, $db, $container);
        }, [new AuthMiddleware(['admin', 'staff', 'standard', 'premium'])]);

        $profileUpdateRoute = RouteTranslator::getRouteForLocale('profile_update', $locale);
        $registerRouteIfUnique('POST', $profileUpdateRoute, function ($request, $response) use ($app) {
            $db = $app->getContainer()->get('db');
            $controller = new ProfileController();
            return $controller->update($request, $response, $db);
        }, [new CsrfMiddleware(), new AuthMiddleware(['admin', 'staff', 'standard', 'premium'])]);

        // Redirect GET to profile update to profile
        $registerRouteIfUnique('GET', $profileUpdateRoute, function ($request, $response) {
            return $response->withHeader('Location', RouteTranslator::route('profile'))->withStatus(302);
        }, [new AuthMiddleware(['admin', 'staff', 'standard', 'premium'])]);

        // Handle hybrid URLs for profile update (base in one language, action in another)
        // This occurs when users switch languages mid-session: their browser may have
        // cached the old form action URL in one language while the page base URL changed.
        // Example: Italian install shows /profilo but form might POST to /profilo/update (hybrid)
        // instead of the expected /profilo/aggiorna (fully Italian).
        if ($locale === 'it_IT') {
            // Italian base + English action
            $registerRouteIfUnique('POST', '/profilo/update', function ($request, $response) use ($app) {
                $db = $app->getContainer()->get('db');
                $controller = new ProfileController();
                return $controller->update($request, $response, $db);
            }, [new CsrfMiddleware(), new AuthMiddleware(['admin', 'staff', 'standard', 'premium'])]);
        } elseif ($locale === 'en_US') {
            // English base + Italian action
            $registerRouteIfUnique('POST', '/profile/aggiorna', function ($request, $response) use ($app) {
                $db = $app->getContainer()->get('db');
                $controller = new ProfileController();
                return $controller->update($request, $response, $db);
            }, [new CsrfMiddleware(), new AuthMiddleware(['admin', 'staff', 'standard', 'premium'])]);
        } elseif ($locale === 'de_DE') {
            // German base + English/Italian action
            $registerRouteIfUnique('POST', '/profil/update', function ($request, $response) use ($app) {
                $db = $app->getContainer()->get('db');
                $controller = new ProfileController();
                return $controller->update($request, $response, $db);
            }, [new CsrfMiddleware(), new AuthMiddleware(['admin', 'staff', 'standard', 'premium'])]);
            $registerRouteIfUnique('POST', '/profil/aggiorna', function ($request, $response) use ($app) {
                $db = $app->getContainer()->get('db');
                $controller = new ProfileController();
                return $controller->update($request, $response, $db);
            }, [new CsrfMiddleware(), new AuthMiddleware(['admin', 'staff', 'standard', 'premium'])]);
        }

        $profilePasswordRoute = RouteTranslator::getRouteForLocale('profile_password', $locale);
        $registerRouteIfUnique('POST', $profilePasswordRoute, function ($request, $response) use ($app) {
            $db = $app->getContainer()->get('db');
            $controller = new ProfileController();
            return $controller->changePassword($request, $response, $db);
        }, [new CsrfMiddleware(), new AuthMiddleware(['admin', 'staff', 'standard', 'premium'])]);

        // Redirect GET to profile password to profile
        $registerRouteIfUnique('GET', $profilePasswordRoute, function ($request, $response) {
            return $response->withHeader('Location', RouteTranslator::route('profile'))->withStatus(302);
        }, [new AuthMiddleware(['admin', 'staff', 'standard', 'premium'])]);
    }

    // Session management API endpoints (GDPR compliant - user can manage their sessions)
    $registerRouteIfUnique('GET', '/api/profile/sessions', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new ProfileController();
        return $controller->getSessions($request, $response, $db);
    }, [new AuthMiddleware(['admin', 'staff', 'standard', 'premium'])]);

    $registerRouteIfUnique('POST', '/api/profile/sessions/revoke', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new ProfileController();
        return $controller->revokeSession($request, $response, $db);
    }, [new CsrfMiddleware(), new AuthMiddleware(['admin', 'staff', 'standard', 'premium'])]);

    $registerRouteIfUnique('POST', '/api/profile/sessions/revoke-all', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new ProfileController();
        return $controller->revokeAllSessions($request, $response, $db);
    }, [new CsrfMiddleware(), new AuthMiddleware(['admin', 'staff', 'standard', 'premium'])]);

    // User wishlist (multi-language variants)
    foreach ($supportedLocales as $locale) {
        $wishlistRoute = RouteTranslator::getRouteForLocale('wishlist', $locale);

        $registerRouteIfUnique('GET', $wishlistRoute, function ($request, $response) use ($app) {
            // Redirect to user dashboard if catalogue mode is enabled
            if (\App\Support\ConfigStore::isCatalogueMode()) {
                return $response->withHeader('Location', RouteTranslator::route('user_dashboard'))->withStatus(302);
            }
            $container = $app->getContainer();
            $db = $container->get('db');
            $controller = new UserWishlistController();
            return $controller->page($request, $response, $db, $container);
        }, [new AuthMiddleware(['admin', 'staff', 'standard', 'premium'])]);
    }

    // User reservations (multi-language variants)
    foreach ($supportedLocales as $locale) {
        $reservationsRoute = RouteTranslator::getRouteForLocale('reservations', $locale);

        $registerRouteIfUnique('GET', $reservationsRoute, function ($request, $response) use ($app) {
            // Redirect to user dashboard if catalogue mode is enabled
            if (\App\Support\ConfigStore::isCatalogueMode()) {
                return $response->withHeader('Location', RouteTranslator::route('user_dashboard'))->withStatus(302);
            }
            $container = $app->getContainer();
            $db = $container->get('db');
            $controller = new UserDashboardController();
            return $controller->prenotazioni($request, $response, $db, $container);
        }, [new AuthMiddleware(['admin', 'staff', 'standard', 'premium'])]);
    }

    // Public registration routes (all language variants)
    $registerGetHandler = function ($request, $response) use ($app) {
        if (!empty($_SESSION['user']['id'])) {
            return $response->withHeader('Location', RouteTranslator::route('user_dashboard'))->withStatus(302);
        }
        $db = $app->getContainer()->get('db');
        $controller = new RegistrationController();
        return $controller->form($request, $response, $db);
    };
    $registerPostHandler = function ($request, $response) use ($app) {
        if (!empty($_SESSION['user']['id'])) {
            return $response->withHeader('Location', RouteTranslator::route('user_dashboard'))->withStatus(302);
        }
        $db = $app->getContainer()->get('db');
        $controller = new RegistrationController();
        return $controller->register($request, $response, $db);
    };
    $registerSuccessHandler = function ($request, $response) {
        $controller = new RegistrationController();
        return $controller->success($request, $response);
    };
    $registerRouteIfUnique('GET', '/register', $registerGetHandler); // English fallback
    $registerRouteIfUnique('POST', '/register', $registerPostHandler, [new \App\Middleware\RateLimitMiddleware(3, 3600, 'register'), new CsrfMiddleware()]); // English fallback
    $registerRouteIfUnique('GET', '/register/success', $registerSuccessHandler); // English fallback
    foreach ($supportedLocales as $locale) {
        $registerRouteIfUnique('GET', RouteTranslator::getRouteForLocale('register', $locale), $registerGetHandler);
        $registerRouteIfUnique('POST', RouteTranslator::getRouteForLocale('register', $locale), $registerPostHandler, [new \App\Middleware\RateLimitMiddleware(3, 3600, 'register'), new CsrfMiddleware()]);
        $registerRouteIfUnique('GET', RouteTranslator::getRouteForLocale('register_success', $locale), $registerSuccessHandler);
    }

    // Email verification - all language variants + English fallback
    $verifyEmailHandler = function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new RegistrationController();
        return $controller->verifyEmail($request, $response, $db);
    };
    $registerRouteIfUnique('GET', '/verify-email', $verifyEmailHandler); // English fallback
    foreach ($supportedLocales as $locale) {
        $registerRouteIfUnique('GET', RouteTranslator::getRouteForLocale('verify_email', $locale), $verifyEmailHandler);
    }

    // Password reset - all language variants + English fallback
    $forgotPasswordGetHandler = function ($request, $response) {
        $controller = new PasswordController();
        return $controller->forgotForm($request, $response);
    };
    $forgotPasswordPostHandler = function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new PasswordController();
        return $controller->forgot($request, $response, $db);
    };
    $registerRouteIfUnique('GET', '/forgot-password', $forgotPasswordGetHandler); // English fallback
    $registerRouteIfUnique('POST', '/forgot-password', $forgotPasswordPostHandler, [new \App\Middleware\RateLimitMiddleware(3, 900, 'forgot_password'), new CsrfMiddleware()]); // English fallback
    foreach ($supportedLocales as $locale) {
        $registerRouteIfUnique('GET', RouteTranslator::getRouteForLocale('forgot_password', $locale), $forgotPasswordGetHandler);
        $registerRouteIfUnique('POST', RouteTranslator::getRouteForLocale('forgot_password', $locale), $forgotPasswordPostHandler, [new \App\Middleware\RateLimitMiddleware(3, 900, 'forgot_password'), new CsrfMiddleware()]);
    }

    $resetPasswordGetHandler = function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new PasswordController();
        return $controller->resetForm($request, $response, $db);
    };
    $resetPasswordPostHandler = function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new PasswordController();
        return $controller->reset($request, $response, $db);
    };
    $registerRouteIfUnique('GET', '/reset-password', $resetPasswordGetHandler); // English fallback
    $registerRouteIfUnique('POST', '/reset-password', $resetPasswordPostHandler, [new \App\Middleware\RateLimitMiddleware(5, 300, 'reset_password'), new CsrfMiddleware()]); // English fallback
    foreach ($supportedLocales as $locale) {
        $registerRouteIfUnique('GET', RouteTranslator::getRouteForLocale('reset_password', $locale), $resetPasswordGetHandler);
        $registerRouteIfUnique('POST', RouteTranslator::getRouteForLocale('reset_password', $locale), $resetPasswordPostHandler, [new \App\Middleware\RateLimitMiddleware(5, 300, 'reset_password'), new CsrfMiddleware()]);
    }

    // Frontend user actions: loan/reserve
    $app->post('/user/loan', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new UserActionsController();
        return $controller->loan($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AuthMiddleware(['admin', 'staff', 'standard', 'premium']));
    $app->post('/user/reserve', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new UserActionsController();
        return $controller->reserve($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AuthMiddleware(['admin', 'staff', 'standard', 'premium']));

    // Rotte frontend per gestire le prenotazioni dell'utente (slug '/prenotazioni')

    // Redirect old URL for compatibility
    $app->get('/my-reservations', function ($request, $response) {
        return $response->withHeader('Location', \App\Support\RouteTranslator::route('reservations'))->withStatus(301);
    })->add(new AuthMiddleware(['admin', 'staff', 'standard', 'premium']));
    $app->post('/reservation/cancel', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new UserActionsController();
        return $controller->cancelReservation($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AuthMiddleware(['admin', 'staff', 'standard', 'premium']));
    // Annullamento di una richiesta ('pendente') o di un prestito programmato
    // ('prenotato') da parte dell'utente (M13): il controller esisteva ma era
    // raggiungibile solo dal plugin mobile-api; il vincolo sugli stati
    // annullabili è applicato dalla SELECT di cancelLoan.
    $app->post('/loan/cancel', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new UserActionsController();
        return $controller->cancelLoan($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AuthMiddleware(['admin', 'staff', 'standard', 'premium']));
    $app->post('/reservation/change-date', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new UserActionsController();
        return $controller->changeReservationDate($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AuthMiddleware(['admin', 'staff', 'standard', 'premium']));

    // User reservations count (for badge)
    // If authenticated (via session user), returns JSON {count: N}
    // If not authenticated, returns JSON {count: 0} with 200 (used on public pages safely).
    $app->get('/api/user/reservations/count', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new UserActionsController();
        return $controller->reservationsCount($request, $response, $db);
    });

    // Wishlist API (AJAX)
    $app->get('/api/user/wishlist/status', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new UserWishlistController();
        return $controller->status($request, $response, $db);
    })->add(new AuthMiddleware(['admin', 'staff', 'standard', 'premium']));
    $app->post('/api/user/wishlist/toggle', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new UserWishlistController();
        return $controller->toggle($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AuthMiddleware(['admin', 'staff', 'standard', 'premium']));

    // Rotte dedicate alla gestione della wishlist utente

    // ========== RECENSIONI (Reviews System) ==========
    // User review routes
    $app->get('/api/user/can-review/{libro_id:\d+}', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\RecensioniController();
        return $controller->canReview($request, $response, $db, $args);
    })->add(new AuthMiddleware(['admin', 'staff', 'standard', 'premium']));

    $app->post('/api/user/recensioni', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\RecensioniController();
        return $controller->create($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AuthMiddleware(['admin', 'staff', 'standard', 'premium']));

    // Admin review management routes
    $app->get('/admin/reviews', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\Admin\RecensioniAdminController();
        return $controller->index($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware());

    $app->post('/admin/reviews/{id:\d+}/approve', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\Admin\RecensioniAdminController();
        return $controller->approve($request, $response, $db, $args);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/reviews/{id:\d+}/reject', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\Admin\RecensioniAdminController();
        return $controller->reject($request, $response, $db, $args);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->delete('/admin/reviews/{id:\d+}', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\Admin\RecensioniAdminController();
        return $controller->delete($request, $response, $db, $args);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());
    // ========== END RECENSIONI ==========

    // Admin settings (general + email + templates)
    // Security Logs (Admin Only)
    $app->get('/admin/security-logs', function ($request, $response) {
        $controller = new \App\Controllers\SecurityLogsController();
        return $controller->index($request, $response);
    })->add(new AdminAuthMiddleware());

    $app->get('/admin/settings', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new SettingsController();
        return $controller->index($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute

    $app->post('/admin/settings/general', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new SettingsController();
        return $controller->updateGeneral($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/settings/email', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new SettingsController();
        return $controller->updateEmailSettings($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/settings/email/test', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new SettingsController();
        return $controller->sendTestEmail($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(5, 60, 'email_test')) // triggers an external SMTP handshake — throttle like the other costly admin routes
      ->add(new CsrfMiddleware())
      ->add(new AdminAuthMiddleware());
    $app->post('/admin/settings/registration', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new SettingsController();
        return $controller->updateRegistrationSettings($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/settings/contacts', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new SettingsController();
        return $controller->updateContactSettings($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/settings/privacy', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new SettingsController();
        return $controller->updatePrivacySettings($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/settings/cookie-banner', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new SettingsController();
        return $controller->updateCookieBannerSettings($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/settings/templates/{template}', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new SettingsController();
        $template = (string) ($args['template'] ?? '');
        return $controller->updateEmailTemplate($request, $response, $db, $template);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/settings/labels', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new SettingsController();
        return $controller->updateLabels($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/settings/sharing', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new SettingsController();
        return $controller->updateSharingSettings($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/settings/events', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new SettingsController();
        return $controller->updateEventSettings($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/settings/catalog-header', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new SettingsController();
        return $controller->updateCatalogHeader($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/settings/headers/events', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new SettingsController();
        return $controller->updateCatalogHeader($request, $response, $db, 'events');
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/settings/advanced', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new SettingsController();
        return $controller->updateAdvancedSettings($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/settings/advanced/regenerate-sitemap', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new SettingsController();
        return $controller->regenerateSitemap($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/settings/advanced/flush-cache', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new SettingsController();
        return $controller->flushAllCaches($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/settings/loans', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new SettingsController();
        return $controller->updateLoansSettings($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // API Settings Routes
    $app->post('/admin/settings/api/toggle', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new SettingsController();
        return $controller->toggleApi($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/settings/api/keys/create', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new SettingsController();
        return $controller->createApiKey($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/settings/api/keys/{id:\d+}/toggle', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new SettingsController();
        return $controller->toggleApiKey($request, $response, $db, (int) $args['id']);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/settings/api/keys/{id:\d+}/delete', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new SettingsController();
        return $controller->deleteApiKey($request, $response, $db, (int) $args['id']);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Language Management Routes (Admin Only)
    $app->get('/admin/languages', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\Admin\LanguagesController();
        return $controller->index($request, $response, $db, []);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware());

    $app->get('/admin/languages/create', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\Admin\LanguagesController();
        return $controller->create($request, $response, $db, []);
    })->add(new AdminAuthMiddleware());

    $app->post('/admin/languages', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\Admin\LanguagesController();
        return $controller->store($request, $response, $db, []);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // IMPORTANT: Static routes MUST come BEFORE dynamic routes with {code}
    // to avoid FastRoute shadowing errors
    $app->post('/admin/languages/refresh-stats', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\Admin\LanguagesController();
        return $controller->refreshStats($request, $response, $db, []);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->get('/admin/languages/{code}/download', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\Admin\LanguagesController();
        return $controller->download($request, $response, $db, $args);
    })->add(new AdminAuthMiddleware());

    // Route translation editor (must come before /admin/languages/{code}/edit)
    $app->get('/admin/languages/{code}/edit-routes', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\Admin\LanguagesController();
        return $controller->editRoutes($request, $response, $db, $args);
    })->add(new AdminAuthMiddleware());

    if ($installationLocale === 'en_US') {
        // Legacy Italian and hybrid URLs -> redirect to English canonical routes
        $legacyRedirects = [
            // Auth
            '/accedi' => 'login',
            '/esci' => 'logout',
            '/registrati' => 'register',
            '/registrati/successo' => 'register_success',
            '/register/successo' => 'register_success',  // Hybrid
            '/password-dimenticata' => 'forgot_password',
            '/reimposta-password' => 'reset_password',
            '/verifica-email' => 'verify_email',
            // Profile
            '/profilo' => 'profile',
            '/profilo/password' => 'profile_password',
            '/profilo/aggiorna' => 'profile_update',
            '/profile/aggiorna' => 'profile_update',  // Hybrid
            // User area
            '/utente/bacheca' => 'user_dashboard',
            '/user/bacheca' => 'user_dashboard',  // Hybrid
            '/prenotazioni' => 'reservations',
            '/lista-desideri' => 'wishlist',
            // Catalog
            '/catalogo' => 'catalog',
            '/catalogo.php' => 'catalog_legacy',
            '/libro' => 'book',
            '/autore' => 'author',
            '/editore' => 'publisher',
            '/genere' => 'genre',
            // Pages
            '/chi-siamo' => 'about',
            '/contatti' => 'contact',
            '/contatti/invia' => 'contact_submit',
            '/contact/invia' => 'contact_submit',  // Hybrid
            '/privacy' => 'privacy',
            '/cookies' => 'cookies',
            '/eventi' => 'events',
            // Language
            '/lingua' => 'language_switch',
        ];

        foreach ($legacyRedirects as $legacyPath => $routeKey) {
            $targetPath = RouteTranslator::route($routeKey);
            if ($targetPath === $legacyPath) {
                continue;
            }

            // Use 301 (permanent) for legacy URLs that won't return
            $registerRouteIfUnique('GET', $legacyPath, function ($request, $response) use ($targetPath) {
                return $response->withHeader('Location', $targetPath)->withStatus(301);
            });
        }
    } elseif ($installationLocale === 'it_IT') {
        // Legacy English and hybrid URLs -> redirect to Italian canonical routes
        $legacyRedirects = [
            // Auth
            '/login' => 'login',
            '/logout' => 'logout',
            '/register' => 'register',
            '/register/success' => 'register_success',
            '/registrati/success' => 'register_success',  // Hybrid
            '/forgot-password' => 'forgot_password',
            '/reset-password' => 'reset_password',
            '/verify-email' => 'verify_email',
            // Profile
            '/profile' => 'profile',
            '/profile/password' => 'profile_password',
            '/profile/update' => 'profile_update',
            '/profilo/update' => 'profile_update',  // Hybrid
            // User area
            '/user/dashboard' => 'user_dashboard',
            '/utente/dashboard' => 'user_dashboard',  // Hybrid
            '/reservations' => 'reservations',
            '/wishlist' => 'wishlist',
            // Catalog
            '/catalog' => 'catalog',
            '/book' => 'book',
            '/author' => 'author',
            '/publisher' => 'publisher',
            '/genre' => 'genre',
            // Pages
            '/about-us' => 'about',
            '/contact' => 'contact',
            '/contact/submit' => 'contact_submit',
            '/contatti/submit' => 'contact_submit',  // Hybrid
            '/privacy-policy' => 'privacy',
            '/cookie-policy' => 'cookies',
            // Note: /events is already registered at the top of the file, no redirect needed
            // Language
            '/language' => 'language_switch',
        ];

        foreach ($legacyRedirects as $legacyPath => $routeKey) {
            $targetPath = RouteTranslator::route($routeKey);
            if ($targetPath === $legacyPath) {
                continue;
            }

            // Use 301 (permanent) for legacy URLs that won't return
            $registerRouteIfUnique('GET', $legacyPath, function ($request, $response) use ($targetPath) {
                return $response->withHeader('Location', $targetPath)->withStatus(301);
            });
        }
    }

    $app->post('/admin/languages/{code}/update-routes', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\Admin\LanguagesController();
        return $controller->updateRoutes($request, $response, $db, $args);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->get('/admin/languages/{code}/edit', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\Admin\LanguagesController();
        return $controller->edit($request, $response, $db, $args);
    })->add(new AdminAuthMiddleware());

    $app->post('/admin/languages/{code}', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\Admin\LanguagesController();
        return $controller->update($request, $response, $db, $args);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/languages/{code}/delete', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\Admin\LanguagesController();
        return $controller->delete($request, $response, $db, $args);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/languages/{code}/toggle-active', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\Admin\LanguagesController();
        return $controller->toggleActive($request, $response, $db, $args);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/languages/{code}/set-default', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\Admin\LanguagesController();
        return $controller->setDefault($request, $response, $db, $args);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Admin Messages API routes
    $app->get('/admin/messages', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\Admin\MessagesController($db);
        return $controller->getAll($request, $response);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware());

    $app->get('/admin/messages/{id:\d+}', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\Admin\MessagesController($db);
        return $controller->getOne($request, $response, $args);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware());

    $app->delete('/admin/messages/{id:\d+}', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\Admin\MessagesController($db);
        return $controller->delete($request, $response, $args);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/messages/{id:\d+}/archive', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\Admin\MessagesController($db);
        return $controller->archive($request, $response, $args);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/messages/mark-all-read', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\Admin\MessagesController($db);
        return $controller->markAllRead($request, $response);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Admin Notifications routes
    $app->get('/admin/notifications', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\Admin\NotificationsController($db);
        return $controller->index($request, $response);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware());

    $app->get('/admin/notifications/recent', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\Admin\NotificationsController($db);
        return $controller->getRecent($request, $response);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware());

    $app->get('/admin/notifications/unread-count', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\Admin\NotificationsController($db);
        return $controller->getUnreadCount($request, $response);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware());

    $app->post('/admin/notifications/{id:\d+}/read', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\Admin\NotificationsController($db);
        return $controller->markAsRead($request, $response, $args);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/notifications/mark-all-read', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\Admin\NotificationsController($db);
        return $controller->markAllAsRead($request, $response);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->delete('/admin/notifications/{id:\d+}', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\Admin\NotificationsController($db);
        return $controller->delete($request, $response, $args);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Admin CMS index. Declared before /admin/cms/{slug} so the bare address
    // lists the content instead of being read as a page slug.
    $app->get('/admin/cms[/]', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\CmsController();
        return $controller->index($request, $response, $db, $args);
    })->add(new AdminAuthMiddleware());

    // Admin CMS routes - Homepage
    $app->get('/admin/cms/home', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\CmsController();
        return $controller->editHome($request, $response, $db, $args);
    })->add(new AdminAuthMiddleware());

    $app->post('/admin/cms/home', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\CmsController();
        return $controller->updateHome($request, $response, $db, $args);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Reorder home sections (AJAX)
    $app->post('/admin/cms/home/reorder', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\CmsController();
        return $controller->reorderHomeSections($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Toggle home section visibility (AJAX)
    $app->post('/admin/cms/home/toggle-visibility', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\CmsController();
        return $controller->toggleSectionVisibility($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Admin Events routes (MUST be before the catch-all /admin/cms/{slug} route)
    $app->get('/admin/cms/events', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\EventsController();
        return $controller->index($request, $response, $db);
    })->add(new AdminAuthMiddleware());

    $app->post('/admin/cms/events/toggle-visibility', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\EventsController();
        return $controller->toggleVisibility($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->get('/admin/cms/events/create', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\EventsController();
        return $controller->create($request, $response, $db);
    })->add(new AdminAuthMiddleware());

    $app->post('/admin/cms/events', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\EventsController();
        return $controller->store($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->get('/admin/cms/events/edit/{id}', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\EventsController();
        return $controller->edit($request, $response, $db, $args);
    })->add(new AdminAuthMiddleware());

    $app->post('/admin/cms/events/update/{id}', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\EventsController();
        return $controller->update($request, $response, $db, $args);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/cms/events/delete/{id}', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\EventsController();
        return $controller->delete($request, $response, $db, $args);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Admin CMS routes - Other pages (catch-all, MUST be after specific routes)
    $app->get('/admin/cms/{slug}', function ($request, $response, $args) {
        $controller = new \App\Controllers\Admin\CmsAdminController();
        return $controller->editPage($request, $response, $args);
    })->add(new AdminAuthMiddleware());

    $app->post('/admin/cms/{slug}/update', function ($request, $response, $args) {
        $controller = new \App\Controllers\Admin\CmsAdminController();
        return $controller->updatePage($request, $response, $args);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/cms/upload', function ($request, $response) {
        $controller = new \App\Controllers\Admin\CmsAdminController();
        return $controller->uploadImage($request, $response);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Admin API: pending registrations count/list
    $app->get('/api/admin/pending-registrations-count', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $res = $db->query("SELECT COUNT(*) AS c FROM utenti WHERE stato='sospeso' AND email_verificata=1" . \App\Support\Permissions::accountScopeSql());
        $count = (int) ($res->fetch_assoc()['c'] ?? 0);
        $payload = json_encode(['count' => $count]);
        $response->getBody()->write($payload);
        return $response->withHeader('Content-Type', 'application/json');
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute
    $app->get('/api/admin/pending-registrations', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $res = $db->query("SELECT id, nome, cognome, email, created_at FROM utenti WHERE stato='sospeso' AND email_verificata=1" . \App\Support\Permissions::accountScopeSql() . " ORDER BY created_at DESC LIMIT 10");
        $rows = [];
        while ($row = $res->fetch_assoc()) {
            $rows[] = $row;
        }
        $response->getBody()->write(json_encode($rows));
        return $response->withHeader('Content-Type', 'application/json');
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute

    // Role definitions are always administered by a full administrator.
    $app->get('/admin/roles', function ($request, $response) use ($app) {
        return (new \App\Controllers\RolesController())->index($request, $response, $app->getContainer()->get('db'));
    })->add(new AuthMiddleware(['admin']));
    $app->post('/admin/roles', function ($request, $response) use ($app) {
        return (new \App\Controllers\RolesController())->save($request, $response, $app->getContainer()->get('db'));
    })->add(new CsrfMiddleware())->add(new AuthMiddleware(['admin']));

    // Dashboard (protected admin)
    $app->get('/admin/dashboard', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new DashboardController();
        return $controller->index($request, $response, $db);
    })->add(new AuthMiddleware(['admin', 'staff', 'standard', 'premium']));

    // Withdraw every operator calendar link (dashboard "regenerate link").
    // AdminAuthMiddleware also admits staff: this is an admin-only action.
    $app->post('/admin/calendar/rotate-link', function ($request, $response) use ($app) {
        if (($_SESSION['user']['tipo_utente'] ?? '') !== 'admin') {
            $_SESSION['error_message'] = __('Operazione riservata agli amministratori.');
            return $response->withHeader('Location', url('/admin/dashboard'))->withStatus(302);
        }
        try {
            (new \App\Support\LoanCalendarLinks($app->getContainer()->get('db')))->rotateLibraryFeedSecret();
            $_SESSION['success_message'] = __('Link del calendario rigenerato: i link copiati in precedenza non mostrano più nomi ed email dei lettori.');
        } catch (\Throwable $e) {
            \App\Support\SecureLogger::error('Calendar link rotation failed', ['error' => $e->getMessage()]);
            $_SESSION['error_message'] = __('Impossibile rigenerare il link del calendario.');
        }
        return $response->withHeader('Location', url('/admin/dashboard'))->withStatus(302);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Statistics page
    $app->get('/admin/statistics', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\Admin\StatsController();
        return $controller->index($request, $response, $db);
    })->add(new AdminAuthMiddleware());

    // Simple stats APIs used by header quick stats (require authentication)
    $app->get('/api/stats/books-count', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $count = 0;
        if ($db) {
            // Deliberately UNFILTERED by BookVisibility. This feeds the admin
            // layout's header quick-stat, so it follows the same rule as
            // DashboardStats and /admin/books: operator surfaces count every
            // record, requests included. Filtering only this one would make the
            // header disagree with the dashboard card next to it.
            $res = $db->query("SELECT COUNT(*) AS c FROM libri WHERE deleted_at IS NULL");
            if ($res) {
                $count = (int) ($res->fetch_assoc()['c'] ?? 0);
            }
        }
        $response->getBody()->write(json_encode(['count' => $count], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES));
        return $response->withHeader('Content-Type', 'application/json');
    })->add(new AuthMiddleware(['admin', 'staff', 'standard', 'premium']));

    $app->get('/api/stats/active-loans-count', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $count = 0;
        if ($db) {
            $res = $db->query("SELECT COUNT(*) AS c FROM prestiti WHERE attivo = 1 AND stato IN ('in_corso','in_ritardo')");
            if ($res) {
                $count = (int) ($res->fetch_assoc()['c'] ?? 0);
            }
        }
        $response->getBody()->write(json_encode(['count' => $count], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES));
        return $response->withHeader('Content-Type', 'application/json');
    })->add(new AuthMiddleware(['admin', 'staff', 'standard', 'premium']));

    // Users (protected admin)
    $app->get('/admin/users', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\UsersController();
        $db = $app->getContainer()->get('db');
        return $controller->index($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute
    $app->get('/admin/users/create', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\UsersController();
        return $controller->createForm($request, $response, $app->getContainer()->get('db'));
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute
    $app->post('/admin/users/store', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\UsersController();
        $db = $app->getContainer()->get('db');
        return $controller->store($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());
    $app->get('/admin/users/edit/{id:\d+}', function ($request, $response, $args) use ($app) {
        $controller = new \App\Controllers\UsersController();
        $db = $app->getContainer()->get('db');
        return $controller->editForm($request, $response, $db, (int) $args['id']);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute
    $app->post('/admin/users/update/{id:\d+}', function ($request, $response, $args) use ($app) {
        $controller = new \App\Controllers\UsersController();
        $db = $app->getContainer()->get('db');
        return $controller->update($request, $response, $db, (int) $args['id']);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());
    $app->get('/admin/users/details/{id:\d+}', function ($request, $response, $args) use ($app) {
        $controller = new \App\Controllers\UsersController();
        $db = $app->getContainer()->get('db');
        return $controller->details($request, $response, $db, (int) $args['id']);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute
    $app->post('/admin/users/delete/{id:\d+}', function ($request, $response, $args) use ($app) {
        $controller = new \App\Controllers\UsersController();
        $db = $app->getContainer()->get('db');
        return $controller->delete($request, $response, $db, (int) $args['id']);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());
    $app->post('/admin/users/{id:\d+}/approve-and-send-activation', function ($request, $response, $args) use ($app) {
        $controller = new \App\Controllers\UsersController();
        $db = $app->getContainer()->get('db');
        return $controller->approveAndSendActivation($request, $response, $db, $args);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());
    $app->post('/admin/users/{id:\d+}/activate-directly', function ($request, $response, $args) use ($app) {
        $controller = new \App\Controllers\UsersController();
        $db = $app->getContainer()->get('db');
        return $controller->activateDirectly($request, $response, $db, $args);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // CSV Export route for users
    $app->get('/admin/users/export/csv', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\UsersController();
        $db = $app->getContainer()->get('db');
        return $controller->exportCsv($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(15, 60))->add(new AdminAuthMiddleware()); // 15 requests per minute

    // Authors (protected admin)
    $app->get('/admin/authors', function ($request, $response) use ($app) {
        $controller = new AutoriController();
        $db = $app->getContainer()->get('db');
        return $controller->index($request, $response, $db);
    })->add(new AuthMiddleware(['admin', 'staff', 'standard', 'premium']));
    $app->get('/admin/authors/{id:\d+}', function ($request, $response, $args) use ($app) {
        $controller = new AutoriController();
        $db = $app->getContainer()->get('db');
        return $controller->show($request, $response, $db, (int) $args['id']);
    })->add(new AuthMiddleware(['admin', 'staff', 'standard', 'premium']));
    $app->get('/admin/authors/create', function ($request, $response) {
        $controller = new AutoriController();
        return $controller->createForm($request, $response);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute
    $app->post('/admin/authors/create', function ($request, $response) use ($app) {
        $controller = new AutoriController();
        $db = $app->getContainer()->get('db');
        return $controller->store($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());
    $app->get('/admin/authors/edit/{id:\d+}', function ($request, $response, $args) use ($app) {
        $controller = new AutoriController();
        $db = $app->getContainer()->get('db');
        return $controller->editForm($request, $response, $db, (int) $args['id']);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute
    $app->post('/admin/authors/update/{id:\d+}', function ($request, $response, $args) use ($app) {
        $controller = new AutoriController();
        $db = $app->getContainer()->get('db');
        return $controller->update($request, $response, $db, (int) $args['id']);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());
    // Fallback GET to avoid 405 if user navigates directly
    $app->get('/admin/authors/update/{id:\d+}', function ($request, $response, $args) {
        return $response->withHeader('Location', '/admin/authors/edit/' . (int) $args['id'])->withStatus(302);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute
    $app->post('/admin/authors/delete/{id:\d+}', function ($request, $response, $args) use ($app) {
        $controller = new AutoriController();
        $db = $app->getContainer()->get('db');
        return $controller->delete($request, $response, $db, (int) $args['id']);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Author duplicates management (admin only)
    $app->get('/api/autori/duplicates', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $repo = new \App\Models\AuthorRepository($db);
        $duplicates = $repo->findDuplicates();
        $response->getBody()->write(json_encode(['success' => true, 'duplicates' => $duplicates]));
        return $response->withHeader('Content-Type', 'application/json');
    })->add(new AdminAuthMiddleware());

    $app->post('/api/autori/merge', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        return \App\Support\MergeHelper::handleMergeRequest($request, $response, $db, 'autori');
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Loans (protected admin) - Disabled in catalogue mode
    $app->get('/admin/loans', function ($request, $response) use ($app) {
        if (\App\Support\ConfigStore::isCatalogueMode()) {
            return $response->withHeader('Location', '/admin/dashboard')->withStatus(302);
        }
        $controller = new PrestitiController();
        $db = $app->getContainer()->get('db');
        return $controller->index($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute

    $app->get('/admin/loans/export-csv', function ($request, $response) use ($app) {
        if (\App\Support\ConfigStore::isCatalogueMode()) {
            return $response->withHeader('Location', '/admin/dashboard')->withStatus(302);
        }
        $controller = new PrestitiController();
        $db = $app->getContainer()->get('db');
        return $controller->exportCsv($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(15, 60))->add(new AdminAuthMiddleware()); // 15 exports per minute

    $app->get('/admin/loans/create', function ($request, $response) use ($app) {
        if (\App\Support\ConfigStore::isCatalogueMode()) {
            return $response->withHeader('Location', '/admin/dashboard')->withStatus(302);
        }
        $controller = new PrestitiController();
        $db = $app->getContainer()->get('db');
        return $controller->createForm($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware());

    $app->post('/admin/loans/create', function ($request, $response) use ($app) {
        if (\App\Support\ConfigStore::isCatalogueMode()) {
            return $response->withHeader('Location', '/admin/dashboard')->withStatus(302);
        }
        $controller = new PrestitiController();
        $db = $app->getContainer()->get('db');
        return $controller->store($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Alias inglese
    $app->get('/admin/loans/{id:\d+}/edit', function ($request, $response, $args) {
        return $response->withHeader('Location', '/admin/loans/edit/' . $args['id'])->withStatus(301);
    })->add(new AdminAuthMiddleware());

    $app->get('/admin/loans/edit/{id:\d+}', function ($request, $response, $args) use ($app) {
        if (\App\Support\ConfigStore::isCatalogueMode()) {
            return $response->withHeader('Location', '/admin/dashboard')->withStatus(302);
        }
        $controller = new PrestitiController();
        $db = $app->getContainer()->get('db');
        return $controller->editForm($request, $response, $db, (int) $args['id']);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware());

    $app->post('/admin/loans/update/{id:\d+}', function ($request, $response, $args) use ($app) {
        if (\App\Support\ConfigStore::isCatalogueMode()) {
            return $response->withHeader('Location', '/admin/dashboard')->withStatus(302);
        }
        $controller = new PrestitiController();
        $db = $app->getContainer()->get('db');
        return $controller->update($request, $response, $db, (int) $args['id']);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Books (protected admin)
    $app->get('/admin/books', function ($request, $response) use ($app) {
        $controller = new LibriController();
        $db = $app->getContainer()->get('db');
        return $controller->index($request, $response, $db);
    })->add(new AuthMiddleware(['admin', 'staff', 'standard', 'premium']));

    $app->get('/admin/books/{id:\d+}', function ($request, $response, $args) use ($app) {
        $controller = new LibriController();
        $db = $app->getContainer()->get('db');
        return $controller->show($request, $response, $db, (int) $args['id']);
    })->add(new AuthMiddleware(['admin', 'staff', 'standard', 'premium']));

    $app->get('/admin/books/create', function ($request, $response) use ($app) {
        $controller = new LibriController();
        $db = $app->getContainer()->get('db');
        return $controller->createForm($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute

    $app->post('/admin/books/create', function ($request, $response) use ($app) {
        $controller = new LibriController();
        $db = $app->getContainer()->get('db');
        return $controller->store($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->get('/admin/books/edit/{id:\d+}', function ($request, $response, $args) use ($app) {
        $controller = new LibriController();
        $db = $app->getContainer()->get('db');
        return $controller->editForm($request, $response, $db, (int) $args['id']);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute

    $app->post('/admin/books/update/{id:\d+}', function ($request, $response, $args) use ($app) {
        $controller = new LibriController();
        $db = $app->getContainer()->get('db');
        return $controller->update($request, $response, $db, (int) $args['id']);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->get('/api/libri/{id:\d+}/etichetta-pdf', function ($request, $response, $args) use ($app) {
        $controller = new LibriController();
        $db = $app->getContainer()->get('db');
        return $controller->generateLabelPDF($request, $response, $db, (int) $args['id']);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute

    // Per-copy labels: one label per physical copy, each carrying its numero_inventario
    // as text + Code128 barcode.
    $app->get('/admin/books/{id:\d+}/copy-labels-pdf', function ($request, $response, $args) use ($app) {
        $controller = new LibriController();
        $db = $app->getContainer()->get('db');
        return $controller->generateCopyLabelsPDF($request, $response, $db, (int) $args['id']);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute

    // Fetch cover for a book via scraping
    $app->post('/api/libri/{id:\d+}/fetch-cover', function ($request, $response, $args) use ($app) {
        $controller = new LibriController();
        $db = $app->getContainer()->get('db');
        return $controller->fetchCover($request, $response, $db, (int) $args['id']);
    })->add(new CsrfMiddleware())->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute for bulk operations

    // CSV Import routes
    $app->get('/admin/books/import', function ($request, $response) {
        $controller = new \App\Controllers\CsvImportController();
        return $controller->showImportPage($request, $response);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute

    $app->get('/admin/books/import/example', function ($request, $response) {
        $controller = new \App\Controllers\CsvImportController();
        return $controller->downloadExample($request, $response);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute

    $app->post('/admin/books/import/upload', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\CsvImportController();
        $db = $app->getContainer()->get('db');
        return $controller->processImport($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->get('/admin/books/import/progress', function ($request, $response) {
        $controller = new \App\Controllers\CsvImportController();
        return $controller->getProgress($request, $response);
    })->add(new AdminAuthMiddleware());
    // No RateLimitMiddleware here: this is a read-only progress poll behind
    // admin auth, called every 1-2s by the import UI to refresh the bar.
    // A 30/60s throttle saturated on imports of ~500+ rows (#113) and the
    // user got hard-stuck behind a 429. All import endpoints rely on
    // AdminAuthMiddleware + CsrfMiddleware as the primary defense.

    // CSV Import Chunk Processing (AJAX)
    $app->post('/admin/books/import/chunk', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\CsvImportController();
        $db = $app->getContainer()->get('db');
        return $controller->processChunk($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());
    // No RateLimitMiddleware: chunk processing is sequential (one at a time
    // per JS loop) and each chunk is scoped to a session-bound import_id.
    // A 100/60 cap causes 429 on fast imports (e.g. 1620 rows, no scraping,
    // chunks complete in <370 ms → >100/min). All import endpoints (/upload,
    // /prepare, /chunk) rely on AdminAuthMiddleware + CsrfMiddleware; the
    // chunk loop is further bounded by the session-scoped import_id.
    // See issue #113 for the original rate-limit regression.

    // LibraryThing Plugin Routes

    // Plugin Administration
    $app->get('/admin/plugins/librarything', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\LibraryThingImportController();
        $db = $app->getContainer()->get('db');
        return $controller->showAdminPage($request, $response, $db);
    })->add(new AdminAuthMiddleware());

    $app->post('/admin/plugins/librarything/install', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\LibraryThingImportController();
        $db = $app->getContainer()->get('db');
        return $controller->install($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/plugins/librarything/uninstall', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\LibraryThingImportController();
        $db = $app->getContainer()->get('db');
        return $controller->uninstall($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Import/Export
    $app->get('/admin/books/import/librarything', function ($request, $response) {
        $controller = new \App\Controllers\LibraryThingImportController();
        return $controller->showImportPage($request, $response);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware());

    // Chunked import endpoints (new)
    $app->post('/admin/books/import/librarything/prepare', function ($request, $response) {
        $controller = new \App\Controllers\LibraryThingImportController();
        return $controller->prepareImport($request, $response);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/books/import/librarything/chunk', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\LibraryThingImportController();
        $db = $app->getContainer()->get('db');
        return $controller->processChunk($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());
    // No RateLimitMiddleware: same rationale as CSV /import/chunk. See #113.

    $app->get('/admin/books/import/librarything/results', function ($request, $response) {
        $controller = new \App\Controllers\LibraryThingImportController();
        return $controller->getImportResults($request, $response);
    })->add(new AdminAuthMiddleware());

    // Legacy endpoint (backwards compatibility)
    $app->post('/admin/books/import/librarything/process', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\LibraryThingImportController();
        $db = $app->getContainer()->get('db');
        return $controller->processImport($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->get('/admin/books/import/librarything/progress', function ($request, $response) {
        $controller = new \App\Controllers\LibraryThingImportController();
        return $controller->getProgress($request, $response);
    })->add(new AdminAuthMiddleware());
    // No RateLimitMiddleware: see CSV /import/progress for rationale (#113).

    // Import History routes (Sprint 3)
    $app->get('/admin/imports-history', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\ImportHistoryController();
        $db = $app->getContainer()->get('db');
        return $controller->index($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware());

    $app->get('/admin/imports/download-errors', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\ImportHistoryController();
        $db = $app->getContainer()->get('db');
        return $controller->downloadErrors($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware());

    $app->post('/admin/imports/delete-old-logs', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\ImportHistoryController();
        $db = $app->getContainer()->get('db');
        return $controller->deleteOldLogs($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->get('/admin/books/export/librarything', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\LibraryThingImportController();
        $db = $app->getContainer()->get('db');
        return $controller->exportToLibraryThing($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(15, 60))
      ->add(new AdminAuthMiddleware());

    // CSV Export route
    $app->get('/admin/books/export/csv', function ($request, $response) use ($app) {
        $controller = new LibriController();
        $db = $app->getContainer()->get('db');
        return $controller->exportCsv($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(15, 60))->add(new AdminAuthMiddleware()); // 15 requests per minute

    // Sync covers route
    // Slim 4 route middleware is LIFO: the LAST ->add() runs FIRST. To make
    // sure auth/CSRF rejections don't burn the rate-limit bucket (CR R7),
    // order added so RateLimit is the OUTERMOST and runs LAST: Auth → CSRF
    // → RateLimit. A 401 / 403 short-circuits before any quota is consumed.
    $app->post('/admin/books/sync-covers', function ($request, $response) use ($app) {
        $controller = new LibriController();
        $db = $app->getContainer()->get('db');
        return $controller->syncCovers($request, $response, $db);
    })
        ->add(new \App\Middleware\RateLimitMiddleware(1, 120)) // 1 req / 120s
        ->add(new CsrfMiddleware())
        ->add(new AdminAuthMiddleware());

    // Bulk enrichment routes
    $app->get('/admin/books/bulk-enrich', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\BulkEnrichController();
        return $controller->index($request, $response, $db);
    })->add(new AdminAuthMiddleware());

    // Bulk enrich start: up to 20 external scrapes per request. Rate-limit
    // prevents double-clicks + retries from overlapping batches and burning
    // upstream quota (Discogs / Google Books / Open Library have per-minute
    // limits). Same shape as sync-covers above.
    $app->post('/admin/books/bulk-enrich/start', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\BulkEnrichController();
        return $controller->start($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(1, 120)) // 1 req / 2 min
      ->add(new CsrfMiddleware())
      ->add(new AdminAuthMiddleware());

    $app->post('/admin/books/bulk-enrich/toggle', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\BulkEnrichController();
        return $controller->toggle($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Fallback GET to avoid 405 if user navigates directly
    $app->get('/admin/books/update/{id:\d+}', function ($request, $response, $args) {
        return $response->withHeader('Location', '/admin/books/edit/' . (int) $args['id'])->withStatus(302);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute

    $app->post('/admin/books/delete/{id:\d+}', function ($request, $response, $args) use ($app) {
        $controller = new LibriController();
        $db = $app->getContainer()->get('db');
        return $controller->delete($request, $response, $db, (int) $args['id']);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Copy management routes
    // Resolve a physical copy by its numero_inventario (per-copy code) → JSON.
    $app->get('/admin/copies/by-code', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\CopyController();
        $db = $app->getContainer()->get('db');
        return $controller->byCode($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(60, 60))->add(new AdminAuthMiddleware());

    $app->post('/admin/books/copies/{id:\d+}/update', function ($request, $response, $args) use ($app) {
        $controller = new \App\Controllers\CopyController();
        $db = $app->getContainer()->get('db');
        return $controller->updateCopy($request, $response, $db, (int) $args['id']);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/books/copies/{id:\d+}/delete', function ($request, $response, $args) use ($app) {
        $controller = new \App\Controllers\CopyController();
        $db = $app->getContainer()->get('db');
        return $controller->deleteCopy($request, $response, $db, (int) $args['id']);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/books/{id:\d+}/copies/create', function ($request, $response, $args) use ($app) {
        $controller = new \App\Controllers\CopyController();
        $db = $app->getContainer()->get('db');
        return $controller->createCopy($request, $response, $db, (int) $args['id']);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Series (Series) management
    $app->get('/admin/series', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\CollaneController();
        $db = $app->getContainer()->get('db');
        return $controller->index($request, $response, $db);
    })->add(new AdminAuthMiddleware());

    $app->get('/admin/series/detail', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\CollaneController();
        $db = $app->getContainer()->get('db');
        return $controller->show($request, $response, $db);
    })->add(new AdminAuthMiddleware());

    $app->post('/admin/series/create', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\CollaneController();
        $db = $app->getContainer()->get('db');
        return $controller->create($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/series/delete', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\CollaneController();
        $db = $app->getContainer()->get('db');
        return $controller->delete($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/series/description', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\CollaneController();
        $db = $app->getContainer()->get('db');
        return $controller->saveDescription($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/series/rename', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\CollaneController();
        $db = $app->getContainer()->get('db');
        return $controller->rename($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/series/merge', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\CollaneController();
        $db = $app->getContainer()->get('db');
        return $controller->merge($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/series/order', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\CollaneController();
        $db = $app->getContainer()->get('db');
        return $controller->updateOrder($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/series/remove-book', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\CollaneController();
        $db = $app->getContainer()->get('db');
        return $controller->removeBook($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/series/create-opera', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\CollaneController();
        $db = $app->getContainer()->get('db');
        return $controller->createParentWork($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->get('/api/collane/search', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\CollaneController();
        $db = $app->getContainer()->get('db');
        return $controller->searchApi($request, $response, $db);
    })->add(new AdminAuthMiddleware());

    $app->post('/admin/series/bulk-assign', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\CollaneController();
        $db = $app->getContainer()->get('db');
        return $controller->bulkAssign($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Multi-volume management routes
    $app->post('/admin/books/volumes/add', function ($request, $response) use ($app) {
        $controller = new LibriController();
        $db = $app->getContainer()->get('db');
        return $controller->addVolume($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/books/volumes/remove', function ($request, $response) use ($app) {
        $controller = new LibriController();
        $db = $app->getContainer()->get('db');
        return $controller->removeVolume($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Genres (protected admin/staff only)
    $app->get('/admin/genres', function ($request, $response) use ($app) {
        $controller = new GeneriController();
        $db = $app->getContainer()->get('db');
        return $controller->index($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute

    $app->get('/admin/genres/create', function ($request, $response) use ($app) {
        $controller = new GeneriController();
        $db = $app->getContainer()->get('db');
        return $controller->createForm($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute

    $app->post('/admin/genres/create', function ($request, $response) use ($app) {
        $controller = new GeneriController();
        $db = $app->getContainer()->get('db');
        return $controller->store($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->get('/admin/genres/{id:\d+}', function ($request, $response, $args) use ($app) {
        $controller = new GeneriController();
        $db = $app->getContainer()->get('db');
        return $controller->show($request, $response, $db, (int) $args['id']);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute

    $app->post('/admin/genres/{id:\d+}/edit', function ($request, $response, $args) use ($app) {
        $controller = new GeneriController();
        $db = $app->getContainer()->get('db');
        return $controller->update($request, $response, $db, (int) $args['id']);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/genres/{id:\d+}/merge', function ($request, $response, $args) use ($app) {
        $controller = new GeneriController();
        $db = $app->getContainer()->get('db');
        return $controller->merge($request, $response, $db, (int) $args['id']);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/genres/{id:\d+}/delete', function ($request, $response, $args) use ($app) {
        $controller = new GeneriController();
        $db = $app->getContainer()->get('db');
        return $controller->destroy($request, $response, $db, (int) $args['id']);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Placement (protected admin)
    $app->get('/admin/placement', function ($request, $response) use ($app) {
        $controller = new CollocazioneController();
        $db = $app->getContainer()->get('db');
        return $controller->index($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute
    $app->post('/admin/placement/shelving-units', function ($request, $response) use ($app) {
        $controller = new CollocazioneController();
        $db = $app->getContainer()->get('db');
        return $controller->createScaffale($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());
    $app->post('/admin/placement/shelves', function ($request, $response) use ($app) {
        $controller = new CollocazioneController();
        $db = $app->getContainer()->get('db');
        return $controller->createMensola($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());
    $app->post('/admin/placement/shelving-units/{id}/delete', function ($request, $response, $args) use ($app) {
        $controller = new CollocazioneController();
        $db = $app->getContainer()->get('db');
        return $controller->deleteScaffale($request, $response, $db, (int) $args['id']);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());
    $app->post('/admin/placement/shelves/{id}/delete', function ($request, $response, $args) use ($app) {
        $controller = new CollocazioneController();
        $db = $app->getContainer()->get('db');
        return $controller->deleteMensola($request, $response, $db, (int) $args['id']);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());
    $app->get('/api/collocazione/suggerisci', function ($request, $response) use ($app) {
        $controller = new CollocazioneController();
        $db = $app->getContainer()->get('db');
        return $controller->suggest($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute
    $app->get('/api/collocazione/next', function ($request, $response) use ($app) {
        $controller = new CollocazioneController();
        $db = $app->getContainer()->get('db');
        return $controller->nextPosition($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute
    $app->post('/api/collocazione/sort', function ($request, $response) use ($app) {
        $controller = new CollocazioneController();
        $db = $app->getContainer()->get('db');
        return $controller->sort($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());
    $app->get('/api/collocazione/libri', function ($request, $response) use ($app) {
        $controller = new CollocazioneController();
        $db = $app->getContainer()->get('db');
        return $controller->getLibri($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute
    $app->get('/api/collocazione/export-csv', function ($request, $response) use ($app) {
        $controller = new CollocazioneController();
        $db = $app->getContainer()->get('db');
        return $controller->exportCSV($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute

    // Loans (protected) - Disabled in catalogue mode
    $app->get('/prestiti', function ($request, $response) use ($app) {
        if (\App\Support\ConfigStore::isCatalogueMode()) {
            return $response->withHeader('Location', '/admin/dashboard')->withStatus(302);
        }
        $controller = new PrestitiController();
        $db = $app->getContainer()->get('db');
        return $controller->index($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute
    $app->get('/prestiti/crea', function ($request, $response) use ($app) {
        if (\App\Support\ConfigStore::isCatalogueMode()) {
            return $response->withHeader('Location', '/admin/dashboard')->withStatus(302);
        }
        $controller = new PrestitiController();
        $db = $app->getContainer()->get('db');
        return $controller->createForm($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute
    $app->post('/prestiti/crea', function ($request, $response) use ($app) {
        if (\App\Support\ConfigStore::isCatalogueMode()) {
            return $response->withHeader('Location', '/admin/dashboard')->withStatus(302);
        }
        $controller = new PrestitiController();
        $db = $app->getContainer()->get('db');
        return $controller->store($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());
    $app->get('/prestiti/modifica/{id:\d+}', function ($request, $response, $args) use ($app) {
        $controller = new PrestitiController();
        $db = $app->getContainer()->get('db');
        return $controller->editForm($request, $response, $db, (int) $args['id']);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute
    $app->post('/prestiti/update/{id:\d+}', function ($request, $response, $args) use ($app) {
        $controller = new PrestitiController();
        $db = $app->getContainer()->get('db');
        return $controller->update($request, $response, $db, (int) $args['id']);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());
    $app->post('/prestiti/close/{id:\d+}', function ($request, $response, $args) use ($app) {
        $controller = new PrestitiController();
        $db = $app->getContainer()->get('db');
        return $controller->close($request, $response, $db, (int) $args['id']);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());
    $app->get('/prestiti/restituito/{id:\d+}', function ($request, $response, $args) use ($app) {
        $controller = new PrestitiController();
        $db = $app->getContainer()->get('db');
        return $controller->returnForm($request, $response, $db, (int) $args['id']);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute
    $app->post('/prestiti/restituito/{id:\d+}', function ($request, $response, $args) use ($app) {
        $controller = new PrestitiController();
        $db = $app->getContainer()->get('db');
        return $controller->processReturn($request, $response, $db, (int) $args['id']);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());
    $app->get('/prestiti/dettagli/{id:\d+}', function ($request, $response, $args) use ($app) {
        $controller = new PrestitiController();
        $db = $app->getContainer()->get('db');
        return $controller->details($request, $response, $db, (int) $args['id']);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute

    // Loan approval routes - Disabled in catalogue mode
    $app->get('/admin/loans/pending', function ($request, $response) use ($app) {
        if (\App\Support\ConfigStore::isCatalogueMode()) {
            return $response->withHeader('Location', '/admin/dashboard')->withStatus(302);
        }
        $controller = new LoanApprovalController();
        $db = $app->getContainer()->get('db');
        return $controller->pendingLoans($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute

    $app->post('/admin/loans/approve', function ($request, $response) use ($app) {
        if (\App\Support\ConfigStore::isCatalogueMode()) {
            return $response->withHeader('Location', '/admin/dashboard')->withStatus(302);
        }
        $controller = new LoanApprovalController();
        $db = $app->getContainer()->get('db');
        return $controller->approveLoan($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/loans/reject', function ($request, $response) use ($app) {
        if (\App\Support\ConfigStore::isCatalogueMode()) {
            return $response->withHeader('Location', '/admin/dashboard')->withStatus(302);
        }
        $controller = new LoanApprovalController();
        $db = $app->getContainer()->get('db');
        return $controller->rejectLoan($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/loans/confirm-pickup', function ($request, $response) use ($app) {
        if (\App\Support\ConfigStore::isCatalogueMode()) {
            return $response->withHeader('Location', '/admin/dashboard')->withStatus(302);
        }
        $controller = new LoanApprovalController();
        $db = $app->getContainer()->get('db');
        return $controller->confirmPickup($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/loans/cancel-pickup', function ($request, $response) use ($app) {
        if (\App\Support\ConfigStore::isCatalogueMode()) {
            return $response->withHeader('Location', '/admin/dashboard')->withStatus(302);
        }
        $controller = new LoanApprovalController();
        $db = $app->getContainer()->get('db');
        return $controller->cancelPickup($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/loans/return', function ($request, $response) use ($app) {
        if (\App\Support\ConfigStore::isCatalogueMode()) {
            return $response->withHeader('Location', '/admin/dashboard')->withStatus(302);
        }
        $controller = new LoanApprovalController();
        $db = $app->getContainer()->get('db');
        return $controller->returnLoan($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/loans/cancel-reservation', function ($request, $response) use ($app) {
        if (\App\Support\ConfigStore::isCatalogueMode()) {
            return $response->withHeader('Location', '/admin/dashboard')->withStatus(302);
        }
        $controller = new LoanApprovalController();
        $db = $app->getContainer()->get('db');
        return $controller->cancelReservation($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Maintenance routes
    $app->get('/admin/maintenance/integrity-report', function ($request, $response) use ($app) {
        $controller = new MaintenanceController();
        $db = $app->getContainer()->get('db');
        return $controller->integrityReport($request, $response, $db);
    })->add(new AuthMiddleware(['admin']));

    $app->post('/admin/maintenance/fix-issues', function ($request, $response) use ($app) {
        $controller = new MaintenanceController();
        $db = $app->getContainer()->get('db');
        return $controller->fixIntegrityIssues($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AuthMiddleware(['admin']));

    $app->post('/admin/maintenance/recalculate-availability', function ($request, $response) use ($app) {
        $controller = new MaintenanceController();
        $db = $app->getContainer()->get('db');
        return $controller->recalculateAvailability($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AuthMiddleware(['admin']));

    $app->post('/admin/maintenance/perform', function ($request, $response) use ($app) {
        $controller = new MaintenanceController();
        $db = $app->getContainer()->get('db');
        return $controller->performMaintenance($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AuthMiddleware(['admin']));

    $app->post('/admin/maintenance/apply-config-fix', function ($request, $response) {
        $controller = new MaintenanceController();
        return $controller->applyConfigFix($request, $response);
    })->add(new CsrfMiddleware())->add(new AuthMiddleware(['admin']));

    // Index optimization routes
    $app->post('/admin/maintenance/create-indexes', function ($request, $response) use ($app) {
        $controller = new MaintenanceController();
        $db = $app->getContainer()->get('db');
        return $controller->createMissingIndexes($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AuthMiddleware(['admin']));

    $app->get('/admin/maintenance/indexes-sql', function ($request, $response) use ($app) {
        $controller = new MaintenanceController();
        $db = $app->getContainer()->get('db');
        return $controller->generateIndexesSQL($request, $response, $db);
    })->add(new AuthMiddleware(['admin']));

    // System tables creation route
    $app->post('/admin/maintenance/create-system-tables', function ($request, $response) use ($app) {
        $controller = new MaintenanceController();
        $db = $app->getContainer()->get('db');
        return $controller->createMissingSystemTables($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AuthMiddleware(['admin']));

    $app->get('/admin/loans/returned/{id:\d+}', function ($request, $response, $args) use ($app) {
        $controller = new PrestitiController();
        $db = $app->getContainer()->get('db');
        return $controller->returnForm($request, $response, $db, (int) $args['id']);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute
    $app->post('/admin/loans/returned/{id:\d+}', function ($request, $response, $args) use ($app) {
        $controller = new PrestitiController();
        $db = $app->getContainer()->get('db');
        return $controller->processReturn($request, $response, $db, (int) $args['id']);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());
    $app->post('/admin/loans/renew/{id:\d+}', function ($request, $response, $args) use ($app) {
        $controller = new PrestitiController();
        $db = $app->getContainer()->get('db');
        return $controller->renew($request, $response, $db, (int) $args['id']);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());
    // #281: extend the due date of several selected active loans at once.
    $app->post('/admin/loans/bulk-extend', function ($request, $response) use ($app) {
        if (\App\Support\ConfigStore::isCatalogueMode()) {
            return $response->withHeader('Location', '/admin/dashboard')->withStatus(302);
        }
        $controller = new PrestitiController();
        $db = $app->getContainer()->get('db');
        return $controller->bulkExtend($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());
    // Return a loan by scanning/typing the physical copy code (numero_inventario)
    $app->post('/admin/loans/return-by-code', function ($request, $response) use ($app) {
        if (\App\Support\ConfigStore::isCatalogueMode()) {
            return $response->withHeader('Location', '/admin/dashboard')->withStatus(302);
        }
        $controller = new PrestitiController();
        $db = $app->getContainer()->get('db');
        return $controller->returnByCode($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());
    $app->get('/admin/loans/details/{id:\d+}', function ($request, $response, $args) use ($app) {
        $controller = new PrestitiController();
        $db = $app->getContainer()->get('db');
        return $controller->details($request, $response, $db, (int) $args['id']);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute

    // PDF prestito
    $app->get('/admin/loans/{id:\d+}/pdf', function ($request, $response, $args) use ($app) {
        $controller = new PrestitiController();
        $db = $app->getContainer()->get('db');
        return $controller->downloadPdf($request, $response, $db, (int) $args['id']);
    })->add(new AdminAuthMiddleware())->add(new CsrfMiddleware());

    // #360: invia la ricevuta PDF del prestito via email all'utente.
    // RateLimit aggiunto per primo (LIFO: eseguito per ultimo, dopo Auth e
    // CSRF) come /admin/settings/email/test — ogni chiamata è un vero
    // handshake SMTP. L'actionKey rende il bucket per-client e non per-path:
    // senza, ogni {id} avrebbe il proprio contatore e il limite sarebbe
    // aggirabile iterando i prestiti.
    $app->post('/admin/loans/{id:\d+}/email-pdf', function ($request, $response, $args) use ($app) {
        $controller = new PrestitiController();
        $db = $app->getContainer()->get('db');
        return $controller->emailPdf($request, $response, $db, (int) $args['id']);
    })->add(new \App\Middleware\RateLimitMiddleware(10, 60, 'loan-email-pdf'))->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // #360: sollecito manuale per un singolo prestito scaduto
    $app->post('/admin/loans/{id:\d+}/recall', function ($request, $response, $args) use ($app) {
        $controller = new PrestitiController();
        $db = $app->getContainer()->get('db');
        return $controller->sendRecall($request, $response, $db, (int) $args['id']);
    })->add(new \App\Middleware\RateLimitMiddleware(10, 60, 'loan-recall'))->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // #360: sollecito in blocco per i prestiti selezionati nella lista
    // (fino a 50 invii SMTP per richiesta: limite più stretto)
    $app->post('/admin/loans/bulk-recall', function ($request, $response) use ($app) {
        if (\App\Support\ConfigStore::isCatalogueMode()) {
            return $response->withHeader('Location', '/admin/dashboard')->withStatus(302);
        }
        $controller = new PrestitiController();
        $db = $app->getContainer()->get('db');
        return $controller->bulkRecall($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(5, 60, 'loan-bulk-recall'))->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // API loans per DataTables
    $app->get('/api/prestiti', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\PrestitiApiController();
        $db = $app->getContainer()->get('db');
        return $controller->list($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute

    // API users per DataTables
    $app->get('/api/utenti', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\UtentiApiController();
        $db = $app->getContainer()->get('db');
        return $controller->list($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute

    // Server-side PDF export of the (filtered) users list — reuses UtentiApiController's
    // filter logic so the PDF matches the on-screen table. Replaces a dead client-side jsPDF.
    $app->get('/admin/users/export-pdf', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\UtentiApiController();
        $db = $app->getContainer()->get('db');
        return $controller->exportPdf($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(10, 60))->add(new AdminAuthMiddleware());

    // Reservations (admin)
    $app->get('/admin/reservations', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new ReservationsAdminController();
        return $controller->index($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute
    $app->get('/admin/reservations/create', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new ReservationsAdminController();
        return $controller->createForm($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute
    $app->post('/admin/reservations/create', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new ReservationsAdminController();
        return $controller->store($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());
    $app->get('/admin/reservations/edit/{id:\\d+}', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new ReservationsAdminController();
        return $controller->editForm($request, $response, $db, (int) $args['id']);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute
    $app->post('/admin/reservations/update/{id:\\d+}', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new ReservationsAdminController();
        return $controller->update($request, $response, $db, (int) $args['id']);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Book availability endpoint
    $app->get('/api/books/{id:\\d+}/availability', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $bookId = (int) $args['id'];
        $data = ['available' => false, 'copies_available' => 0, 'copies_total' => 0, 'copies_owned' => 0, 'copies_out_of_circulation' => 0, 'next_due_date' => null, 'queue' => 0];
        // Copies info
        $stmt = $db->prepare("SELECT copie_disponibili, copie_totali FROM libri WHERE id = ? AND deleted_at IS NULL");
        $stmt->bind_param('i', $bookId);
        $stmt->execute();
        $res = $stmt->get_result();
        $bookFound = false;
        if ($row = $res->fetch_assoc()) {
            $bookFound = true;
            $data['copies_available'] = (int) ($row['copie_disponibili'] ?? 0);
            // copies_total stays the lending capacity (copies in circulation);
            // copies_owned is what the catalogue publishes, so a book whose only
            // copy is under maintenance reads "0 / 1", not "0 / 0" (#426).
            $data['copies_total'] = (int) ($row['copie_totali'] ?? 0);
            $holdings = \App\Support\CopyHoldings::forBook($db, $bookId);
            $data['copies_owned'] = \App\Support\CopyHoldings::publishedTotal($holdings, $data['copies_total']);
            $data['copies_out_of_circulation'] = $holdings['out'] ?? 0;
        }
        $stmt->close();
        if (!$bookFound) {
            $response->getBody()->write(json_encode(['success' => false, 'message' => __('Libro non trovato')]));
            return $response->withStatus(404)->withHeader('Content-Type', 'application/json');
        }
        $data['available'] = ($data['copies_available'] > 0);
        // Next due date among HOLDING loans, never in the past. The bare
        // `attivo = 1` version could return the past data_scadenza of an
        // in_ritardo loan ("available again on <date already gone>") or the
        // far-future date of a scheduled prenotato — align the predicate with
        // NotificationService::getNextAvailabilityDate.
        if (!$data['available']) {
            $today = \App\Support\DateHelper::today();
            $stmt = $db->prepare("SELECT MIN(data_scadenza) AS next_due FROM prestiti
                WHERE libro_id = ? AND attivo = 1
                  AND stato IN ('in_corso','in_ritardo','da_ritirare','prenotato')
                  AND data_scadenza >= ?");
            $stmt->bind_param('is', $bookId, $today);
            $stmt->execute();
            $res = $stmt->get_result();
            $row = $res->fetch_assoc();
            $data['next_due_date'] = $row && !empty($row['next_due']) ? $row['next_due'] : null;
            $stmt->close();
        }
        // Queue size
        $stmt = $db->prepare("SELECT COUNT(*) AS c FROM prenotazioni WHERE libro_id = ? AND stato = 'attiva'");
        $stmt->bind_param('i', $bookId);
        $stmt->execute();
        $res = $stmt->get_result();
        $data['queue'] = (int) ($res->fetch_assoc()['c'] ?? 0);
        $stmt->close();
        $response->getBody()->write(json_encode($data));
        return $response->withHeader('Content-Type', 'application/json');
    })->add(new AuthMiddleware(['admin', 'staff', 'standard', 'premium']));

    // Availability calendar (per-day availability for next N days)
    $app->get('/api/books/{id:\\d+}/availability-calendar', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $bookId = (int) $args['id'];
        $days = (int) (($request->getQueryParams()['days'] ?? 60));
        if ($days < 1)
            $days = 30;
        if ($days > 180)
            $days = 180;
        $controller = new \App\Controllers\ReservationsController($db);
        // Exclude the requesting user's own reservations, like the mobile
        // calendar and the server-side write gate already do: without it the
        // picker painted the user's own reserved days red while the server
        // would have accepted the same dates.
        // F012: the admin loan form fetches this same route while creating a loan
        // FOR a borrower who is NOT the session operator. When an admin/staff
        // passes ?for_user=<id>, exclude THAT borrower's reservations instead of
        // the operator's, so the calendar matches the write gate. Anonymous or
        // non-privileged callers stay on the session id (self-service default).
        $sessionUserId = isset($_SESSION['user']['id']) ? (int) $_SESSION['user']['id'] : null;
        $forUser = $request->getQueryParams()['for_user'] ?? null;
        $excludeUserId = $sessionUserId;
        // Whoever may record loans (admin, staff, a loan-desk role) previews for the borrower.
        if ($forUser !== null && is_numeric($forUser) && \App\Support\Permissions::can('loans.manage')) {
            $excludeUserId = (int) $forUser;
        }
        $availability = $controller->getBookAvailabilityData($bookId, \App\Support\DateHelper::today(), $days, $excludeUserId);
        if ($availability === null) {
            $response->getBody()->write(json_encode(['success' => false, 'message' => __('Libro non trovato')]));
            return $response->withStatus(404)->withHeader('Content-Type', 'application/json');
        }

        $response->getBody()->write(json_encode([
            'total_copies' => $availability['total_copies'] ?? 0,
            'days' => array_slice($availability['days'] ?? [], 0, $days)
        ]));
        return $response->withHeader('Content-Type', 'application/json');
    })->add(new AuthMiddleware(['admin', 'staff', 'standard', 'premium']));

    // Debug endpoint intentionally removed to avoid accidental exposure of sensitive data

    // Publishers (protected)
    $app->get('/admin/publishers', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\EditorsController();
        $db = $app->getContainer()->get('db');
        return $controller->index($request, $response, $db);
    })->add(new AuthMiddleware(['admin', 'staff', 'standard', 'premium']));
    $app->get('/admin/publishers/{id:\d+}', function ($request, $response, $args) use ($app) {
        $controller = new \App\Controllers\EditorsController();
        $db = $app->getContainer()->get('db');
        return $controller->show($request, $response, $db, (int) $args['id']);
    })->add(new AuthMiddleware(['admin', 'staff', 'standard', 'premium']));
    $app->get('/admin/publishers/create', function ($request, $response) {
        $controller = new \App\Controllers\EditorsController();
        return $controller->createForm($request, $response);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute
    $app->post('/admin/publishers/create', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\EditorsController();
        $db = $app->getContainer()->get('db');
        return $controller->store($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());
    $app->get('/admin/publishers/edit/{id:\d+}', function ($request, $response, $args) use ($app) {
        $controller = new \App\Controllers\EditorsController();
        $db = $app->getContainer()->get('db');
        return $controller->editForm($request, $response, $db, (int) $args['id']);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute
    $app->post('/admin/publishers/update/{id:\d+}', function ($request, $response, $args) use ($app) {
        $controller = new \App\Controllers\EditorsController();
        $db = $app->getContainer()->get('db');
        return $controller->update($request, $response, $db, (int) $args['id']);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());
    // API Dewey (basata su JSON) - PROTETTO: Solo admin e staff
    $app->get('/api/dewey/categories', [DeweyApiController::class, 'getCategories'])->add(new AdminAuthMiddleware());
    $app->get('/api/dewey/divisions', [DeweyApiController::class, 'getDivisions'])->add(new AdminAuthMiddleware());
    $app->get('/api/dewey/specifics', [DeweyApiController::class, 'getSpecifics'])->add(new AdminAuthMiddleware());
    // Nuovi endpoint per formato completo con decimali (fino a livello 7)
    $app->get('/api/dewey/children', [DeweyApiController::class, 'getChildren'])->add(new AdminAuthMiddleware());
    $app->get('/api/dewey/search', [DeweyApiController::class, 'search'])->add(new AdminAuthMiddleware());
    $app->get('/api/dewey/autocomplete', [DeweyApiController::class, 'autocomplete'])->add(new AdminAuthMiddleware());
    $app->get('/api/dewey/path', [DeweyApiController::class, 'getPath'])->add(new AdminAuthMiddleware());
    // Reseed endpoint (per compatibilità - ora non fa nulla) - PROTETTO: Solo admin
    $app->post('/api/dewey/reseed', [DeweyApiController::class, 'reseed'])->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());
    // Bug-hunt #3-3: previously open to any visitor with a session CSRF;
    // restricted to admin/staff (the legitimate caller is the admin book
    // form's "download cover" button) plus rate limit to prevent disk-fill
    // / SSRF amplification.
    $app->post('/api/cover/download', function ($request, $response) {
        $controller = new \App\Controllers\CoverController();
        return $controller->download($request, $response);
    })
        // LIFO order (CR R7): RateLimit added first runs last so 401/403
        // from Auth/CSRF doesn't consume the throttle bucket.
        ->add(new \App\Middleware\RateLimitMiddleware(10, 60))
        ->add(new CsrfMiddleware())
        ->add(new AdminAuthMiddleware());
    // Admin-only: this DataTables feed runs SELECT l.* and exposes internal
    // fields (prezzo, note_varie, numero_inventario, tipo_acquisizione,
    // collocazione) never shown on the public catalog. Guard it like its
    // sibling /api/libri/bulk-* routes so anonymous visitors can't page
    // through internal book data (CWE-862).
    $app->get('/api/libri', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\LibriApiController();
        $db = $app->getContainer()->get('db');
        return $controller->list($request, $response, $db);
    })->add(new AdminAuthMiddleware());
    // API Autori (server-side DataTables)
    // Admin-only: this feed returns biografia, sito_web and the life dates,
    // and it was the one registration in its block chaining no auth while its
    // bulk-delete and bulk-export siblings did (CWE-306). Its only consumer is
    // the /admin/authors DataTables — the book form's author picker is a
    // different endpoint, /api/search/autori — so gating it costs no caller.
    $app->get('/api/autori', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\AutoriApiController();
        $db = $app->getContainer()->get('db');
        return $controller->list($request, $response, $db);
    })->add(new AdminAuthMiddleware());

    // API Autori - Bulk Delete
    $app->post('/api/autori/bulk-delete', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\AutoriApiController();
        $db = $app->getContainer()->get('db');
        return $controller->bulkDelete($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // API Autori - Bulk Export
    $app->post('/api/autori/bulk-export', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\AutoriApiController();
        $db = $app->getContainer()->get('db');
        return $controller->bulkExport($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // API Editori (server-side DataTables)
    // Admin-only: this feed runs SELECT e.* and exposes publisher PII
    // (telefono, email, referente_*, codice_fiscale). Guard it like its
    // sibling /api/editori/bulk-* and merge routes so anonymous visitors
    // can't exfiltrate contact data (CWE-862).
    $app->get('/api/editori', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\EditoriApiController();
        $db = $app->getContainer()->get('db');
        return $controller->list($request, $response, $db);
    })->add(new AdminAuthMiddleware());

    // API Editori - Bulk Delete
    $app->post('/api/editori/bulk-delete', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\EditoriApiController();
        $db = $app->getContainer()->get('db');
        return $controller->bulkDelete($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // API Editori - Bulk Export
    $app->post('/api/editori/bulk-export', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\EditoriApiController();
        $db = $app->getContainer()->get('db');
        return $controller->bulkExport($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // API Editori - Merge
    $app->post('/api/editori/merge', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        return \App\Support\MergeHelper::handleMergeRequest($request, $response, $db, 'editori');
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Public picker feed; SessionRoleRefreshMiddleware re-validates the operator
    // claim that decides whether author life dates are included (CWE-613).
    $app->get('/api/search/autori', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\SearchController();
        $db = $app->getContainer()->get('db');
        return $controller->authors($request, $response, $db);
    })->add(new SessionRoleRefreshMiddleware(null, $app->getContainer()));
    $app->get('/api/search/editori', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\SearchController();
        $db = $app->getContainer()->get('db');
        return $controller->publishers($request, $response, $db);
    });
    // PII endpoint: only admin/staff may enumerate users (Bug-hunt #3-1).
    // Pre-fix this route was unauthenticated and leaked first/last name +
    // tessera codes via search.
    $app->get('/api/search/utenti', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\SearchController();
        $db = $app->getContainer()->get('db');
        return $controller->users($request, $response, $db);
    })->add(new AdminAuthMiddleware());
    $app->get('/api/search/libri', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\SearchController();
        $db = $app->getContainer()->get('db');
        return $controller->books($request, $response, $db);
    });

    // API to get book availability dates for calendar display.
    // Autenticato come il gemello /api/books/{id}/availability (L6):
    // occupied_ranges espone le date dei prestiti degli utenti e non deve
    // essere leggibile da client anonimi.
    $app->get('/api/libri/{id}/disponibilita', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $libroId = (int)$args['id'];

        // Verifica esistenza libro
        $bookStmt = $db->prepare("SELECT copie_disponibili, copie_totali FROM libri WHERE id = ? AND deleted_at IS NULL");
        $bookStmt->bind_param('i', $libroId);
        $bookStmt->execute();
        $book = $bookStmt->get_result()->fetch_assoc();
        $bookStmt->close();
        if (!$book) {
            $response->getBody()->write(json_encode(['success' => false, 'message' => __('Libro non trovato')]));
            return $response->withStatus(404)->withHeader('Content-Type', 'application/json');
        }

        // Intervalli occupati (per la visualizzazione). Predicato HOLDING completo
        // (#157): oltre agli stati attivi, anche il 'pendente' da conversione
        // prenotazione che detiene già una copia. Senza questi due archi il
        // payload si contraddiceva: occupied_ranges diceva "libero" mentre
        // first_available/is_available_now (calcolati per-giorno qui sotto)
        // contavano anche pendenti-con-copia e coda prenotazioni.
        $today = \App\Support\DateHelper::today();
        $stmt = $db->prepare("
            SELECT data_prestito,
                   CASE
                       WHEN stato = 'in_ritardo'
                            OR (stato = 'in_corso' AND data_scadenza < ?)
                       THEN '9999-12-31'
                       ELSE data_scadenza
                   END AS occupied_until,
                   stato
            FROM prestiti
            WHERE libro_id = ? AND (
                (attivo = 1 AND stato IN ('in_corso', 'da_ritirare', 'prenotato', 'in_ritardo'))
                OR (attivo = 0 AND stato = 'pendente' AND copia_id IS NOT NULL)
            )
            ORDER BY data_prestito
        ");
        $stmt->bind_param('si', $today, $libroId);
        $stmt->execute();
        $result = $stmt->get_result();
        $occupiedRanges = [];
        while ($row = $result->fetch_assoc()) {
            $occupiedRanges[] = [
                'from' => $row['data_prestito'],
                // An overdue, unreturned copy has no known release date. Keep
                // this display payload aligned with CapacityService, which
                // treats it as occupied for every future availability day.
                'to' => $row['occupied_until'],
                'stato' => $row['stato']
            ];
        }
        $stmt->close();

        // Anche la coda prenotazioni occupa il suo periodo promesso (stessa
        // regola di CapacityService): catena COALESCE canonica per i bound.
        $resStmt = $db->prepare("
            SELECT COALESCE(data_inizio_richiesta, DATE(data_scadenza_prenotazione)) AS r_start,
                   COALESCE(data_fine_richiesta, DATE(data_scadenza_prenotazione), data_inizio_richiesta) AS r_end
            FROM prenotazioni
            WHERE libro_id = ? AND stato = 'attiva'
            ORDER BY queue_position ASC
        ");
        $resStmt->bind_param('i', $libroId);
        $resStmt->execute();
        $resResult = $resStmt->get_result();
        while ($row = $resResult->fetch_assoc()) {
            if (!empty($row['r_start'])) {
                $occupiedRanges[] = [
                    'from' => $row['r_start'],
                    'to' => $row['r_end'] ?? $row['r_start'],
                    'stato' => 'prenotazione'
                ];
            }
        }
        $resStmt->close();

        // first_available / is_available_now: delega al calcolo per-giorno e per-copia
        // (AVAIL-001). Il vecchio "giorno dopo la scadenza più lontana" ignorava le
        // copie multiple, restituendo una data troppo conservativa.
        $reservations = new \App\Controllers\ReservationsController($db);
        $availability = $reservations->getBookAvailabilityData($libroId, $today, 180);
        if ($availability === null) {
            // The book was soft-deleted after the initial lookup above. Keep the
            // nullable provider contract consistent with the sibling endpoints.
            $response->getBody()->write(json_encode(['success' => false, 'message' => __('Libro non trovato')]));
            return $response->withStatus(404)->withHeader('Content-Type', 'application/json');
        }
        $todayData = $availability['by_date'][$today] ?? null;
        $isAvailableNow = $todayData !== null && (int) ($todayData['available'] ?? 0) > 0;

        $data = [
            'libro_id' => $libroId,
            'copie_disponibili' => (int)($book['copie_disponibili'] ?? 0),
            'copie_totali' => (int)($availability['total_copies'] ?? ($book['copie_totali'] ?? 0)),
            'occupied_ranges' => $occupiedRanges,
            'first_available' => $availability['earliest_available'] ?? null,
            'is_available_now' => $isAvailableNow
        ];

        $response->getBody()->write(json_encode($data, JSON_UNESCAPED_UNICODE));
        return $response->withHeader('Content-Type', 'application/json');
    })->add(new AuthMiddleware(['admin', 'staff', 'standard', 'premium']));

    // NOTE: /api/libro/{id}/availability is registered via $registerRouteIfUnique
    // in the translated routes block below (line ~2147) to avoid duplicate route errors.

    $app->get('/api/search/collocazione', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\SearchController();
        $db = $app->getContainer()->get('db');
        return $controller->locations($request, $response, $db);
    });

    // API for Generi (Genres)
    $app->get('/api/search/generi', function ($request, $response) use ($app) {
        $controller = new GeneriApiController();
        $db = $app->getContainer()->get('db');
        return $controller->search($request, $response, $db);
    });

    // Stays open — plugins publish sources into it through the
    // `search.unified.sources` hook and the archives suite drives it logged
    // out — but its results are scoped by operator role, and a role read on a
    // route with no middleware is the login-time snapshot with nothing
    // refreshing it (CWE-613). SessionRoleRefreshMiddleware re-validates the
    // claim against the DB and lets everyone through; AdminAuthMiddleware
    // cannot go here because it would answer 401 to the anonymous callers.
    $app->get('/api/search/unified', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\SearchController();
        $db = $app->getContainer()->get('db');
        return $controller->unifiedSearch($request, $response, $db);
    })->add(new SessionRoleRefreshMiddleware(null, $app->getContainer()));
    $app->get('/api/search/preview', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\SearchController();
        $db = $app->getContainer()->get('db');
        return $controller->searchPreview($request, $response, $db);
    });
    $app->post('/api/generi', function ($request, $response) use ($app) {
        $controller = new GeneriApiController();
        $db = $app->getContainer()->get('db');
        return $controller->create($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());
    $app->get('/api/generi', function ($request, $response) use ($app) {
        $controller = new GeneriApiController();
        $db = $app->getContainer()->get('db');
        return $controller->listGeneri($request, $response, $db);
    });
    $app->get('/api/generi/sottogeneri', function ($request, $response) use ($app) {
        $controller = new GeneriApiController();
        $db = $app->getContainer()->get('db');
        return $controller->getSottogeneri($request, $response, $db);
    });
    $app->post('/api/generi/{id:\d+}', function ($request, $response, $args) use ($app) {
        $controller = new GeneriApiController();
        $db = $app->getContainer()->get('db');
        return $controller->update($request, $response, $db, (int) $args['id']);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());
    // Editor delete route

    // API per scraping dati libro tramite ISBN - PROTETTO: Solo admin e staff
    $app->get("/api/scrape/isbn", function ($request, $response) {
        $controller = new \App\Controllers\ScrapeController();
        // FIX F003: mark this as the top-level HTTP entry so byIsbn() can safely
        // release the session lock (session_write_close). In-process callers
        // (LibriController::fetchCover, Support\ScrapingService::scrapeBookData)
        // do NOT set this attribute, so the session stays open and their
        // subsequent $_SESSION writes are preserved.
        $request = $request->withAttribute('scrape.http_entry', true);
        return $controller->byIsbn($request, $response);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware()); // 30 requests per minute



    // Publishers - Delete
    $app->post('/admin/publishers/delete/{id:\d+}', function ($request, $response, $args) use ($app) {
        $controller = new \App\Controllers\EditorsController();
        $db = $app->getContainer()->get('db');
        return $controller->delete($request, $response, $db, (int) $args['id']);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // API Libri by Author/Publisher
    $app->get('/api/libri/author/{id:\d+}', function ($request, $response, $args) use ($app) {
        $controller = new \App\Controllers\LibriApiController();
        $db = $app->getContainer()->get('db');
        return $controller->getByAuthor($request, $response, $db, (int) $args['id']);
    })->add(new AuthMiddleware(['admin', 'staff', 'standard', 'premium']));

    $app->get('/api/libri/publisher/{id:\d+}', function ($request, $response, $args) use ($app) {
        $controller = new \App\Controllers\LibriApiController();
        $db = $app->getContainer()->get('db');
        return $controller->getByPublisher($request, $response, $db, (int) $args['id']);
    })->add(new AuthMiddleware(['admin', 'staff', 'standard', 'premium']));

    // API Libri by Genre (public for homepage carousels)
    $app->get('/api/libri/genre/{id:\d+}', function ($request, $response, $args) use ($app) {
        $controller = new \App\Controllers\LibriApiController();
        $db = $app->getContainer()->get('db');
        return $controller->byGenre($request->withQueryParams(array_merge(
            $request->getQueryParams(),
            ['genre_id' => (int) $args['id']]
        )), $response, $db);
    });

    // API Bulk operations (admin only)
    $app->post('/api/libri/bulk-status', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\LibriApiController();
        $db = $app->getContainer()->get('db');
        return $controller->bulkStatus($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/api/libri/bulk-delete', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\LibriApiController();
        $db = $app->getContainer()->get('db');
        return $controller->bulkDelete($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Manual bulk edit of one field across the selection (issue #380)
    $app->post('/api/libri/bulk-edit', function ($request, $response) use ($app) {
        $controller = new \App\Controllers\LibriApiController();
        $db = $app->getContainer()->get('db');
        return $controller->bulkEdit($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // API Increase copies of a book (admin only)
    $app->post('/api/libri/{id:\d+}/increase-copies', function ($request, $response, $args) use ($app) {
        $db = $app->getContainer()->get('db');
        $bookId = (int) $args['id'];

        // Get request body
        $body = $request->getParsedBody();
        if (!is_array($body) || $body === []) {
            $decodedBody = json_decode((string) $request->getBody(), true);
            $body = is_array($decodedBody) ? $decodedBody : [];
        }

        // Keep the server-side contract aligned with the admin prompt. Avoid
        // PHP's surprising casts ((int) ['anything'] === 1) and cap the batch so
        // one request cannot build an unbounded multi-row INSERT.
        $rawCopies = $body['copies'] ?? null;
        $copiesToAdd = is_int($rawCopies)
            ? $rawCopies
            : (is_string($rawCopies) && preg_match('/^[1-9]\d*$/D', $rawCopies) === 1 ? (int) $rawCopies : 0);

        if ($copiesToAdd < 1 || $copiesToAdd > 100) {
            $response->getBody()->write(json_encode([
                'error' => true,
                'message' => __('Numero di copie non valido.')
            ], JSON_UNESCAPED_UNICODE));
            return $response->withStatus(400)->withHeader('Content-Type', 'application/json');
        }

        // Get current book data
        $stmt = $db->prepare('SELECT copie_totali, numero_inventario FROM libri WHERE id = ? AND deleted_at IS NULL');
        $stmt->bind_param('i', $bookId);
        $stmt->execute();
        $result = $stmt->get_result();
        $book = $result->fetch_assoc();
        $stmt->close();

        if (!$book) {
            $response->getBody()->write(json_encode([
                'error' => true,
                'message' => __('Libro non trovato.')
            ], JSON_UNESCAPED_UNICODE));
            return $response->withStatus(404)->withHeader('Content-Type', 'application/json');
        }

        // Create the copies atomically and let DataIntegrity derive the counters,
        // mirroring CopyController::createCopy(). The allocator produces
        // collision-free "{base}-C{N}" codes: the previous "-C{copie_totali+i}"
        // scheme collided with an existing code as soon as a copy was out of
        // circulation (copie_totali excludes those), raising a 1062 that left the
        // manually-inflated copie_totali and a partial copy set behind. No manual
        // UPDATE, one transaction, rolled back on any failure.
        $copyRepo = new \App\Models\CopyRepository($db);
        $baseInventario = \App\Models\CopyRepository::inventoryBase($bookId, $book['numero_inventario'] ?? null);

        $reassignmentService = null;
        $reservationManager = null;
        $transactionStarted = false;
        try {
            if (!$db->begin_transaction()) {
                throw new \RuntimeException('Unable to begin the increase-copies transaction.');
            }
            $transactionStarted = true;

            // Canonical lock order: book row first, then copies.
            $lock = $db->prepare('SELECT id FROM libri WHERE id = ? AND deleted_at IS NULL FOR UPDATE');
            $lock->bind_param('i', $bookId);
            $lock->execute();
            $stillExists = (bool) $lock->get_result()->fetch_assoc();
            $lock->close();
            if (!$stillExists) {
                throw new \RuntimeException('Book not found.');
            }

            $createdCopyIds = $copyRepo->createManyForBookWithIds($bookId, $baseInventario, $copiesToAdd, 'disponibile', __('Copia %d di %d'));
            if (count($createdCopyIds) !== $copiesToAdd) {
                throw new \RuntimeException('Unable to create the requested physical copies.');
            }

            // First repair copy-less/blocked HOLDING assignments, exactly like
            // CopyController::createCopy(). Only the capacity left after those
            // repairs may promote wait-list rows from prenotazioni.
            $reassignmentService = new \App\Services\ReservationReassignmentService($db);
            $reassignmentService->setExternalTransaction(true);
            foreach ($createdCopyIds as $createdCopyId) {
                $reassignmentService->reassignOnNewCopy($bookId, $createdCopyId);
            }

            $reservationManager = new \App\Controllers\ReservationManager($db);
            $reservationManager->setExternalTransaction(true);
            for ($guard = 0; $guard < 1000 && $reservationManager->processBookAvailability($bookId); $guard++) {
                // promote the next eligible reservation into a pending loan
            }

            $integrity = new \App\Support\DataIntegrity($db);
            if (!$integrity->recalculateBookAvailability($bookId, true)) {
                throw new \RuntimeException('Unable to recalculate book availability.');
            }

            if (!$db->commit()) {
                throw new \RuntimeException('Unable to commit the increase-copies transaction.');
            }
            $transactionStarted = false;
        } catch (\Throwable $e) {
            if ($transactionStarted) {
                try {
                    $db->rollback();
                } catch (\Throwable $rollbackError) {
                    // best-effort — preserve the original failure
                }
            }
            \App\Support\SecureLogger::error('[increase-copies] failed to add copies', [
                'book' => $bookId,
                'error' => $e->getMessage(),
            ]);
            $response->getBody()->write(json_encode([
                'error' => true,
                'message' => __('Impossibile aggiungere le copie.')
            ], JSON_UNESCAPED_UNICODE));
            return $response->withStatus(500)->withHeader('Content-Type', 'application/json');
        }

        // Both services defer I/O while the transaction is open. Flush only
        // after the assignment/promotion has become durable; notification errors
        // must not turn a committed copy batch into an apparent API failure.
        try {
            $reassignmentService->flushDeferredNotifications();
            $reservationManager->flushDeferredNotifications();
        } catch (\Throwable $e) {
            \App\Support\SecureLogger::warning('[increase-copies] deferred notification failed', [
                'book' => $bookId,
                'error' => $e->getMessage(),
            ]);
        }

        // Read the derived counters (post-commit) for the response.
        $stmt = $db->prepare('SELECT copie_totali, copie_disponibili FROM libri WHERE id = ? AND deleted_at IS NULL');
        $stmt->bind_param('i', $bookId);
        $stmt->execute();
        $result = $stmt->get_result();
        $updatedBook = $result->fetch_assoc();
        $stmt->close();

        $response->getBody()->write(json_encode([
            'success' => true,
            'copie_totali' => (int) ($updatedBook['copie_totali'] ?? 0),
            'copie_disponibili' => (int) ($updatedBook['copie_disponibili'] ?? 0),
            'added' => $copiesToAdd
        ], JSON_UNESCAPED_UNICODE));

        return $response->withHeader('Content-Type', 'application/json');
    })->add(new CsrfMiddleware())->add(new AuthMiddleware(['admin']));

    // Frontend routes (public)
    $app->get('/home.php', function ($request, $response) use ($app) {
        $container = $app->getContainer();
        $controller = new \App\Controllers\FrontendController($container);
        $db = $container->get('db');
        return $controller->home($request, $response, $db, $container);
    });

    // Legacy redirect for backward compatibility (all language variants)
    foreach ($supportedLocales as $locale) {
        $registerRouteIfUnique('GET', RouteTranslator::getRouteForLocale('catalog_legacy', $locale), function ($request, $response) {
            return $response->withHeader('Location', RouteTranslator::route('catalog'))->withStatus(301);
        });
    }

    // Catalog page (all language variants)
    foreach ($supportedLocales as $locale) {
        $registerRouteIfUnique('GET', RouteTranslator::getRouteForLocale('catalog', $locale), function ($request, $response) use ($app) {
            $container = $app->getContainer();
            $controller = new \App\Controllers\FrontendController($container);
            $db = $container->get('db');
            return $controller->catalog($request, $response, $db);
        });
    }

    // Legacy book detail redirect (all language variants)
    foreach ($supportedLocales as $locale) {
        $registerRouteIfUnique('GET', RouteTranslator::getRouteForLocale('book_legacy', $locale), function ($request, $response) use ($app) {
            $container = $app->getContainer();
            $controller = new \App\Controllers\FrontendController($container);
            $db = $container->get('db');
            return $controller->bookDetail($request, $response, $db);
        });
    }

    // Old /libro/{id}/{slug} variants remain available and redirect inside the controller
    foreach ($supportedLocales as $locale) {
        $bookRoute = RouteTranslator::getRouteForLocale('book', $locale);

        // Route without slug
        $registerRouteIfUnique('GET', $bookRoute . '/{id:\d+}', function ($request, $response, $args) use ($app) {
            $container = $app->getContainer();
            $controller = new \App\Controllers\FrontendController($container);
            $db = $container->get('db');
            return $controller->bookDetailSEO($request, $response, $db, (int) $args['id'], '');
        });

        // Route with slug
        $registerRouteIfUnique('GET', $bookRoute . '/{id:\d+}/{slug}', function ($request, $response, $args) use ($app) {
            $container = $app->getContainer();
            $controller = new \App\Controllers\FrontendController($container);
            $db = $container->get('db');
            return $controller->bookDetailSEO($request, $response, $db, (int) $args['id'], $args['slug']);
        });
    }

    // RIS citation of a book (#412). A technical endpoint, not a localized page
    // ("/libro/{id}/citation.ris" would be taken as a slug by the route above).
    $registerRouteIfUnique('GET', '/books/{id:\d+}/citation.ris', function ($request, $response, $args) use ($app) {
        $container = $app->getContainer();
        $controller = new \App\Controllers\FrontendController($container);
        $db = $container->get('db');
        return $controller->bookCitationRis($request, $response, $db, (int) $args['id']);
    });

    // Canonical SEO route: /{author-slug}/{book-slug}/{id}
    $registerRouteIfUnique('GET', '/{authorSlug}/{bookSlug}/{id:\d+}', function ($request, $response, $args) use ($app) {
        $container = $app->getContainer();
        $controller = new \App\Controllers\FrontendController($container);
        $db = $container->get('db');
        return $controller->bookDetailSEO($request, $response, $db, (int) $args['id'], $args['bookSlug']);
    });

    // API endpoints for book reservations (all language variants)
    foreach ($supportedLocales as $locale) {
        $registerRouteIfUnique('GET', RouteTranslator::getRouteForLocale('api_book', $locale) . '/{id:\d+}/availability', function ($request, $response, $args) use ($app) {
            $db = $app->getContainer()->get('db');
            $bookId = (int)$args['id'];
            $controller = new \App\Controllers\ReservationsController($db);
            // Public endpoint (the book-page picker) — when a session exists,
            // exclude the user's own reservations like the write gate does.
            // F012: the admin loan form fetches this same route to create a loan
            // FOR a borrower who is not the session operator. An admin/staff can
            // pass ?for_user=<id> to exclude THAT borrower instead of the
            // operator; everyone else stays on the session id (self-service).
            $sessionUserId = isset($_SESSION['user']['id']) ? (int) $_SESSION['user']['id'] : null;
            $forUser = $request->getQueryParams()['for_user'] ?? null;
            $excludeUserId = $sessionUserId;
            if ($forUser !== null && is_numeric($forUser) && \App\Support\Permissions::can('loans.manage')) {
                $excludeUserId = (int) $forUser;
            }
            $availability = $controller->getBookAvailabilityData($bookId, \App\Support\DateHelper::today(), 180, $excludeUserId);
            if ($availability === null) {
                $response->getBody()->write(json_encode(['success' => false, 'message' => __('Libro non trovato')]));
                return $response->withStatus(404)->withHeader('Content-Type', 'application/json');
            }
            $data = [
                'success' => true,
                'availability' => [
                    'unavailable_dates' => $availability['unavailable_dates'] ?? [],
                    'earliest_available' => $availability['earliest_available'] ?? null,
                    'days' => $availability['days'] ?? [],
                    // F040: true when the excluded user already holds an active
                    // reservation on this book — the picker would otherwise show
                    // an all-green calendar that the date-less duplicate guard in
                    // createReservation rejects for every date.
                    'has_active_reservation' => $availability['has_active_reservation'] ?? false
                ]
            ];
            $response->getBody()->write(json_encode($data, JSON_UNESCAPED_UNICODE));
            return $response->withHeader('Content-Type', 'application/json');
        });

        $registerRouteIfUnique('POST', RouteTranslator::getRouteForLocale('api_book', $locale) . '/{id:\d+}/reservation', function ($request, $response, $args) use ($app) {
            $db = $app->getContainer()->get('db');
            $controller = new \App\Controllers\ReservationsController($db);
            return $controller->createReservation($request, $response, $args);
        }, [new AuthMiddleware(['admin', 'staff', 'standard', 'premium']), new CsrfMiddleware()]);
    }

    // API endpoint for AJAX catalog filtering (all language variants)
    foreach ($supportedLocales as $locale) {
        $registerRouteIfUnique('GET', RouteTranslator::getRouteForLocale('api_catalog', $locale), function ($request, $response) use ($app) {
            $container = $app->getContainer();
            $controller = new \App\Controllers\FrontendController($container);
            $db = $container->get('db');
            return $controller->catalogAPI($request, $response, $db);
        });
    }

    // API endpoint for home page sections (all language variants)
    foreach ($supportedLocales as $locale) {
        $registerRouteIfUnique('GET', RouteTranslator::getRouteForLocale('api_home', $locale) . '/{section}', function ($request, $response, $args) use ($app) {
            $container = $app->getContainer();
            $controller = new \App\Controllers\FrontendController($container);
            $db = $container->get('db');
            return $controller->homeAPI($request, $response, $db, $args['section']);
        });
    }

    // Author archive page by ID (all language variants)
    foreach ($supportedLocales as $locale) {
        $registerRouteIfUnique('GET', RouteTranslator::getRouteForLocale('author', $locale) . '/{id:\d+}', function ($request, $response, $args) use ($app) {
            $container = $app->getContainer();
            $controller = new \App\Controllers\FrontendController($container);
            $db = $container->get('db');
            return $controller->authorArchiveById($request, $response, $db, (int) $args['id']);
        });
    }

    // Author archive page by name (all language variants)
    foreach ($supportedLocales as $locale) {
        $registerRouteIfUnique('GET', RouteTranslator::getRouteForLocale('author', $locale) . '/{name}', function ($request, $response, $args) use ($app) {
            $container = $app->getContainer();
            $controller = new \App\Controllers\FrontendController($container);
            $db = $container->get('db');
            return $controller->authorArchive($request, $response, $db, $args['name']);
        });
    }

    // Publisher archive page by ID (all language variants) — registered BEFORE the
    // by-name route so /editore/{id} (the URL the header search builds) matches the
    // numeric variant instead of the {name} route with name="5" (which 404'd).
    foreach ($supportedLocales as $locale) {
        $registerRouteIfUnique('GET', RouteTranslator::getRouteForLocale('publisher', $locale) . '/{id:\d+}', function ($request, $response, $args) use ($app) {
            $container = $app->getContainer();
            $controller = new \App\Controllers\FrontendController($container);
            $db = $container->get('db');
            return $controller->publisherArchiveById($request, $response, $db, (int) $args['id']);
        });
    }

    // Publisher archive page by name (all language variants)
    foreach ($supportedLocales as $locale) {
        $registerRouteIfUnique('GET', RouteTranslator::getRouteForLocale('publisher', $locale) . '/{name}', function ($request, $response, $args) use ($app) {
            $container = $app->getContainer();
            $controller = new \App\Controllers\FrontendController($container);
            $db = $container->get('db');
            return $controller->publisherArchive($request, $response, $db, $args['name']);
        });
    }

    // Genre archive page (all language variants)
    foreach ($supportedLocales as $locale) {
        $registerRouteIfUnique('GET', RouteTranslator::getRouteForLocale('genre', $locale) . '/{name}', function ($request, $response, $args) use ($app) {
            $container = $app->getContainer();
            $controller = new \App\Controllers\FrontendController($container);
            $db = $container->get('db');
            return $controller->genreArchive($request, $response, $db, $args['name']);
        });
    }

    // CMS pages (Chi Siamo, etc.) (multi-language variants)
    foreach ($supportedLocales as $locale) {
        $aboutRoute = RouteTranslator::getRouteForLocale('about', $locale);

        $registerRouteIfUnique('GET', $aboutRoute, function ($request, $response, $args) use ($app) {
            $db = $app->getContainer()->get('db');
            $controller = new \App\Controllers\CmsController();
            // Don't pass hardcoded slug - let controller use CmsHelper::getSlug('about') at runtime
            // This resolves to locale-appropriate slug (chi-siamo for IT, about-us for EN)
            return $controller->showPage($request, $response, $db, []);
        });
    }

    // Contact page (multi-language variants)
    foreach ($supportedLocales as $locale) {
        $contactRoute = RouteTranslator::getRouteForLocale('contact', $locale);

        $registerRouteIfUnique('GET', $contactRoute, function ($request, $response) use ($app) {
            $container = $app->getContainer();
            $controller = new \App\Controllers\ContactController();
            return $controller->showPage($request, $response, $container);
        });

        $contactSubmitRoute = RouteTranslator::getRouteForLocale('contact_submit', $locale);
        $registerRouteIfUnique('POST', $contactSubmitRoute, function ($request, $response) use ($app) {
            $db = $app->getContainer()->get('db');
            $controller = new \App\Controllers\ContactController();
            return $controller->submitForm($request, $response, $db);
        }, [new CsrfMiddleware()]);

        // Handle hybrid URLs for contact submit (Italian base + English action and vice versa)
        // This occurs when users switch languages mid-session: their browser may have
        // cached the old form action URL in one language while the page base URL changed.
        // Example: Italian install shows /contatti but form might POST to /contatti/submit (hybrid)
        // instead of the expected /contatti/invia (fully Italian).
        if ($locale === 'it_IT') {
            $registerRouteIfUnique('POST', '/contatti/submit', function ($request, $response) use ($app) {
                $db = $app->getContainer()->get('db');
                $controller = new \App\Controllers\ContactController();
                return $controller->submitForm($request, $response, $db);
            }, [new CsrfMiddleware()]);
        } elseif ($locale === 'en_US') {
            $registerRouteIfUnique('POST', '/contact/invia', function ($request, $response) use ($app) {
                $db = $app->getContainer()->get('db');
                $controller = new \App\Controllers\ContactController();
                return $controller->submitForm($request, $response, $db);
            }, [new CsrfMiddleware()]);
        }
    }

    // Privacy Policy page (multi-language variants)
    foreach ($supportedLocales as $locale) {
        $privacyRoute = RouteTranslator::getRouteForLocale('privacy', $locale);

        $registerRouteIfUnique('GET', $privacyRoute, function ($request, $response) use ($app) {
            $container = $app->getContainer();
            $controller = new \App\Controllers\PrivacyController();
            return $controller->showPage($request, $response, $container);
        });
    }

    // Cookie Policy page (multi-language variants)
    foreach ($supportedLocales as $locale) {
        $cookiesRoute = RouteTranslator::getRouteForLocale('cookies', $locale);

        $registerRouteIfUnique('GET', $cookiesRoute, function ($request, $response) use ($app) {
            $container = $app->getContainer();
            $controller = new \App\Controllers\CookiesController();
            return $controller->showPage($request, $response, $container);
        });
    }

    // Cover proxy endpoint for previews (bypasses CORS)
    $app->get('/proxy/cover', function ($request, $response) {
        $url = $request->getQueryParams()['url'] ?? '';
        if (!$url) {
            return $response->withStatus(400);
        }

        // Validate URL format
        if (!filter_var($url, FILTER_VALIDATE_URL)) {
            return $response->withStatus(400);
        }

        // Parse URL components
        $parts = parse_url($url);
        if (!$parts || !isset($parts['scheme'], $parts['host'])) {
            return $response->withStatus(400);
        }

        // Enforce HTTPS only
        if (strtolower($parts['scheme']) !== 'https') {
            return $response->withStatus(403);
        }

        // Domain whitelist validation
        $allowedDomains = [
            'img.libreriauniversitaria.it',
            'img2.libreriauniversitaria.it',
            'img3.libreriauniversitaria.it',
            'covers.openlibrary.org',
            'images.amazon.com',
            'images-na.ssl-images-amazon.com',
            'www.lafeltrinelli.it',
            'books.google.com',
            'books.googleusercontent.com'
        ];

        $host = strtolower($parts['host']);
        if (!in_array($host, $allowedDomains, true)) {
            return $response->withStatus(403);
        }

        // DNS resolution check - ensure domain resolves to public IPs only
        $ips = gethostbynamel($host) ?: [];
        $aaaaRecords = @dns_get_record($host, DNS_AAAA) ?: [];

        if (!$ips && !$aaaaRecords) {
            return $response->withStatus(403);
        }

        // Validate all resolved IPs are public
        foreach ($ips as $ip) {
            if (filter_var($ip, FILTER_VALIDATE_IP, FILTER_FLAG_NO_PRIV_RANGE | FILTER_FLAG_NO_RES_RANGE) === false) {
                return $response->withStatus(403);
            }
        }

        foreach ($aaaaRecords as $record) {
            $ipv6 = $record['ipv6'] ?? null;
            if ($ipv6 && filter_var($ipv6, FILTER_VALIDATE_IP, FILTER_FLAG_NO_PRIV_RANGE | FILTER_FLAG_NO_RES_RANGE) === false) {
                return $response->withStatus(403);
            }
        }

        // Use cURL with secure settings (no automatic redirect following)
        // Use standard browser User-Agent for Google to avoid blocking
        $userAgent = (strpos($host, 'google') !== false)
            ? 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36'
            : 'BibliotecaBot/1.0';

        // Prepare headers for Google Books (they may require browser-like headers)
        $headers = [];
        if (strpos($host, 'google') !== false) {
            $headers = [
                'Accept: image/avif,image/webp,image/apng,image/svg+xml,image/*,*/*;q=0.8',
                'Accept-Language: it-IT,it;q=0.9,en-US;q=0.8,en;q=0.7',
                'Referer: https://books.google.com/',
                'Sec-Fetch-Dest: image',
                'Sec-Fetch-Mode: no-cors',
                'Sec-Fetch-Site: same-origin'
            ];
        }

        // Anti-DNS-rebinding: the DNS check above and curl's own resolution are
        // two separate lookups — pin curl to the exact IPs already validated as
        // public so it can't be steered to an internal address on the second
        // lookup (same fix as /api/plugins/proxy-image; a whitelisted host that
        // is compromised could otherwise resolve internally). Entries in $ips /
        // $aaaaRecords already passed the NO_PRIV_RANGE|NO_RES_RANGE filter.
        // Scheme is guaranteed 'https' here (enforced with a 403 above).
        $coverPort = isset($parts['port']) ? (int) $parts['port'] : 443;
        $coverIps = $ips;
        foreach ($aaaaRecords as $record) {
            if (!empty($record['ipv6'])) {
                $coverIps[] = $record['ipv6'];
            }
        }
        if ($coverIps === []) {
            return $response->withStatus(403);
        }

        $ch = curl_init($url);
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_FOLLOWLOCATION => false,
            CURLOPT_RESOLVE => [$host . ':' . $coverPort . ':' . implode(',', $coverIps)],
            CURLOPT_TIMEOUT => 10,
            CURLOPT_CONNECTTIMEOUT => 5,
            CURLOPT_SSL_VERIFYPEER => true,
            CURLOPT_SSL_VERIFYHOST => 2,
            CURLOPT_USERAGENT => $userAgent,
            CURLOPT_HTTPHEADER => $headers,
            CURLOPT_MAXREDIRS => 0
        ]);

        $img = curl_exec($ch);
        $httpCode = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
        /* curl_close(): no-op since PHP 8.0, deprecated 8.5 */

        if ($img === false || $httpCode !== 200) {
            return $response->withStatus(404);
        }

        // Validate it's actually an image
        $finfo = new finfo(FILEINFO_MIME_TYPE);
        $mimeType = $finfo->buffer($img);

        // Only allow image MIME types
        if (!str_starts_with($mimeType, 'image/')) {
            return $response->withStatus(403);
        }

        $response->getBody()->write($img);
        return $response->withHeader('Content-Type', $mimeType)
            ->withHeader('Cache-Control', 'public, max-age=3600');
    });

    // Plugin image proxy endpoint - More permissive for plugin extensibility
    // Allows any HTTPS domain but protects against SSRF attacks
    $app->get('/api/plugins/proxy-image', function ($request, $response) {
        $url = $request->getQueryParams()['url'] ?? '';
        if (!$url) {
            return $response->withStatus(400);
        }

        // Validate URL format
        if (!filter_var($url, FILTER_VALIDATE_URL)) {
            return $response->withStatus(400);
        }

        // Parse URL components
        $parts = parse_url($url);
        if (!$parts || !isset($parts['scheme'], $parts['host'])) {
            return $response->withStatus(400);
        }

        // Auto-upgrade HTTP to HTTPS for known safe book cover domains
        // These domains support HTTPS and are commonly used for book covers
        $httpUpgradeDomains = [
            'covers.librarything.com',
            'covers.openlibrary.org',
            'images.amazon.com',
            'books.google.com',
        ];

        $host = strtolower($parts['host']);
        if (strtolower($parts['scheme']) === 'http' && in_array($host, $httpUpgradeDomains, true)) {
            $url = preg_replace('/^http:/i', 'https:', $url);
            $parts['scheme'] = 'https';
        }

        // Enforce HTTPS only (no HTTP, file://, ftp://, etc.)
        if (strtolower($parts['scheme']) !== 'https') {
            return $response->withStatus(403);
        }

        // Block localhost and loopback addresses
        $blockedHosts = ['localhost', '127.0.0.1', '::1', '0.0.0.0'];
        if (in_array($host, $blockedHosts, true)) {
            return $response->withStatus(403);
        }

        // Block common private network patterns
        $privatePatterns = [
            '/^192\.168\./',
            '/^10\./',
            '/^172\.(1[6-9]|2[0-9]|3[0-1])\./',
            '/^169\.254\./',  // Link-local
            '/^fe80:/i',      // IPv6 link-local
            '/^fc00:/i',      // IPv6 private
            '/^fd00:/i',      // IPv6 private
        ];

        foreach ($privatePatterns as $pattern) {
            if (preg_match($pattern, $host)) {
                return $response->withStatus(403);
            }
        }

        // DNS resolution check - ensure domain resolves to public IPs only
        $ips = @gethostbynamel($host) ?: [];
        $aaaaRecords = @dns_get_record($host, DNS_AAAA) ?: [];

        if (!$ips && !$aaaaRecords) {
            return $response->withStatus(403);
        }

        // Validate all resolved IPv4 addresses are public
        foreach ($ips as $ip) {
            if (filter_var($ip, FILTER_VALIDATE_IP, FILTER_FLAG_NO_PRIV_RANGE | FILTER_FLAG_NO_RES_RANGE) === false) {
                return $response->withStatus(403);
            }
        }

        // Validate all resolved IPv6 addresses are public
        foreach ($aaaaRecords as $record) {
            $ipv6 = $record['ipv6'] ?? null;
            if ($ipv6 && filter_var($ipv6, FILTER_VALIDATE_IP, FILTER_FLAG_NO_PRIV_RANGE | FILTER_FLAG_NO_RES_RANGE) === false) {
                return $response->withStatus(403);
            }
        }

        // Security scan F5 (CWE-918): the DNS check above (gethostbynamel /
        // dns_get_record) and curl's own resolution are two SEPARATE lookups —
        // a rebinding attacker can answer "public IP" to the first and
        // "127.0.0.1" to curl's, so validating the hostname is not enough. Pin
        // curl to the exact IPs we just validated as public via CURLOPT_RESOLVE
        // so it never re-resolves. All entries in $ips / $aaaaRecords already
        // passed the NO_PRIV_RANGE|NO_RES_RANGE filter above.
        $port = isset($parts['port']) ? (int) $parts['port'] : 443;
        $validatedIps = $ips;
        foreach ($aaaaRecords as $record) {
            if (!empty($record['ipv6'])) {
                $validatedIps[] = $record['ipv6'];
            }
        }
        if ($validatedIps === []) {
            return $response->withStatus(403);
        }
        $resolveEntry = $host . ':' . $port . ':' . implode(',', $validatedIps);

        // Fetch image with secure settings
        $ch = curl_init($url);
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            // F5: never follow redirects — a 3xx to an internal host would be
            // fetched by curl BEFORE any post-hoc URL re-validation could run,
            // and the response body would already have been read. Reject 3xx.
            CURLOPT_FOLLOWLOCATION => false,
            CURLOPT_RESOLVE => [$resolveEntry],
            CURLOPT_PROTOCOLS => CURLPROTO_HTTPS,
            CURLOPT_TIMEOUT => 10,
            CURLOPT_CONNECTTIMEOUT => 5,
            CURLOPT_SSL_VERIFYPEER => true,
            CURLOPT_SSL_VERIFYHOST => 2,
            CURLOPT_USERAGENT => 'Mozilla/5.0 (compatible; BibliotecaBot/1.0) Safari/537.36',
            CURLOPT_HTTPHEADER => [
                'Accept: image/avif,image/webp,image/apng,image/svg+xml,image/*,*/*;q=0.8'
            ],
        ]);

        $img = curl_exec($ch);
        $httpCode = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
        /* curl_close(): no-op since PHP 8.0, deprecated 8.5 */

        // A 3xx means the origin tried to redirect us (potentially to an
        // internal target); with FOLLOWLOCATION off we simply refuse it.
        if ($img === false || $httpCode !== 200) {
            return $response->withStatus(404);
        }

        // Validate it's actually an image
        $finfo = new finfo(FILEINFO_MIME_TYPE);
        $mimeType = $finfo->buffer($img);

        // Only allow image MIME types
        if (!str_starts_with($mimeType, 'image/')) {
            return $response->withStatus(403);
        }

        $response->getBody()->write($img);
        return $response->withHeader('Content-Type', $mimeType)
            ->withHeader('Cache-Control', 'public, max-age=3600')
            ->withHeader('X-Proxy-Type', 'plugin');
    });

    // Serve uploaded files from storage directory
    $app->get('/uploads/storage/{filepath:.*}', function ($request, $response, $args) {
        $rawPath = (string) ($args['filepath'] ?? '');
        if ($rawPath === '') {
            return $response->withStatus(404);
        }

        // Normalize and validate the requested path
        $sanitizedPath = str_replace(["\0", "\r", "\n"], '', $rawPath);
        $sanitizedPath = str_replace('\\', '/', $sanitizedPath);
        $sanitizedPath = ltrim($sanitizedPath, '/');

        if ($sanitizedPath === '' || preg_match('#(^|/)\.\.(?:/|$)#', $sanitizedPath)) {
            return $response->withStatus(403);
        }

        $basePath = realpath(__DIR__ . '/../../storage/uploads');
        if ($basePath === false) {
            return $response->withStatus(500);
        }

        $fullPath = $basePath . '/' . $sanitizedPath;

        // Ensure file exists and resolve real path for final security check
        if (!file_exists($fullPath) || !is_file($fullPath)) {
            return $response->withStatus(404);
        }

        $realFullPath = realpath($fullPath);
        if ($realFullPath === false || !str_starts_with($realFullPath, $basePath)) {
            return $response->withStatus(403);
        }

        // Security: Check file extension
        $allowedExtensions = ['jpg', 'jpeg', 'png', 'gif'];
        $extension = strtolower(pathinfo($realFullPath, PATHINFO_EXTENSION));
        if (!in_array($extension, $allowedExtensions, true)) {
            return $response->withStatus(403);
        }

        // Serve file
        $finfo = new finfo(FILEINFO_MIME_TYPE);
        $mimeType = $finfo->file($realFullPath);
        $fileContent = file_get_contents($realFullPath);

        if ($fileContent === false) {
            return $response->withStatus(500);
        }

        $response->getBody()->write($fileContent);
        return $response->withHeader('Content-Type', $mimeType)
            ->withHeader('Cache-Control', 'public, max-age=3600');
    });

    // Serve ICS calendar file for external calendar sync (dynamic generation)
    // Supports both legacy path and new clean URL
    $calendarHandler = function ($request, $response) use ($app) {
        try {
            $db = $app->getContainer()->get('db');
            $generator = new \App\Support\IcsGenerator($db);
            // The book title goes into the VEVENT summary and is retained by
            // the subscriber's calendar client, so wanted titles must not be
            // published here. Borrower names and emails are only written for
            // an operator link (per-operator HMAC token from the dashboard,
            // re-checked against an active admin/staff account): the bare URL
            // is guessable and must not tell anyone who borrowed what.
            $query = $request->getQueryParams();
            $token = $query['token'] ?? '';
            $operator = $query['op'] ?? '';
            $operatorFeed = is_string($token) && is_string($operator)
                && (new \App\Support\LoanCalendarLinks($db))->libraryFeedOperator($operator, $token) !== null;
            $content = $generator->generate(true, $operatorFeed);

            $response->getBody()->write($content);
            return $response
                ->withHeader('Content-Type', 'text/calendar; charset=utf-8')
                ->withHeader('Content-Disposition', 'inline; filename="library-calendar.ics"')
                ->withHeader('X-Robots-Tag', 'noindex, nofollow')
                // 5 min; the personal variant must never sit in a shared cache.
                ->withHeader('Cache-Control', $operatorFeed ? 'private, max-age=300' : 'public, max-age=300');
        } catch (\Throwable $e) {
            \App\Support\SecureLogger::error('ICS generation error', ['error' => $e->getMessage()]);
            $response->getBody()->write(__('Errore generazione calendario'));
            return $response->withStatus(500);
        }
    };

    // New clean URL (preferred)
    $app->get('/calendar/events.ics', $calendarHandler);

    // Legacy URL for backward compatibility
    $app->get('/storage/calendar/library-calendar.ics', $calendarHandler);

    // Per-loan ICS download linked from the loan confirmation emails.
    // Opened by mail/calendar clients without a session, so access is gated by
    // the HMAC token generated by LoanCalendarLinks (404 on mismatch: don't
    // reveal whether a loan id exists).
    $app->get('/calendar/loan/{id:[0-9]+}.ics', function ($request, $response, array $args) use ($app) {
        try {
            $db = $app->getContainer()->get('db');
            $loanId = (int) $args['id'];
            $token = (string) ($request->getQueryParams()['token'] ?? '');

            $links = new \App\Support\LoanCalendarLinks($db);
            if (!$links->isValidToken($loanId, $token)) {
                return $response->withStatus(404);
            }

            $content = (new \App\Support\IcsGenerator($db))->generateForLoan($loanId);
            if ($content === null) {
                return $response->withStatus(404);
            }

            $response->getBody()->write($content);
            return $response
                ->withHeader('Content-Type', 'text/calendar; charset=utf-8')
                ->withHeader('Content-Disposition', 'attachment; filename="prestito-' . $loanId . '.ics"')
                ->withHeader('Cache-Control', 'private, max-age=300');
        } catch (\Throwable $e) {
            \App\Support\SecureLogger::error('Loan ICS generation error', ['error' => $e->getMessage()]);
            $response->getBody()->write(__('Errore generazione calendario'));
            return $response->withStatus(500);
        }
    });

    // Public API endpoint for book search (protected by API key)
    $app->get('/api/public/books/search', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\PublicApiController();
        return $controller->searchBooks($request, $response, $db);
    })->add(new \App\Middleware\ApiKeyMiddleware($app->getContainer()->get('db')));

    // ==========================================
    // Plugin Management Routes (Admin Only)
    // ==========================================

    // Plugin list page
    $app->get('/admin/plugins', function ($request, $response) use ($app) {
        $pluginManager = $app->getContainer()->get('pluginManager');
        $controller = new \App\Controllers\PluginController($pluginManager);
        return $controller->index($request, $response);
    })->add(new AdminAuthMiddleware());

    // Plugin upload/install
    $app->post('/admin/plugins/upload', function ($request, $response) use ($app) {
        $pluginManager = $app->getContainer()->get('pluginManager');
        $controller = new \App\Controllers\PluginController($pluginManager);
        return $controller->upload($request, $response);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Plugin activate
    $app->post('/admin/plugins/{id}/activate', function ($request, $response, $args) use ($app) {
        $pluginManager = $app->getContainer()->get('pluginManager');
        $controller = new \App\Controllers\PluginController($pluginManager);
        return $controller->activate($request, $response, $args);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Plugin deactivate
    $app->post('/admin/plugins/{id}/deactivate', function ($request, $response, $args) use ($app) {
        $pluginManager = $app->getContainer()->get('pluginManager');
        $controller = new \App\Controllers\PluginController($pluginManager);
        return $controller->deactivate($request, $response, $args);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Plugin uninstall
    $app->post('/admin/plugins/{id}/uninstall', function ($request, $response, $args) use ($app) {
        $pluginManager = $app->getContainer()->get('pluginManager');
        $controller = new \App\Controllers\PluginController($pluginManager);
        return $controller->uninstall($request, $response, $args);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->get('/admin/plugins/{id}/settings', function ($request, $response, $args) use ($app) {
        $pluginManager = $app->getContainer()->get('pluginManager');
        $controller = new \App\Controllers\PluginController($pluginManager);
        return $controller->settingsPage($request, $response, $args);
    })->add(new AdminAuthMiddleware());

    // Plugin settings update
    $app->post('/admin/plugins/{id}/settings', function ($request, $response, $args) use ($app) {
        $pluginManager = $app->getContainer()->get('pluginManager');
        $controller = new \App\Controllers\PluginController($pluginManager);
        return $controller->updateSettings($request, $response, $args);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // ==========================================
    // Theme Management Routes (Admin Only)
    // ==========================================

    $app->get('/admin/themes', function ($request, $response) use ($app) {
        $themeManager = $app->getContainer()->get('themeManager');
        $themeColorizer = $app->getContainer()->get('themeColorizer');
        $controller = new \App\Controllers\ThemeController($themeManager, $themeColorizer);
        return $controller->index($request, $response);
    })->add(new AdminAuthMiddleware());

    $app->get('/admin/themes/{id}/customize', function ($request, $response, $args) use ($app) {
        $themeManager = $app->getContainer()->get('themeManager');
        $themeColorizer = $app->getContainer()->get('themeColorizer');
        $controller = new \App\Controllers\ThemeController($themeManager, $themeColorizer);
        return $controller->customize($request, $response, $args);
    })->add(new AdminAuthMiddleware());

    $app->post('/admin/themes/{id}/save', function ($request, $response, $args) use ($app) {
        $themeManager = $app->getContainer()->get('themeManager');
        $themeColorizer = $app->getContainer()->get('themeColorizer');
        $controller = new \App\Controllers\ThemeController($themeManager, $themeColorizer);
        return $controller->save($request, $response, $args);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/themes/{id}/layout', function ($request, $response, $args) use ($app) {
        $themeManager = $app->getContainer()->get('themeManager');
        $themeColorizer = $app->getContainer()->get('themeColorizer');
        $controller = new \App\Controllers\ThemeController($themeManager, $themeColorizer);
        return $controller->saveLayout($request, $response, $args);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/themes/{id}/activate', function ($request, $response, $args) use ($app) {
        $themeManager = $app->getContainer()->get('themeManager');
        $themeColorizer = $app->getContainer()->get('themeColorizer');
        $controller = new \App\Controllers\ThemeController($themeManager, $themeColorizer);
        return $controller->activate($request, $response, $args);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/themes/{id}/reset', function ($request, $response, $args) use ($app) {
        $themeManager = $app->getContainer()->get('themeManager');
        $themeColorizer = $app->getContainer()->get('themeColorizer');
        $controller = new \App\Controllers\ThemeController($themeManager, $themeColorizer);
        return $controller->reset($request, $response, $args);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->post('/admin/themes/check-contrast', function ($request, $response) use ($app) {
        $themeManager = $app->getContainer()->get('themeManager');
        $themeColorizer = $app->getContainer()->get('themeColorizer');
        $controller = new \App\Controllers\ThemeController($themeManager, $themeColorizer);
        return $controller->checkContrast($request, $response);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // ==========================================
    // Admin Updates routes
    // ==========================================
    $app->get('/admin/updates', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\UpdateController();
        return $controller->index($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware());

    $app->get('/admin/updates/check', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\UpdateController();
        return $controller->checkUpdates($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(15, 60))->add(new AdminAuthMiddleware());

    $app->get('/admin/updates/available', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\UpdateController();
        return $controller->checkAvailable($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware());

    $app->post('/admin/updates/perform', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\UpdateController();
        return $controller->performUpdate($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Full backups (DB + uploads) are heavy — cap to 5/min, tighter than the
    // nearby 30/60 convention (intentional, the operation is resource-intensive).
    $app->post('/admin/updates/backup', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\UpdateController();
        return $controller->createBackup($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(5, 60))->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->get('/admin/updates/history', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\UpdateController();
        return $controller->getHistory($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new AdminAuthMiddleware());

    $app->get('/admin/updates/backups', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\UpdateController();
        return $controller->getBackups($request, $response, $db);
    })->add(new AdminAuthMiddleware());

    $app->post('/admin/updates/backup/delete', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\UpdateController();
        return $controller->deleteBackup($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    $app->get('/admin/updates/backup/download', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\UpdateController();
        return $controller->downloadBackup($request, $response, $db);
    })->add(new AdminAuthMiddleware());

    $app->post('/admin/updates/backup/settings', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\UpdateController();
        return $controller->saveBackupSettings($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Restore a stored backup (DB + files). Destructive — the controller
    // additionally restricts this to admins (AdminAuthMiddleware allows staff).
    $app->post('/admin/updates/backup/restore', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\UpdateController();
        return $controller->restoreBackup($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Restore from an uploaded backup ZIP. Destructive — admin-only (controller).
    $app->post('/admin/updates/backup/restore-upload', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\UpdateController();
        return $controller->uploadRestore($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Emergency maintenance mode clear (for recovery after failed updates)
    $app->post('/admin/updates/maintenance/clear', function ($request, $response) {
        $controller = new \App\Controllers\UpdateController();
        return $controller->clearMaintenance($request, $response);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Where an update stands: polled by the page when a proxy dropped its
    // install request while the server carried on (#450)
    $app->get('/admin/updates/status', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\UpdateController();
        return $controller->status($request, $response, $db);
    })->add(new AdminAuthMiddleware());

    // View updater logs (for debugging)
    $app->get('/admin/updates/logs', function ($request, $response) {
        $controller = new \App\Controllers\UpdateController();
        return $controller->getLogs($request, $response);
    })->add(new AdminAuthMiddleware());

    // GitHub API token
    $app->post('/admin/updates/token', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\UpdateController();
        return $controller->saveToken($request, $response, $db);
    })->add(new \App\Middleware\RateLimitMiddleware(30, 60))->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Manual update - Upload package
    $app->post('/admin/updates/upload', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\UpdateController();
        return $controller->uploadUpdate($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Automatic update, first request: download and verify the release package
    $app->post('/admin/updates/download', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\UpdateController();
        return $controller->downloadUpdatePackage($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // Manual update - Install uploaded package
    $app->post('/admin/updates/install-manual', function ($request, $response) use ($app) {
        $db = $app->getContainer()->get('db');
        $controller = new \App\Controllers\UpdateController();
        return $controller->installManualUpdate($request, $response, $db);
    })->add(new CsrfMiddleware())->add(new AdminAuthMiddleware());

    // ==========================================
    // Legacy Italian admin-path redirects (301 permanent)
    //
    // Maps old Italian /admin/{segment}[/{rest}] paths to their new English
    // equivalents. These fire BEFORE auth (no middleware added) so bookmarked
    // or emailed links redirect cleanly without hitting a login wall first.
    //
    // Sub-segments (action words) in $rest are also translated so that e.g.
    // /admin/libri/modifica/5 → /admin/books/edit/5 in a single round-trip.
    // ==========================================

    /** @var array<string,string> $adminSegmentMap Italian primary segment → English */
    $adminSegmentMap = [
        'libri'        => 'books',
        'prestiti'     => 'loans',
        'utenti'       => 'users',
        'collane'      => 'series',
        'autori'       => 'authors',
        'generi'       => 'genres',
        'editori'      => 'publishers',
        'prenotazioni' => 'reservations',
        'collocazione' => 'placement',
        'recensioni'   => 'reviews',
        'statistiche'  => 'statistics',
    ];

    /** @var array<string,string> $actionSegmentMap Italian action words → English */
    $actionSegmentMap = [
        'crea-opera'    => 'create-opera',
        'crea'          => 'create',
        'modifica'      => 'edit',
        'elimina'       => 'delete',
        'dettagli'      => 'details',
        'dettaglio'     => 'detail',
        'restituito'    => 'returned',
        'rinnova'       => 'renew',
        'unisci'        => 'merge',
        'rinomina'      => 'rename',
        'rimuovi-libro' => 'remove-book',
        'ordine'        => 'order',
        'descrizione'   => 'description',
        'mensole'       => 'shelves',
        'scaffali'      => 'shelving-units',
        'copie'         => 'copies',
        'volumi'        => 'volumes',
    ];

    foreach ($adminSegmentMap as $itSegment => $enSegment) {
        $app->map(
            ['GET', 'POST'],
            '/admin/' . $itSegment . '[/{rest:.*}]',
            function ($request, $response, $args) use ($enSegment, $actionSegmentMap) {
                $rest = isset($args['rest']) && $args['rest'] !== ''
                    ? '/' . $args['rest']
                    : '';

                // Translate action sub-segments inside $rest.
                // Split on '/', translate each segment, then rejoin.
                if ($rest !== '') {
                    $parts = explode('/', ltrim($rest, '/'));
                    // Translate known action segments; rawurlencode every segment so a
                    // user-controlled {rest} capture can never be structurally ambiguous
                    // in the Location header (defense in depth — the '/admin/' prefix
                    // already prevents host break-out).
                    $parts = array_map(
                        fn(string $part) => rawurlencode($actionSegmentMap[$part] ?? $part),
                        $parts
                    );
                    $rest = '/' . implode('/', $parts);
                }

                $query = $request->getUri()->getQuery();
                $location = '/admin/' . $enSegment . $rest . ($query !== '' ? '?' . $query : '');

                // 308 (not 301): this redirect also covers legacy POST submits.
                // A 301 lets the browser rewrite POST→GET and drop the body/CSRF,
                // landing a form on the English endpoint with no payload (or 405).
                // 308 preserves the method and body, and behaves like 301 for GET.
                return $response->withHeader('Location', $location)->withStatus(308);
            }
        );
    }
    // ==========================================
    // End legacy Italian admin-path redirects
    // ==========================================

};