From 2626d2e88e8daa23f2829af7ebe5e9a4aab975dd Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Sat, 11 Apr 2026 22:40:25 +0200
Subject: [PATCH 01/10] feat: add ForbiddenException with 403 mapping in
 GlobalExceptionHandler

---
 .../Constants/ErrorMessages.cs                |  3 +++
 .../Exceptions/ForbiddenException.cs          | 15 +++++++++++++++
 .../Exceptions/GlobalExceptionHandler.cs      |  5 +++++
 .../GlobalExceptionHandlerTests.cs            | 19 +++++++++++++++++++
 4 files changed, 42 insertions(+)
 create mode 100644 framework/SimpleModule.Core/Exceptions/ForbiddenException.cs

diff --git a/framework/SimpleModule.Core/Constants/ErrorMessages.cs b/framework/SimpleModule.Core/Constants/ErrorMessages.cs
index d4cb5dc9..bbbee803 100644
--- a/framework/SimpleModule.Core/Constants/ErrorMessages.cs
+++ b/framework/SimpleModule.Core/Constants/ErrorMessages.cs
@@ -6,6 +6,7 @@ public static class ErrorMessages
     public const string ValidationErrorTitle = "Validation Error";
     public const string NotFoundTitle = "Not Found";
     public const string ConflictTitle = "Conflict";
+    public const string ForbiddenTitle = "Forbidden";
     public const string InternalServerErrorTitle = "Internal Server Error";
 
     // Default exception messages
@@ -13,4 +14,6 @@ public static class ErrorMessages
     public const string DefaultValidationMessage = "One or more validation errors occurred.";
     public const string DefaultNotFoundMessage = "The requested resource was not found.";
     public const string DefaultConflictMessage = "A conflict occurred.";
+    public const string DefaultForbiddenMessage =
+        "You do not have permission to access this resource.";
 }
diff --git a/framework/SimpleModule.Core/Exceptions/ForbiddenException.cs b/framework/SimpleModule.Core/Exceptions/ForbiddenException.cs
new file mode 100644
index 00000000..f8429045
--- /dev/null
+++ b/framework/SimpleModule.Core/Exceptions/ForbiddenException.cs
@@ -0,0 +1,15 @@
+using SimpleModule.Core.Constants;
+
+namespace SimpleModule.Core.Exceptions;
+
+public sealed class ForbiddenException : Exception
+{
+    public ForbiddenException()
+        : base(ErrorMessages.DefaultForbiddenMessage) { }
+
+    public ForbiddenException(string message)
+        : base(message) { }
+
+    public ForbiddenException(string message, Exception innerException)
+        : base(message, innerException) { }
+}
diff --git a/framework/SimpleModule.Core/Exceptions/GlobalExceptionHandler.cs b/framework/SimpleModule.Core/Exceptions/GlobalExceptionHandler.cs
index 10d2d060..e1ec1cef 100644
--- a/framework/SimpleModule.Core/Exceptions/GlobalExceptionHandler.cs
+++ b/framework/SimpleModule.Core/Exceptions/GlobalExceptionHandler.cs
@@ -29,6 +29,11 @@ CancellationToken cancellationToken
             ),
             NotFoundException => (StatusCodes.Status404NotFound, ErrorMessages.NotFoundTitle, null),
             ConflictException => (StatusCodes.Status409Conflict, ErrorMessages.ConflictTitle, null),
+            ForbiddenException => (
+                StatusCodes.Status403Forbidden,
+                ErrorMessages.ForbiddenTitle,
+                null
+            ),
             _ => (
                 StatusCodes.Status500InternalServerError,
                 ErrorMessages.InternalServerErrorTitle,
diff --git a/tests/SimpleModule.Core.Tests/GlobalExceptionHandlerTests.cs b/tests/SimpleModule.Core.Tests/GlobalExceptionHandlerTests.cs
index a5ee89e9..5a6f5dc3 100644
--- a/tests/SimpleModule.Core.Tests/GlobalExceptionHandlerTests.cs
+++ b/tests/SimpleModule.Core.Tests/GlobalExceptionHandlerTests.cs
@@ -128,6 +128,25 @@ public async Task NotFoundException_IncludesEntityInfoInDetail()
             .Be("User with ID abc-123 not found");
     }
 
+    [Fact]
+    public async Task ForbiddenException_Returns403()
+    {
+        var context = CreateHttpContext();
+        var exception = new ForbiddenException("Access denied to admin panel");
+
+        var handled = await _handler.TryHandleAsync(context, exception, CancellationToken.None);
+
+        handled.Should().BeTrue();
+        context.Response.StatusCode.Should().Be(403);
+
+        var doc = await ReadResponseBodyAsync(context);
+        doc.RootElement.GetProperty("title").GetString().Should().Be("Forbidden");
+        doc.RootElement.GetProperty("detail")
+            .GetString()
+            .Should()
+            .Be("Access denied to admin panel");
+    }
+
     [Fact]
     public async Task Handler_AlwaysReturnsTrue()
     {

From bae8ed608adda7eb2936a7173260baff505b6c9b Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Sat, 11 Apr 2026 22:43:09 +0200
Subject: [PATCH 02/10] feat: render Inertia error pages for browser requests
 in GlobalExceptionHandler

---
 .../Exceptions/GlobalExceptionHandler.cs      | 50 +++++++++++++-
 .../GlobalExceptionHandlerTests.cs            | 65 +++++++++++++++++++
 2 files changed, 113 insertions(+), 2 deletions(-)

diff --git a/framework/SimpleModule.Core/Exceptions/GlobalExceptionHandler.cs b/framework/SimpleModule.Core/Exceptions/GlobalExceptionHandler.cs
index e1ec1cef..5c887765 100644
--- a/framework/SimpleModule.Core/Exceptions/GlobalExceptionHandler.cs
+++ b/framework/SimpleModule.Core/Exceptions/GlobalExceptionHandler.cs
@@ -1,14 +1,21 @@
+using System.Text.Json;
 using Microsoft.AspNetCore.Diagnostics;
 using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.Extensions.Logging;
 using SimpleModule.Core.Constants;
+using SimpleModule.Core.Inertia;
 
 namespace SimpleModule.Core.Exceptions;
 
 public sealed class GlobalExceptionHandler(ILogger<GlobalExceptionHandler> logger)
     : IExceptionHandler
 {
+    private static readonly JsonSerializerOptions InertiaJsonOptions = new()
+    {
+        PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
+    };
+
     public async ValueTask<bool> TryHandleAsync(
         HttpContext httpContext,
         Exception exception,
@@ -28,12 +35,12 @@ CancellationToken cancellationToken
                 null
             ),
             NotFoundException => (StatusCodes.Status404NotFound, ErrorMessages.NotFoundTitle, null),
-            ConflictException => (StatusCodes.Status409Conflict, ErrorMessages.ConflictTitle, null),
             ForbiddenException => (
                 StatusCodes.Status403Forbidden,
                 ErrorMessages.ForbiddenTitle,
                 null
             ),
+            ConflictException => (StatusCodes.Status409Conflict, ErrorMessages.ConflictTitle, null),
             _ => (
                 StatusCodes.Status500InternalServerError,
                 ErrorMessages.InternalServerErrorTitle,
@@ -59,6 +66,15 @@ CancellationToken cancellationToken
                 ? ErrorMessages.UnexpectedError
                 : exception.Message;
 
+        httpContext.Response.StatusCode = statusCode;
+
+        // Inertia requests get an Inertia error page response
+        if (httpContext.Request.Headers.ContainsKey("X-Inertia"))
+        {
+            return await WriteInertiaErrorAsync(httpContext, statusCode, title, detail);
+        }
+
+        // API/non-Inertia requests get ProblemDetails JSON
         var problemDetails = new ProblemDetails
         {
             Status = statusCode,
@@ -71,8 +87,38 @@ CancellationToken cancellationToken
             problemDetails.Extensions["errors"] = errors;
         }
 
-        httpContext.Response.StatusCode = statusCode;
         await httpContext.Response.WriteAsJsonAsync(problemDetails, cancellationToken);
         return true;
     }
+
+    private static async ValueTask<bool> WriteInertiaErrorAsync(
+        HttpContext httpContext,
+        int statusCode,
+        string title,
+        string message
+    )
+    {
+        var component = $"Error/{statusCode}";
+        var props = new
+        {
+            status = statusCode,
+            title,
+            message,
+        };
+
+        var pageData = new
+        {
+            component,
+            props,
+            url = httpContext.Request.Path + httpContext.Request.QueryString,
+            version = InertiaMiddleware.Version,
+        };
+
+        httpContext.Response.Headers["X-Inertia"] = "true";
+        httpContext.Response.Headers["Vary"] = "X-Inertia";
+        httpContext.Response.ContentType = "application/json";
+        var json = JsonSerializer.Serialize(pageData, InertiaJsonOptions);
+        await httpContext.Response.WriteAsync(json);
+        return true;
+    }
 }
diff --git a/tests/SimpleModule.Core.Tests/GlobalExceptionHandlerTests.cs b/tests/SimpleModule.Core.Tests/GlobalExceptionHandlerTests.cs
index 5a6f5dc3..d247c249 100644
--- a/tests/SimpleModule.Core.Tests/GlobalExceptionHandlerTests.cs
+++ b/tests/SimpleModule.Core.Tests/GlobalExceptionHandlerTests.cs
@@ -167,4 +167,69 @@ public async Task Handler_AlwaysReturnsTrue()
         result1.Should().BeTrue();
         result2.Should().BeTrue();
     }
+
+    [Fact]
+    public async Task InertiaRequest_NotFoundException_ReturnsInertiaErrorPage()
+    {
+        var context = CreateHttpContext();
+        context.Request.Headers["X-Inertia"] = "true";
+        context.Request.Headers["X-Inertia-Version"] = "1";
+        var exception = new NotFoundException("Product", 42);
+
+        var handled = await _handler.TryHandleAsync(context, exception, CancellationToken.None);
+
+        handled.Should().BeTrue();
+        context.Response.StatusCode.Should().Be(404);
+        context.Response.Headers["X-Inertia"].ToString().Should().Be("true");
+        context.Response.ContentType.Should().Contain("application/json");
+
+        var doc = await ReadResponseBodyAsync(context);
+        doc.RootElement.GetProperty("component").GetString().Should().Be("Error/404");
+        doc.RootElement.GetProperty("props").GetProperty("status").GetInt32().Should().Be(404);
+        doc.RootElement.GetProperty("props")
+            .GetProperty("title")
+            .GetString()
+            .Should()
+            .Be("Not Found");
+    }
+
+    [Fact]
+    public async Task NonInertiaRequest_NotFoundException_ReturnsJsonProblemDetails()
+    {
+        var context = CreateHttpContext();
+        var exception = new NotFoundException("Product", 42);
+
+        var handled = await _handler.TryHandleAsync(context, exception, CancellationToken.None);
+
+        handled.Should().BeTrue();
+        context.Response.StatusCode.Should().Be(404);
+
+        var doc = await ReadResponseBodyAsync(context);
+        doc.RootElement.GetProperty("title").GetString().Should().Be("Not Found");
+        doc.RootElement.TryGetProperty("component", out _).Should().BeFalse();
+    }
+
+    [Fact]
+    public async Task InertiaRequest_UnhandledException_ReturnsInertia500_WithoutSensitiveDetails()
+    {
+        var context = CreateHttpContext();
+        context.Request.Headers["X-Inertia"] = "true";
+        context.Request.Headers["X-Inertia-Version"] = "1";
+        var exception = new InvalidOperationException("Sensitive DB error");
+
+        var handled = await _handler.TryHandleAsync(context, exception, CancellationToken.None);
+
+        handled.Should().BeTrue();
+        context.Response.StatusCode.Should().Be(500);
+
+        var doc = await ReadResponseBodyAsync(context);
+        doc.RootElement.GetProperty("component").GetString().Should().Be("Error/500");
+        var props = doc.RootElement.GetProperty("props");
+        props.GetProperty("message").GetString().Should().NotContain("Sensitive DB error");
+        props
+            .GetProperty("message")
+            .GetString()
+            .Should()
+            .Be("An unexpected error occurred. Please try again later.");
+    }
 }

From d041602a5f839ed3ff8ffe3330a91e823e7712c5 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Sat, 11 Apr 2026 22:44:27 +0200
Subject: [PATCH 03/10] feat: add status code pages middleware and
 /error/{statusCode} endpoint

---
 .../SimpleModuleHostExtensions.cs             | 32 +++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/framework/SimpleModule.Hosting/SimpleModuleHostExtensions.cs b/framework/SimpleModule.Hosting/SimpleModuleHostExtensions.cs
index 0802cc09..b194a5e5 100644
--- a/framework/SimpleModule.Hosting/SimpleModuleHostExtensions.cs
+++ b/framework/SimpleModule.Hosting/SimpleModuleHostExtensions.cs
@@ -149,6 +149,7 @@ public static async Task UseSimpleModuleInfrastructure(this WebApplication app)
 
         app.UseForwardedHeaders();
         app.UseExceptionHandler();
+        app.UseStatusCodePagesWithReExecute("/error/{0}");
 
         var options = app.Services.GetRequiredService<SimpleModuleOptions>();
         if (options.EnableSwagger && app.Environment.IsDevelopment())
@@ -240,6 +241,37 @@ public static async Task UseSimpleModuleInfrastructure(this WebApplication app)
                 )
                 .AllowAnonymous();
         }
+
+        app.MapGet(
+                "/error/{statusCode:int}",
+                (int statusCode) =>
+                {
+                    var (title, message) = statusCode switch
+                    {
+                        403 => (
+                            ErrorMessages.ForbiddenTitle,
+                            ErrorMessages.DefaultForbiddenMessage
+                        ),
+                        404 => (ErrorMessages.NotFoundTitle, ErrorMessages.DefaultNotFoundMessage),
+                        _ => (
+                            ErrorMessages.InternalServerErrorTitle,
+                            ErrorMessages.UnexpectedError
+                        ),
+                    };
+
+                    return SimpleModule.Core.Inertia.Inertia.Render(
+                        $"Error/{statusCode}",
+                        new
+                        {
+                            status = statusCode,
+                            title,
+                            message,
+                        }
+                    );
+                }
+            )
+            .AllowAnonymous()
+            .ExcludeFromDescription();
     }
 
     private static void BridgeAspireConnectionString(ConfigurationManager configuration)

From c417859832022f361fb199fc6dcb495464ff0c60 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Sat, 11 Apr 2026 22:46:23 +0200
Subject: [PATCH 04/10] feat: add React error page components (404, 500, 403)
 in @simplemodule/ui

---
 .../components/errors/error-page-403.tsx      | 33 +++++++++++++++
 .../components/errors/error-page-404.tsx      | 33 +++++++++++++++
 .../components/errors/error-page-500.tsx      | 33 +++++++++++++++
 .../components/errors/error-page-layout.tsx   | 42 +++++++++++++++++++
 .../components/errors/index.ts                |  4 ++
 packages/SimpleModule.UI/package.json         |  3 +-
 6 files changed, 147 insertions(+), 1 deletion(-)
 create mode 100644 packages/SimpleModule.UI/components/errors/error-page-403.tsx
 create mode 100644 packages/SimpleModule.UI/components/errors/error-page-404.tsx
 create mode 100644 packages/SimpleModule.UI/components/errors/error-page-500.tsx
 create mode 100644 packages/SimpleModule.UI/components/errors/error-page-layout.tsx
 create mode 100644 packages/SimpleModule.UI/components/errors/index.ts

diff --git a/packages/SimpleModule.UI/components/errors/error-page-403.tsx b/packages/SimpleModule.UI/components/errors/error-page-403.tsx
new file mode 100644
index 00000000..145bd771
--- /dev/null
+++ b/packages/SimpleModule.UI/components/errors/error-page-403.tsx
@@ -0,0 +1,33 @@
+import { ErrorPageLayout } from './error-page-layout';
+
+interface Props {
+  status?: number;
+  title?: string;
+  message?: string;
+}
+
+export default function ErrorPage403({ message }: Props) {
+  return (
+    <ErrorPageLayout
+      statusCode={403}
+      icon={
+        <svg
+          className="h-7 w-7 text-danger-text"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.5"
+          viewBox="0 0 24 24"
+          aria-hidden="true"
+        >
+          <path
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            d="M9 12.75 11.25 15 15 9.75m-3-7.036A11.959 11.959 0 0 1 3.598 6 11.99 11.99 0 0 0 3 9.749c0 5.592 3.824 10.29 9 11.623 5.176-1.332 9-6.03 9-11.622 0-1.31-.21-2.571-.598-3.751h-.152c-3.196 0-6.1-1.248-8.25-3.285Z"
+          />
+        </svg>
+      }
+      title="Access denied"
+      description={message ?? 'You do not have permission to access this resource.'}
+    />
+  );
+}
diff --git a/packages/SimpleModule.UI/components/errors/error-page-404.tsx b/packages/SimpleModule.UI/components/errors/error-page-404.tsx
new file mode 100644
index 00000000..fd5b70e8
--- /dev/null
+++ b/packages/SimpleModule.UI/components/errors/error-page-404.tsx
@@ -0,0 +1,33 @@
+import { ErrorPageLayout } from './error-page-layout';
+
+interface Props {
+  status?: number;
+  title?: string;
+  message?: string;
+}
+
+export default function ErrorPage404({ message }: Props) {
+  return (
+    <ErrorPageLayout
+      statusCode={404}
+      icon={
+        <svg
+          className="h-7 w-7 text-danger-text"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.5"
+          viewBox="0 0 24 24"
+          aria-hidden="true"
+        >
+          <path
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            d="m21 21-5.197-5.197m0 0A7.5 7.5 0 1 0 5.196 5.196a7.5 7.5 0 0 0 10.607 10.607ZM13.5 10.5h-6"
+          />
+        </svg>
+      }
+      title="Page not found"
+      description={message ?? 'The page you are looking for does not exist or has been moved.'}
+    />
+  );
+}
diff --git a/packages/SimpleModule.UI/components/errors/error-page-500.tsx b/packages/SimpleModule.UI/components/errors/error-page-500.tsx
new file mode 100644
index 00000000..b765b39a
--- /dev/null
+++ b/packages/SimpleModule.UI/components/errors/error-page-500.tsx
@@ -0,0 +1,33 @@
+import { ErrorPageLayout } from './error-page-layout';
+
+interface Props {
+  status?: number;
+  title?: string;
+  message?: string;
+}
+
+export default function ErrorPage500({ message }: Props) {
+  return (
+    <ErrorPageLayout
+      statusCode={500}
+      icon={
+        <svg
+          className="h-7 w-7 text-danger-text"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.5"
+          viewBox="0 0 24 24"
+          aria-hidden="true"
+        >
+          <path
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            d="M12 9v3.75m-9.303 3.376c-.866 1.5.217 3.374 1.948 3.374h14.71c1.73 0 2.813-1.874 1.948-3.374L13.949 3.378c-.866-1.5-3.032-1.5-3.898 0L2.697 16.126ZM12 15.75h.007v.008H12v-.008Z"
+          />
+        </svg>
+      }
+      title="Something went wrong"
+      description={message ?? 'An unexpected error occurred. Please try again later.'}
+    />
+  );
+}
diff --git a/packages/SimpleModule.UI/components/errors/error-page-layout.tsx b/packages/SimpleModule.UI/components/errors/error-page-layout.tsx
new file mode 100644
index 00000000..5dd8e808
--- /dev/null
+++ b/packages/SimpleModule.UI/components/errors/error-page-layout.tsx
@@ -0,0 +1,42 @@
+import type * as React from 'react';
+import { DarkModeToggle } from '../layouts/dark-mode-toggle';
+
+interface ErrorPageLayoutProps {
+  statusCode: number;
+  icon: React.ReactNode;
+  title: string;
+  description: string;
+}
+
+export function ErrorPageLayout({ statusCode, icon, title, description }: ErrorPageLayoutProps) {
+  return (
+    <div className="flex min-h-screen flex-col items-center justify-center bg-surface px-4">
+      <div className="absolute top-4 right-4">
+        <DarkModeToggle />
+      </div>
+      <div className="w-full max-w-md text-center">
+        <p className="text-[8rem] leading-none font-bold text-text-muted/20">{statusCode}</p>
+        <div className="mx-auto -mt-4 mb-4 flex h-14 w-14 items-center justify-center rounded-full bg-danger-bg">
+          {icon}
+        </div>
+        <h1 className="text-2xl font-semibold text-text">{title}</h1>
+        <p className="mt-2 text-sm text-text-muted">{description}</p>
+        <div className="mt-8 flex justify-center gap-3">
+          <a
+            href="/"
+            className="inline-flex items-center justify-center rounded-lg bg-primary px-4 py-2 text-sm font-medium text-primary-foreground hover:bg-primary/90"
+          >
+            Go home
+          </a>
+          <button
+            type="button"
+            onClick={() => window.history.back()}
+            className="inline-flex items-center justify-center rounded-lg border border-border bg-surface px-4 py-2 text-sm font-medium text-text hover:bg-surface-raised"
+          >
+            Go back
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/packages/SimpleModule.UI/components/errors/index.ts b/packages/SimpleModule.UI/components/errors/index.ts
new file mode 100644
index 00000000..ff7752e3
--- /dev/null
+++ b/packages/SimpleModule.UI/components/errors/index.ts
@@ -0,0 +1,4 @@
+export { default as ErrorPage403 } from './error-page-403';
+export { default as ErrorPage404 } from './error-page-404';
+export { default as ErrorPage500 } from './error-page-500';
+export { ErrorPageLayout } from './error-page-layout';
diff --git a/packages/SimpleModule.UI/package.json b/packages/SimpleModule.UI/package.json
index 868316cb..3a376982 100644
--- a/packages/SimpleModule.UI/package.json
+++ b/packages/SimpleModule.UI/package.json
@@ -7,7 +7,8 @@
     ".": "./components/index.ts",
     "./lib/utils": "./lib/utils.ts",
     "./hooks": "./hooks/use-feature-flag.ts",
-    "./layouts": "./components/layouts/index.ts"
+    "./layouts": "./components/layouts/index.ts",
+    "./errors": "./components/errors/index.ts"
   },
   "peerDependencies": {
     "react": "^19.0.0",

From f5fa6101a40e3f7d85cca5cd78661c84612c7784 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Sat, 11 Apr 2026 22:47:44 +0200
Subject: [PATCH 05/10] feat: wire error page resolution and httpException
 handling in ClientApp

---
 template/SimpleModule.Host/ClientApp/app.tsx | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/template/SimpleModule.Host/ClientApp/app.tsx b/template/SimpleModule.Host/ClientApp/app.tsx
index 4da1e015..ee5d92b9 100644
--- a/template/SimpleModule.Host/ClientApp/app.tsx
+++ b/template/SimpleModule.Host/ClientApp/app.tsx
@@ -1,6 +1,8 @@
 import { createInertiaApp, router } from '@inertiajs/react';
 import { resolvePage } from '@simplemodule/client/resolve-page';
+import { ErrorPage403, ErrorPage404, ErrorPage500 } from '@simplemodule/ui/errors';
 import { resolveLayout } from '@simplemodule/ui/layouts';
+import type React from 'react';
 import { createRoot } from 'react-dom/client';
 
 // In Vite dev server mode, import the Tailwind CSS entry so that
@@ -143,6 +145,17 @@ function showErrorToast(message: string) {
 
 createInertiaApp({
   resolve: async (name) => {
+    // Error pages are bundled in ClientApp, not in module pages.js files
+    const errorPages: Record<string, { default: React.ComponentType }> = {
+      'Error/404': { default: ErrorPage404 },
+      'Error/403': { default: ErrorPage403 },
+      'Error/500': { default: ErrorPage500 },
+    };
+
+    if (name in errorPages) {
+      return errorPages[name];
+    }
+
     try {
       const page = await resolvePage(name);
       return resolveLayout(page);

From dab7f2f1b1e12336d7926b8ee1f45af1967abbe0 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Sat, 11 Apr 2026 22:49:36 +0200
Subject: [PATCH 06/10] feat: add static error.html fallback and configure
 exception handler

---
 .gitignore                                    |  1 +
 .../SimpleModuleHostExtensions.cs             | 23 +++++-
 template/SimpleModule.Host/wwwroot/error.html | 80 +++++++++++++++++++
 3 files changed, 103 insertions(+), 1 deletion(-)
 create mode 100644 template/SimpleModule.Host/wwwroot/error.html

diff --git a/.gitignore b/.gitignore
index a7dbbac6..399d592b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -425,6 +425,7 @@ modules/**/wwwroot/*
 template/SimpleModule.Host/wwwroot/*
 !template/SimpleModule.Host/wwwroot/favicon.svg
 !template/SimpleModule.Host/wwwroot/index.html
+!template/SimpleModule.Host/wwwroot/error.html
 
 # Tailwind CSS module scan directory
 template/SimpleModule.Host/Styles/_scan/
diff --git a/framework/SimpleModule.Hosting/SimpleModuleHostExtensions.cs b/framework/SimpleModule.Hosting/SimpleModuleHostExtensions.cs
index b194a5e5..8095e417 100644
--- a/framework/SimpleModule.Hosting/SimpleModuleHostExtensions.cs
+++ b/framework/SimpleModule.Hosting/SimpleModuleHostExtensions.cs
@@ -148,7 +148,28 @@ public static async Task UseSimpleModuleInfrastructure(this WebApplication app)
         }
 
         app.UseForwardedHeaders();
-        app.UseExceptionHandler();
+        app.UseExceptionHandler(errorApp =>
+        {
+            errorApp.Run(async context =>
+            {
+                // If GlobalExceptionHandler already wrote the response, do nothing
+                if (context.Response.HasStarted)
+                    return;
+
+                // Fallback: serve static error.html for catastrophic failures
+                context.Response.StatusCode = StatusCodes.Status500InternalServerError;
+                context.Response.ContentType = "text/html";
+                var errorPage = Path.Combine(app.Environment.WebRootPath, "error.html");
+                if (File.Exists(errorPage))
+                {
+                    await context.Response.SendFileAsync(errorPage);
+                }
+                else
+                {
+                    await context.Response.WriteAsync("<h1>500 Internal Server Error</h1>");
+                }
+            });
+        });
         app.UseStatusCodePagesWithReExecute("/error/{0}");
 
         var options = app.Services.GetRequiredService<SimpleModuleOptions>();
diff --git a/template/SimpleModule.Host/wwwroot/error.html b/template/SimpleModule.Host/wwwroot/error.html
new file mode 100644
index 00000000..a7b40b41
--- /dev/null
+++ b/template/SimpleModule.Host/wwwroot/error.html
@@ -0,0 +1,80 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="color-scheme" content="light dark" />
+    <title>Error - SimpleModule</title>
+    <style>
+        *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+        body {
+            font-family: 'DM Sans', system-ui, -apple-system, sans-serif;
+            min-height: 100vh;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            background: #fafafa;
+            color: #1a1a1a;
+            padding: 1rem;
+        }
+        @media (prefers-color-scheme: dark) {
+            body { background: #0a0a0a; color: #e5e5e5; }
+            .code { color: rgba(229, 229, 229, 0.15); }
+            .btn-primary { background: #059669; }
+            .btn-secondary { background: #171717; border-color: #262626; color: #e5e5e5; }
+            .btn-secondary:hover { background: #262626; }
+        }
+        .container { text-align: center; max-width: 28rem; width: 100%; }
+        .code {
+            font-size: 8rem;
+            font-weight: 700;
+            line-height: 1;
+            color: rgba(0, 0, 0, 0.08);
+        }
+        .icon {
+            width: 3.5rem; height: 3.5rem;
+            margin: -1rem auto 1rem;
+            background: #fef2f2;
+            border-radius: 50%;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+        }
+        @media (prefers-color-scheme: dark) {
+            .icon { background: #450a0a; }
+            .icon svg { color: #fca5a5; }
+        }
+        .icon svg { width: 1.75rem; height: 1.75rem; color: #dc2626; }
+        h1 { font-size: 1.5rem; font-weight: 600; margin-bottom: 0.5rem; }
+        p { font-size: 0.875rem; color: #737373; line-height: 1.5; }
+        .actions { margin-top: 2rem; display: flex; gap: 0.75rem; justify-content: center; }
+        .btn {
+            display: inline-flex; align-items: center; justify-content: center;
+            padding: 0.5rem 1rem; border-radius: 0.5rem;
+            font-size: 0.875rem; font-weight: 500;
+            text-decoration: none; border: 1px solid transparent;
+            cursor: pointer;
+        }
+        .btn-primary { background: #059669; color: #fff; }
+        .btn-primary:hover { opacity: 0.9; }
+        .btn-secondary { background: #fff; border-color: #e5e5e5; color: #1a1a1a; }
+        .btn-secondary:hover { background: #f5f5f5; }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <p class="code">500</p>
+        <div class="icon">
+            <svg fill="none" stroke="currentColor" stroke-width="1.5" viewBox="0 0 24 24">
+                <path stroke-linecap="round" stroke-linejoin="round" d="M12 9v3.75m-9.303 3.376c-.866 1.5.217 3.374 1.948 3.374h14.71c1.73 0 2.813-1.874 1.948-3.374L13.949 3.378c-.866-1.5-3.032-1.5-3.898 0L2.697 16.126ZM12 15.75h.007v.008H12v-.008Z" />
+            </svg>
+        </div>
+        <h1>Something went wrong</h1>
+        <p>An unexpected error occurred. Please try again later.</p>
+        <div class="actions">
+            <a href="/" class="btn btn-primary">Go home</a>
+            <button type="button" onclick="history.back()" class="btn btn-secondary">Go back</button>
+        </div>
+    </div>
+</body>
+</html>

From 042211c59eb1be983e907bef28d47aa533eb9cc7 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Sun, 12 Apr 2026 00:14:11 +0200
Subject: [PATCH 07/10] =?UTF-8?q?refactor:=20simplify=20error=20pages=20?=
 =?UTF-8?q?=E2=80=94=20hoist=20constants,=20share=20types,=20cache=20fallb?=
 =?UTF-8?q?ack=20HTML?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Hoist errorPages record to module scope in app.tsx (avoid per-resolve allocation)
- Extract shared ErrorPageProps type from duplicated Props interfaces
- Cache error.html bytes at startup instead of File.Exists per request
- Remove narrating comments in GlobalExceptionHandler
---
 .../Exceptions/GlobalExceptionHandler.cs        |  2 --
 .../SimpleModuleHostExtensions.cs               | 13 ++++++++-----
 .../components/errors/error-page-403.tsx        | 10 ++--------
 .../components/errors/error-page-404.tsx        | 10 ++--------
 .../components/errors/error-page-500.tsx        | 10 ++--------
 .../components/errors/error-page-layout.tsx     |  6 ++++++
 .../SimpleModule.UI/components/errors/index.ts  |  1 +
 template/SimpleModule.Host/ClientApp/app.tsx    | 17 ++++++++---------
 8 files changed, 29 insertions(+), 40 deletions(-)

diff --git a/framework/SimpleModule.Core/Exceptions/GlobalExceptionHandler.cs b/framework/SimpleModule.Core/Exceptions/GlobalExceptionHandler.cs
index 5c887765..c53a5202 100644
--- a/framework/SimpleModule.Core/Exceptions/GlobalExceptionHandler.cs
+++ b/framework/SimpleModule.Core/Exceptions/GlobalExceptionHandler.cs
@@ -68,13 +68,11 @@ CancellationToken cancellationToken
 
         httpContext.Response.StatusCode = statusCode;
 
-        // Inertia requests get an Inertia error page response
         if (httpContext.Request.Headers.ContainsKey("X-Inertia"))
         {
             return await WriteInertiaErrorAsync(httpContext, statusCode, title, detail);
         }
 
-        // API/non-Inertia requests get ProblemDetails JSON
         var problemDetails = new ProblemDetails
         {
             Status = statusCode,
diff --git a/framework/SimpleModule.Hosting/SimpleModuleHostExtensions.cs b/framework/SimpleModule.Hosting/SimpleModuleHostExtensions.cs
index 8095e417..a31f5e4b 100644
--- a/framework/SimpleModule.Hosting/SimpleModuleHostExtensions.cs
+++ b/framework/SimpleModule.Hosting/SimpleModuleHostExtensions.cs
@@ -148,21 +148,24 @@ public static async Task UseSimpleModuleInfrastructure(this WebApplication app)
         }
 
         app.UseForwardedHeaders();
+
+        var errorHtmlPath = Path.Combine(app.Environment.WebRootPath, "error.html");
+        var errorHtmlBytes = File.Exists(errorHtmlPath)
+            ? await File.ReadAllBytesAsync(errorHtmlPath)
+            : null;
+
         app.UseExceptionHandler(errorApp =>
         {
             errorApp.Run(async context =>
             {
-                // If GlobalExceptionHandler already wrote the response, do nothing
                 if (context.Response.HasStarted)
                     return;
 
-                // Fallback: serve static error.html for catastrophic failures
                 context.Response.StatusCode = StatusCodes.Status500InternalServerError;
                 context.Response.ContentType = "text/html";
-                var errorPage = Path.Combine(app.Environment.WebRootPath, "error.html");
-                if (File.Exists(errorPage))
+                if (errorHtmlBytes is not null)
                 {
-                    await context.Response.SendFileAsync(errorPage);
+                    await context.Response.Body.WriteAsync(errorHtmlBytes);
                 }
                 else
                 {
diff --git a/packages/SimpleModule.UI/components/errors/error-page-403.tsx b/packages/SimpleModule.UI/components/errors/error-page-403.tsx
index 145bd771..899ce36f 100644
--- a/packages/SimpleModule.UI/components/errors/error-page-403.tsx
+++ b/packages/SimpleModule.UI/components/errors/error-page-403.tsx
@@ -1,12 +1,6 @@
-import { ErrorPageLayout } from './error-page-layout';
+import { ErrorPageLayout, type ErrorPageProps } from './error-page-layout';
 
-interface Props {
-  status?: number;
-  title?: string;
-  message?: string;
-}
-
-export default function ErrorPage403({ message }: Props) {
+export default function ErrorPage403({ message }: ErrorPageProps) {
   return (
     <ErrorPageLayout
       statusCode={403}
diff --git a/packages/SimpleModule.UI/components/errors/error-page-404.tsx b/packages/SimpleModule.UI/components/errors/error-page-404.tsx
index fd5b70e8..bbeb7f6c 100644
--- a/packages/SimpleModule.UI/components/errors/error-page-404.tsx
+++ b/packages/SimpleModule.UI/components/errors/error-page-404.tsx
@@ -1,12 +1,6 @@
-import { ErrorPageLayout } from './error-page-layout';
+import { ErrorPageLayout, type ErrorPageProps } from './error-page-layout';
 
-interface Props {
-  status?: number;
-  title?: string;
-  message?: string;
-}
-
-export default function ErrorPage404({ message }: Props) {
+export default function ErrorPage404({ message }: ErrorPageProps) {
   return (
     <ErrorPageLayout
       statusCode={404}
diff --git a/packages/SimpleModule.UI/components/errors/error-page-500.tsx b/packages/SimpleModule.UI/components/errors/error-page-500.tsx
index b765b39a..297cd801 100644
--- a/packages/SimpleModule.UI/components/errors/error-page-500.tsx
+++ b/packages/SimpleModule.UI/components/errors/error-page-500.tsx
@@ -1,12 +1,6 @@
-import { ErrorPageLayout } from './error-page-layout';
+import { ErrorPageLayout, type ErrorPageProps } from './error-page-layout';
 
-interface Props {
-  status?: number;
-  title?: string;
-  message?: string;
-}
-
-export default function ErrorPage500({ message }: Props) {
+export default function ErrorPage500({ message }: ErrorPageProps) {
   return (
     <ErrorPageLayout
       statusCode={500}
diff --git a/packages/SimpleModule.UI/components/errors/error-page-layout.tsx b/packages/SimpleModule.UI/components/errors/error-page-layout.tsx
index 5dd8e808..40c06fc3 100644
--- a/packages/SimpleModule.UI/components/errors/error-page-layout.tsx
+++ b/packages/SimpleModule.UI/components/errors/error-page-layout.tsx
@@ -1,6 +1,12 @@
 import type * as React from 'react';
 import { DarkModeToggle } from '../layouts/dark-mode-toggle';
 
+export interface ErrorPageProps {
+  status?: number;
+  title?: string;
+  message?: string;
+}
+
 interface ErrorPageLayoutProps {
   statusCode: number;
   icon: React.ReactNode;
diff --git a/packages/SimpleModule.UI/components/errors/index.ts b/packages/SimpleModule.UI/components/errors/index.ts
index ff7752e3..1c9ec142 100644
--- a/packages/SimpleModule.UI/components/errors/index.ts
+++ b/packages/SimpleModule.UI/components/errors/index.ts
@@ -1,4 +1,5 @@
 export { default as ErrorPage403 } from './error-page-403';
 export { default as ErrorPage404 } from './error-page-404';
 export { default as ErrorPage500 } from './error-page-500';
+export type { ErrorPageProps } from './error-page-layout';
 export { ErrorPageLayout } from './error-page-layout';
diff --git a/template/SimpleModule.Host/ClientApp/app.tsx b/template/SimpleModule.Host/ClientApp/app.tsx
index ee5d92b9..2c1c5c2e 100644
--- a/template/SimpleModule.Host/ClientApp/app.tsx
+++ b/template/SimpleModule.Host/ClientApp/app.tsx
@@ -143,17 +143,16 @@ function showErrorToast(message: string) {
   setTimeout(() => container.remove(), 8000);
 }
 
+const ERROR_PAGES: Record<string, { default: React.ComponentType }> = {
+  'Error/404': { default: ErrorPage404 },
+  'Error/403': { default: ErrorPage403 },
+  'Error/500': { default: ErrorPage500 },
+};
+
 createInertiaApp({
   resolve: async (name) => {
-    // Error pages are bundled in ClientApp, not in module pages.js files
-    const errorPages: Record<string, { default: React.ComponentType }> = {
-      'Error/404': { default: ErrorPage404 },
-      'Error/403': { default: ErrorPage403 },
-      'Error/500': { default: ErrorPage500 },
-    };
-
-    if (name in errorPages) {
-      return errorPages[name];
+    if (name in ERROR_PAGES) {
+      return ERROR_PAGES[name];
     }
 
     try {

From 6005dd0a8bd7281068ca7f724df149f83e848c9e Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Sun, 12 Apr 2026 00:14:57 +0200
Subject: [PATCH 08/10] docs: add error pages design spec and implementation
 plan

---
 .../plans/2026-04-11-error-pages.md           | 882 ++++++++++++++++++
 .../specs/2026-04-11-error-pages-design.md    | 122 +++
 2 files changed, 1004 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-04-11-error-pages.md
 create mode 100644 docs/superpowers/specs/2026-04-11-error-pages-design.md

diff --git a/docs/superpowers/plans/2026-04-11-error-pages.md b/docs/superpowers/plans/2026-04-11-error-pages.md
new file mode 100644
index 00000000..e3715b99
--- /dev/null
+++ b/docs/superpowers/plans/2026-04-11-error-pages.md
@@ -0,0 +1,882 @@
+# Error Page Templates (404/500/403) Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add dedicated error page templates (404, 500, 403) with Inertia-rendered React pages and a static HTML fallback for catastrophic failures.
+
+**Architecture:** Two-layer approach. Layer 1: React error page components in `@simplemodule/ui` rendered via Inertia when the backend catches exceptions or the routing pipeline produces bare status codes. Layer 2: A static `error.html` served when React/Inertia itself fails. The `GlobalExceptionHandler` is extended to render Inertia error pages for browser requests and keeps JSON ProblemDetails for API requests. `UseStatusCodePagesWithReExecute` catches bare 404s/403s from the routing pipeline.
+
+**Tech Stack:** ASP.NET (.NET 10), React 19, Inertia.js, Tailwind CSS, lucide-react, xUnit + FluentAssertions
+
+---
+
+## File Map
+
+| File | Action | Responsibility |
+|------|--------|----------------|
+| `framework/SimpleModule.Core/Exceptions/ForbiddenException.cs` | Create | 403 exception class |
+| `framework/SimpleModule.Core/Constants/ErrorMessages.cs` | Modify | Add forbidden message constants |
+| `framework/SimpleModule.Core/Exceptions/GlobalExceptionHandler.cs` | Modify | Add 403 mapping + Inertia error rendering for browser requests |
+| `framework/SimpleModule.Hosting/SimpleModuleHostExtensions.cs` | Modify | Add `UseStatusCodePagesWithReExecute`, error endpoint |
+| `tests/SimpleModule.Core.Tests/GlobalExceptionHandlerTests.cs` | Modify | Add 403 test + Inertia rendering tests |
+| `packages/SimpleModule.UI/components/errors/error-page-layout.tsx` | Create | Shared centering/styling wrapper for all error pages |
+| `packages/SimpleModule.UI/components/errors/error-page-404.tsx` | Create | 404 error page component |
+| `packages/SimpleModule.UI/components/errors/error-page-500.tsx` | Create | 500 error page component |
+| `packages/SimpleModule.UI/components/errors/error-page-403.tsx` | Create | 403 error page component |
+| `packages/SimpleModule.UI/components/errors/index.ts` | Create | Barrel export for error components |
+| `packages/SimpleModule.UI/package.json` | Modify | Add `./errors` export entry |
+| `packages/SimpleModule.UI/components/layouts/layout-provider.tsx` | Modify | Skip auto-layout for error pages |
+| `template/SimpleModule.Host/ClientApp/app.tsx` | Modify | Resolve `Error/*` pages, update `httpException` handler |
+| `template/SimpleModule.Host/wwwroot/error.html` | Create | Static HTML fallback for catastrophic failures |
+
+---
+
+## Task 1: ForbiddenException and Error Constants
+
+**Files:**
+- Create: `framework/SimpleModule.Core/Exceptions/ForbiddenException.cs`
+- Modify: `framework/SimpleModule.Core/Constants/ErrorMessages.cs`
+- Test: `tests/SimpleModule.Core.Tests/GlobalExceptionHandlerTests.cs`
+
+- [ ] **Step 1: Create ForbiddenException class**
+
+Create `framework/SimpleModule.Core/Exceptions/ForbiddenException.cs`:
+
+```csharp
+using SimpleModule.Core.Constants;
+
+namespace SimpleModule.Core.Exceptions;
+
+public sealed class ForbiddenException : Exception
+{
+    public ForbiddenException()
+        : base(ErrorMessages.DefaultForbiddenMessage) { }
+
+    public ForbiddenException(string message)
+        : base(message) { }
+
+    public ForbiddenException(string message, Exception innerException)
+        : base(message, innerException) { }
+}
+```
+
+- [ ] **Step 2: Add forbidden constants to ErrorMessages**
+
+In `framework/SimpleModule.Core/Constants/ErrorMessages.cs`, add after the `ConflictTitle` line:
+
+```csharp
+public const string ForbiddenTitle = "Forbidden";
+```
+
+And after the `DefaultConflictMessage` line:
+
+```csharp
+public const string DefaultForbiddenMessage = "You do not have permission to access this resource.";
+```
+
+- [ ] **Step 3: Add ForbiddenException mapping to GlobalExceptionHandler**
+
+In `framework/SimpleModule.Core/Exceptions/GlobalExceptionHandler.cs`, add a new case in the switch expression (line 31, after the `ConflictException` case):
+
+```csharp
+ForbiddenException => (StatusCodes.Status403Forbidden, ErrorMessages.ForbiddenTitle, null),
+```
+
+- [ ] **Step 4: Write failing test for ForbiddenException handling**
+
+Add to `tests/SimpleModule.Core.Tests/GlobalExceptionHandlerTests.cs`:
+
+```csharp
+[Fact]
+public async Task ForbiddenException_Returns403()
+{
+    var context = CreateHttpContext();
+    var exception = new ForbiddenException("Access denied to admin panel");
+
+    var handled = await _handler.TryHandleAsync(context, exception, CancellationToken.None);
+
+    handled.Should().BeTrue();
+    context.Response.StatusCode.Should().Be(403);
+
+    var doc = await ReadResponseBodyAsync(context);
+    doc.RootElement.GetProperty("title").GetString().Should().Be("Forbidden");
+    doc.RootElement.GetProperty("detail").GetString().Should().Be("Access denied to admin panel");
+}
+```
+
+- [ ] **Step 5: Run tests to verify**
+
+Run: `dotnet test tests/SimpleModule.Core.Tests --filter "GlobalExceptionHandler" -v minimal`
+Expected: All tests pass including the new `ForbiddenException_Returns403`.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add framework/SimpleModule.Core/Exceptions/ForbiddenException.cs framework/SimpleModule.Core/Constants/ErrorMessages.cs framework/SimpleModule.Core/Exceptions/GlobalExceptionHandler.cs tests/SimpleModule.Core.Tests/GlobalExceptionHandlerTests.cs
+git commit -m "feat: add ForbiddenException with 403 mapping in GlobalExceptionHandler"
+```
+
+---
+
+## Task 2: Inertia Error Rendering in GlobalExceptionHandler
+
+**Files:**
+- Modify: `framework/SimpleModule.Core/Exceptions/GlobalExceptionHandler.cs`
+- Test: `tests/SimpleModule.Core.Tests/GlobalExceptionHandlerTests.cs`
+
+- [ ] **Step 1: Write failing test for Inertia error rendering**
+
+Add to `tests/SimpleModule.Core.Tests/GlobalExceptionHandlerTests.cs`:
+
+```csharp
+[Fact]
+public async Task InertiaRequest_NotFoundException_ReturnsInertiaErrorPage()
+{
+    var context = CreateHttpContext();
+    context.Request.Headers["X-Inertia"] = "true";
+    context.Request.Headers["X-Inertia-Version"] = "1";
+    var exception = new NotFoundException("Product", 42);
+
+    var handled = await _handler.TryHandleAsync(context, exception, CancellationToken.None);
+
+    handled.Should().BeTrue();
+    context.Response.StatusCode.Should().Be(404);
+    context.Response.Headers["X-Inertia"].ToString().Should().Be("true");
+    context.Response.ContentType.Should().Contain("application/json");
+
+    var doc = await ReadResponseBodyAsync(context);
+    doc.RootElement.GetProperty("component").GetString().Should().Be("Error/404");
+    doc.RootElement.GetProperty("props").GetProperty("status").GetInt32().Should().Be(404);
+    doc.RootElement.GetProperty("props").GetProperty("title").GetString().Should().Be("Not Found");
+}
+
+[Fact]
+public async Task NonInertiaRequest_NotFoundException_ReturnsJsonProblemDetails()
+{
+    var context = CreateHttpContext();
+    // No X-Inertia header = API request
+    var exception = new NotFoundException("Product", 42);
+
+    var handled = await _handler.TryHandleAsync(context, exception, CancellationToken.None);
+
+    handled.Should().BeTrue();
+    context.Response.StatusCode.Should().Be(404);
+
+    var doc = await ReadResponseBodyAsync(context);
+    doc.RootElement.GetProperty("title").GetString().Should().Be("Not Found");
+    // Should NOT have Inertia fields
+    doc.RootElement.TryGetProperty("component", out _).Should().BeFalse();
+}
+
+[Fact]
+public async Task InertiaRequest_UnhandledException_ReturnsInertia500_WithoutSensitiveDetails()
+{
+    var context = CreateHttpContext();
+    context.Request.Headers["X-Inertia"] = "true";
+    context.Request.Headers["X-Inertia-Version"] = "1";
+    var exception = new InvalidOperationException("Sensitive DB error");
+
+    var handled = await _handler.TryHandleAsync(context, exception, CancellationToken.None);
+
+    handled.Should().BeTrue();
+    context.Response.StatusCode.Should().Be(500);
+
+    var doc = await ReadResponseBodyAsync(context);
+    doc.RootElement.GetProperty("component").GetString().Should().Be("Error/500");
+    var props = doc.RootElement.GetProperty("props");
+    props.GetProperty("message").GetString().Should().NotContain("Sensitive DB error");
+    props.GetProperty("message").GetString().Should().Be("An unexpected error occurred. Please try again later.");
+}
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `dotnet test tests/SimpleModule.Core.Tests --filter "InertiaRequest" -v minimal`
+Expected: FAIL — the handler currently always writes ProblemDetails JSON, not Inertia responses.
+
+- [ ] **Step 3: Implement Inertia error rendering in GlobalExceptionHandler**
+
+Replace the full content of `framework/SimpleModule.Core/Exceptions/GlobalExceptionHandler.cs`:
+
+```csharp
+using System.Text.Json;
+using Microsoft.AspNetCore.Diagnostics;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.Extensions.Logging;
+using SimpleModule.Core.Constants;
+using SimpleModule.Core.Inertia;
+
+namespace SimpleModule.Core.Exceptions;
+
+public sealed class GlobalExceptionHandler(ILogger<GlobalExceptionHandler> logger)
+    : IExceptionHandler
+{
+    private static readonly JsonSerializerOptions InertiaJsonOptions =
+        new() { PropertyNamingPolicy = JsonNamingPolicy.CamelCase };
+
+    public async ValueTask<bool> TryHandleAsync(
+        HttpContext httpContext,
+        Exception exception,
+        CancellationToken cancellationToken
+    )
+    {
+        var (statusCode, title, errors) = exception switch
+        {
+            ValidationException ve => (
+                StatusCodes.Status400BadRequest,
+                ErrorMessages.ValidationErrorTitle,
+                ve.Errors
+            ),
+            ArgumentException => (
+                StatusCodes.Status400BadRequest,
+                ErrorMessages.ValidationErrorTitle,
+                null
+            ),
+            NotFoundException => (StatusCodes.Status404NotFound, ErrorMessages.NotFoundTitle, null),
+            ForbiddenException => (
+                StatusCodes.Status403Forbidden,
+                ErrorMessages.ForbiddenTitle,
+                null
+            ),
+            ConflictException => (StatusCodes.Status409Conflict, ErrorMessages.ConflictTitle, null),
+            _ => (
+                StatusCodes.Status500InternalServerError,
+                ErrorMessages.InternalServerErrorTitle,
+                null
+            ),
+        };
+
+        if (statusCode == StatusCodes.Status500InternalServerError)
+        {
+            logger.LogError(exception, "Unhandled exception occurred");
+        }
+        else
+        {
+            logger.LogWarning(
+                exception,
+                "Handled exception occurred: {Message}",
+                exception.Message
+            );
+        }
+
+        var detail =
+            statusCode == StatusCodes.Status500InternalServerError
+                ? ErrorMessages.UnexpectedError
+                : exception.Message;
+
+        httpContext.Response.StatusCode = statusCode;
+
+        // Inertia requests get an Inertia error page response
+        if (httpContext.Request.Headers.ContainsKey("X-Inertia"))
+        {
+            return await WriteInertiaErrorAsync(httpContext, statusCode, title, detail);
+        }
+
+        // API/non-Inertia requests get ProblemDetails JSON
+        var problemDetails = new ProblemDetails
+        {
+            Status = statusCode,
+            Title = title,
+            Detail = detail,
+        };
+
+        if (errors is not null)
+        {
+            problemDetails.Extensions["errors"] = errors;
+        }
+
+        await httpContext.Response.WriteAsJsonAsync(problemDetails, cancellationToken);
+        return true;
+    }
+
+    private static async ValueTask<bool> WriteInertiaErrorAsync(
+        HttpContext httpContext,
+        int statusCode,
+        string title,
+        string message
+    )
+    {
+        var component = $"Error/{statusCode}";
+        var props = new { status = statusCode, title, message };
+
+        var pageData = new
+        {
+            component,
+            props,
+            url = httpContext.Request.Path + httpContext.Request.QueryString,
+            version = InertiaMiddleware.Version,
+        };
+
+        httpContext.Response.Headers["X-Inertia"] = "true";
+        httpContext.Response.Headers["Vary"] = "X-Inertia";
+        httpContext.Response.ContentType = "application/json";
+        var json = JsonSerializer.Serialize(pageData, InertiaJsonOptions);
+        await httpContext.Response.WriteAsync(json);
+        return true;
+    }
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `dotnet test tests/SimpleModule.Core.Tests --filter "GlobalExceptionHandler" -v minimal`
+Expected: All tests pass (existing + new Inertia tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add framework/SimpleModule.Core/Exceptions/GlobalExceptionHandler.cs tests/SimpleModule.Core.Tests/GlobalExceptionHandlerTests.cs
+git commit -m "feat: render Inertia error pages for browser requests in GlobalExceptionHandler"
+```
+
+---
+
+## Task 3: Status Code Pages Middleware and Error Endpoint
+
+**Files:**
+- Modify: `framework/SimpleModule.Hosting/SimpleModuleHostExtensions.cs`
+
+- [ ] **Step 1: Add error endpoint and status code pages middleware**
+
+In `framework/SimpleModule.Hosting/SimpleModuleHostExtensions.cs`:
+
+**Add import** at the top of the file (after existing usings):
+
+```csharp
+using SimpleModule.Core.Inertia;
+```
+
+**Add `UseStatusCodePagesWithReExecute`** in the `UseSimpleModuleInfrastructure` method, right after line 151 (`app.UseExceptionHandler();`):
+
+```csharp
+app.UseStatusCodePagesWithReExecute("/error/{0}");
+```
+
+**Add error endpoint mapping** at the end of the `UseSimpleModuleInfrastructure` method, right before the closing brace (after the health checks block, around line 242):
+
+```csharp
+app.MapGet(
+                "/error/{statusCode:int}",
+                (int statusCode) =>
+                {
+                    var (title, message) = statusCode switch
+                    {
+                        403 => (
+                            ErrorMessages.ForbiddenTitle,
+                            ErrorMessages.DefaultForbiddenMessage
+                        ),
+                        404 => (
+                            ErrorMessages.NotFoundTitle,
+                            ErrorMessages.DefaultNotFoundMessage
+                        ),
+                        _ => (
+                            ErrorMessages.InternalServerErrorTitle,
+                            ErrorMessages.UnexpectedError
+                        ),
+                    };
+
+                    return Inertia.Render(
+                        $"Error/{statusCode}",
+                        new
+                        {
+                            status = statusCode,
+                            title,
+                            message,
+                        }
+                    );
+                }
+            )
+            .AllowAnonymous()
+            .ExcludeFromDescription();
+```
+
+- [ ] **Step 2: Build to verify compilation**
+
+Run: `dotnet build framework/SimpleModule.Hosting/SimpleModule.Hosting.csproj`
+Expected: Build succeeds with no errors.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add framework/SimpleModule.Hosting/SimpleModuleHostExtensions.cs
+git commit -m "feat: add status code pages middleware and /error/{statusCode} endpoint"
+```
+
+---
+
+## Task 4: React Error Page Components
+
+**Files:**
+- Create: `packages/SimpleModule.UI/components/errors/error-page-layout.tsx`
+- Create: `packages/SimpleModule.UI/components/errors/error-page-404.tsx`
+- Create: `packages/SimpleModule.UI/components/errors/error-page-500.tsx`
+- Create: `packages/SimpleModule.UI/components/errors/error-page-403.tsx`
+- Create: `packages/SimpleModule.UI/components/errors/index.ts`
+- Modify: `packages/SimpleModule.UI/package.json`
+
+- [ ] **Step 1: Create shared error page layout**
+
+Create `packages/SimpleModule.UI/components/errors/error-page-layout.tsx`:
+
+```tsx
+import type * as React from 'react';
+import { DarkModeToggle } from '../layouts/dark-mode-toggle';
+
+interface ErrorPageLayoutProps {
+  statusCode: number;
+  icon: React.ReactNode;
+  title: string;
+  description: string;
+}
+
+export function ErrorPageLayout({ statusCode, icon, title, description }: ErrorPageLayoutProps) {
+  return (
+    <div className="flex min-h-screen flex-col items-center justify-center bg-surface px-4">
+      <div className="absolute top-4 right-4">
+        <DarkModeToggle />
+      </div>
+      <div className="w-full max-w-md text-center">
+        <p className="text-[8rem] leading-none font-bold text-text-muted/20">{statusCode}</p>
+        <div className="mx-auto -mt-4 mb-4 flex h-14 w-14 items-center justify-center rounded-full bg-danger-bg">
+          {icon}
+        </div>
+        <h1 className="text-2xl font-semibold text-text">{title}</h1>
+        <p className="mt-2 text-sm text-text-muted">{description}</p>
+        <div className="mt-8 flex justify-center gap-3">
+          <a
+            href="/"
+            className="inline-flex items-center justify-center rounded-lg bg-primary px-4 py-2 text-sm font-medium text-primary-foreground hover:bg-primary/90"
+          >
+            Go home
+          </a>
+          <button
+            type="button"
+            onClick={() => window.history.back()}
+            className="inline-flex items-center justify-center rounded-lg border border-border bg-surface px-4 py-2 text-sm font-medium text-text hover:bg-surface-raised"
+          >
+            Go back
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+- [ ] **Step 2: Create 404 error page**
+
+Create `packages/SimpleModule.UI/components/errors/error-page-404.tsx`:
+
+```tsx
+import { ErrorPageLayout } from './error-page-layout';
+
+interface Props {
+  status?: number;
+  title?: string;
+  message?: string;
+}
+
+export default function ErrorPage404({ message }: Props) {
+  return (
+    <ErrorPageLayout
+      statusCode={404}
+      icon={
+        <svg
+          className="h-7 w-7 text-danger-text"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.5"
+          viewBox="0 0 24 24"
+          aria-hidden="true"
+        >
+          <path
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            d="m21 21-5.197-5.197m0 0A7.5 7.5 0 1 0 5.196 5.196a7.5 7.5 0 0 0 10.607 10.607ZM13.5 10.5h-6"
+          />
+        </svg>
+      }
+      title="Page not found"
+      description={message ?? 'The page you are looking for does not exist or has been moved.'}
+    />
+  );
+}
+```
+
+- [ ] **Step 3: Create 500 error page**
+
+Create `packages/SimpleModule.UI/components/errors/error-page-500.tsx`:
+
+```tsx
+import { ErrorPageLayout } from './error-page-layout';
+
+interface Props {
+  status?: number;
+  title?: string;
+  message?: string;
+}
+
+export default function ErrorPage500({ message }: Props) {
+  return (
+    <ErrorPageLayout
+      statusCode={500}
+      icon={
+        <svg
+          className="h-7 w-7 text-danger-text"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.5"
+          viewBox="0 0 24 24"
+          aria-hidden="true"
+        >
+          <path
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            d="M12 9v3.75m-9.303 3.376c-.866 1.5.217 3.374 1.948 3.374h14.71c1.73 0 2.813-1.874 1.948-3.374L13.949 3.378c-.866-1.5-3.032-1.5-3.898 0L2.697 16.126ZM12 15.75h.007v.008H12v-.008Z"
+          />
+        </svg>
+      }
+      title="Something went wrong"
+      description={message ?? 'An unexpected error occurred. Please try again later.'}
+    />
+  );
+}
+```
+
+- [ ] **Step 4: Create 403 error page**
+
+Create `packages/SimpleModule.UI/components/errors/error-page-403.tsx`:
+
+```tsx
+import { ErrorPageLayout } from './error-page-layout';
+
+interface Props {
+  status?: number;
+  title?: string;
+  message?: string;
+}
+
+export default function ErrorPage403({ message }: Props) {
+  return (
+    <ErrorPageLayout
+      statusCode={403}
+      icon={
+        <svg
+          className="h-7 w-7 text-danger-text"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.5"
+          viewBox="0 0 24 24"
+          aria-hidden="true"
+        >
+          <path
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            d="M9 12.75 11.25 15 15 9.75m-3-7.036A11.959 11.959 0 0 1 3.598 6 11.99 11.99 0 0 0 3 9.749c0 5.592 3.824 10.29 9 11.623 5.176-1.332 9-6.03 9-11.622 0-1.31-.21-2.571-.598-3.751h-.152c-3.196 0-6.1-1.248-8.25-3.285Z"
+          />
+        </svg>
+      }
+      title="Access denied"
+      description={message ?? 'You do not have permission to access this resource.'}
+    />
+  );
+}
+```
+
+- [ ] **Step 5: Create barrel export**
+
+Create `packages/SimpleModule.UI/components/errors/index.ts`:
+
+```typescript
+export { default as ErrorPage403 } from './error-page-403';
+export { default as ErrorPage404 } from './error-page-404';
+export { default as ErrorPage500 } from './error-page-500';
+export { ErrorPageLayout } from './error-page-layout';
+```
+
+- [ ] **Step 6: Add `./errors` export to package.json**
+
+In `packages/SimpleModule.UI/package.json`, add to the `"exports"` object:
+
+```json
+"./errors": "./components/errors/index.ts"
+```
+
+- [ ] **Step 7: Verify frontend builds**
+
+Run: `npm run check` (from repo root)
+Expected: No lint or format errors.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add packages/SimpleModule.UI/components/errors/ packages/SimpleModule.UI/package.json
+git commit -m "feat: add React error page components (404, 500, 403) in @simplemodule/ui"
+```
+
+---
+
+## Task 5: Wire Error Pages into ClientApp
+
+**Files:**
+- Modify: `template/SimpleModule.Host/ClientApp/app.tsx`
+- Modify: `packages/SimpleModule.UI/components/layouts/layout-provider.tsx`
+
+- [ ] **Step 1: Update app.tsx to resolve error pages and redirect on httpException**
+
+In `template/SimpleModule.Host/ClientApp/app.tsx`:
+
+**Add imports** after the existing imports (line 4):
+
+```typescript
+import { ErrorPage404 } from '@simplemodule/ui/errors';
+import { ErrorPage403 } from '@simplemodule/ui/errors';
+import { ErrorPage500 } from '@simplemodule/ui/errors';
+```
+
+**Replace the `httpException` handler** (lines 100-119) with:
+
+```typescript
+// Handle non-Inertia error responses (404, 500, etc.) by showing a toast
+// for minor errors, or letting Inertia render error pages for page-level errors.
+router.on('httpException', (event) => {
+  event.preventDefault();
+
+  const response = event.detail.response;
+  const body = response.data as { detail?: string; title?: string } | string | undefined;
+  let parsed: { detail?: string; title?: string } | undefined;
+  if (typeof body === 'string') {
+    try {
+      parsed = JSON.parse(body);
+    } catch {
+      // non-JSON response body
+    }
+  } else {
+    parsed = body;
+  }
+  const message = parsed?.detail ?? parsed?.title ?? `Server error (${response.status})`;
+  showErrorToast(message);
+});
+```
+
+**Replace the `resolve` function** inside `createInertiaApp` (lines 145-153) with:
+
+```typescript
+  resolve: async (name) => {
+    // Error pages are bundled in ClientApp, not in module pages.js files
+    const errorPages: Record<string, { default: React.ComponentType<any> }> = {
+      'Error/404': { default: ErrorPage404 },
+      'Error/403': { default: ErrorPage403 },
+      'Error/500': { default: ErrorPage500 },
+    };
+
+    if (name in errorPages) {
+      return errorPages[name];
+    }
+
+    try {
+      const page = await resolvePage(name);
+      return resolveLayout(page);
+    } catch (err) {
+      showErrorToast(`Failed to load page "${name}". Try refreshing the page.`);
+      throw err;
+    }
+  },
+```
+
+Note: Error pages intentionally skip `resolveLayout` — they have no layout wrapper (minimal standalone design).
+
+- [ ] **Step 2: Add React import for type annotation**
+
+At the top of `app.tsx`, add if not present:
+
+```typescript
+import type React from 'react';
+```
+
+- [ ] **Step 3: Verify frontend builds**
+
+Run: `npm run check` (from repo root)
+Expected: No lint or format errors.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add template/SimpleModule.Host/ClientApp/app.tsx
+git commit -m "feat: wire error page resolution and httpException handling in ClientApp"
+```
+
+---
+
+## Task 6: Static HTML Fallback Page
+
+**Files:**
+- Create: `template/SimpleModule.Host/wwwroot/error.html`
+
+- [ ] **Step 1: Create static error.html**
+
+Create `template/SimpleModule.Host/wwwroot/error.html`:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="color-scheme" content="light dark" />
+    <title>Error - SimpleModule</title>
+    <style>
+        *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+        body {
+            font-family: 'DM Sans', system-ui, -apple-system, sans-serif;
+            min-height: 100vh;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            background: #fafafa;
+            color: #1a1a1a;
+            padding: 1rem;
+        }
+        @media (prefers-color-scheme: dark) {
+            body { background: #0a0a0a; color: #e5e5e5; }
+            .card { background: #171717; border-color: #262626; }
+            .code { color: rgba(229, 229, 229, 0.15); }
+            .btn-primary { background: #059669; }
+            .btn-secondary { background: #171717; border-color: #262626; color: #e5e5e5; }
+            .btn-secondary:hover { background: #262626; }
+        }
+        .container { text-align: center; max-width: 28rem; width: 100%; }
+        .code {
+            font-size: 8rem;
+            font-weight: 700;
+            line-height: 1;
+            color: rgba(0, 0, 0, 0.08);
+        }
+        .icon {
+            width: 3.5rem; height: 3.5rem;
+            margin: -1rem auto 1rem;
+            background: #fef2f2;
+            border-radius: 50%;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+        }
+        @media (prefers-color-scheme: dark) {
+            .icon { background: #450a0a; }
+            .icon svg { color: #fca5a5; }
+        }
+        .icon svg { width: 1.75rem; height: 1.75rem; color: #dc2626; }
+        h1 { font-size: 1.5rem; font-weight: 600; margin-bottom: 0.5rem; }
+        p { font-size: 0.875rem; color: #737373; line-height: 1.5; }
+        .actions { margin-top: 2rem; display: flex; gap: 0.75rem; justify-content: center; }
+        .btn {
+            display: inline-flex; align-items: center; justify-content: center;
+            padding: 0.5rem 1rem; border-radius: 0.5rem;
+            font-size: 0.875rem; font-weight: 500;
+            text-decoration: none; border: 1px solid transparent;
+            cursor: pointer;
+        }
+        .btn-primary { background: #059669; color: #fff; }
+        .btn-primary:hover { opacity: 0.9; }
+        .btn-secondary { background: #fff; border-color: #e5e5e5; color: #1a1a1a; }
+        .btn-secondary:hover { background: #f5f5f5; }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <p class="code">500</p>
+        <div class="icon">
+            <svg fill="none" stroke="currentColor" stroke-width="1.5" viewBox="0 0 24 24">
+                <path stroke-linecap="round" stroke-linejoin="round" d="M12 9v3.75m-9.303 3.376c-.866 1.5.217 3.374 1.948 3.374h14.71c1.73 0 2.813-1.874 1.948-3.374L13.949 3.378c-.866-1.5-3.032-1.5-3.898 0L2.697 16.126ZM12 15.75h.007v.008H12v-.008Z" />
+            </svg>
+        </div>
+        <h1>Something went wrong</h1>
+        <p>An unexpected error occurred. Please try again later.</p>
+        <div class="actions">
+            <a href="/" class="btn btn-primary">Go home</a>
+            <button type="button" onclick="history.back()" class="btn btn-secondary">Go back</button>
+        </div>
+    </div>
+</body>
+</html>
+```
+
+- [ ] **Step 2: Configure exception handler fallback to error.html**
+
+In `framework/SimpleModule.Hosting/SimpleModuleHostExtensions.cs`, replace the plain `app.UseExceptionHandler();` call (line 151) with:
+
+```csharp
+app.UseExceptionHandler(errorApp =>
+        {
+            errorApp.Run(async context =>
+            {
+                // If GlobalExceptionHandler already wrote the response, do nothing
+                if (context.Response.HasStarted)
+                    return;
+
+                // Fallback: serve static error.html for catastrophic failures
+                context.Response.StatusCode = StatusCodes.Status500InternalServerError;
+                context.Response.ContentType = "text/html";
+                var errorPage = Path.Combine(
+                    app.Environment.WebRootPath,
+                    "error.html"
+                );
+                if (File.Exists(errorPage))
+                {
+                    await context.Response.SendFileAsync(errorPage);
+                }
+                else
+                {
+                    await context.Response.WriteAsync(
+                        "<h1>500 Internal Server Error</h1>"
+                    );
+                }
+            });
+        });
+```
+
+- [ ] **Step 3: Build to verify**
+
+Run: `dotnet build framework/SimpleModule.Hosting/SimpleModule.Hosting.csproj`
+Expected: Build succeeds.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add template/SimpleModule.Host/wwwroot/error.html framework/SimpleModule.Hosting/SimpleModuleHostExtensions.cs
+git commit -m "feat: add static error.html fallback and configure exception handler"
+```
+
+---
+
+## Task 7: Build and Verify End-to-End
+
+- [ ] **Step 1: Run full backend build**
+
+Run: `dotnet build`
+Expected: Build succeeds with no errors or warnings.
+
+- [ ] **Step 2: Run all backend tests**
+
+Run: `dotnet test --filter "GlobalExceptionHandler" -v minimal`
+Expected: All tests pass.
+
+- [ ] **Step 3: Run frontend checks**
+
+Run: `npm run check`
+Expected: No lint or format errors.
+
+- [ ] **Step 4: Run frontend build**
+
+Run: `npm run build`
+Expected: Build succeeds. Error page components are bundled into ClientApp's `app.js`.
+
+- [ ] **Step 5: Commit any final fixes if needed**
+
+If any build/lint fixes were needed, commit them:
+
+```bash
+git add -A
+git commit -m "fix: resolve build/lint issues in error pages implementation"
+```
diff --git a/docs/superpowers/specs/2026-04-11-error-pages-design.md b/docs/superpowers/specs/2026-04-11-error-pages-design.md
new file mode 100644
index 00000000..610759bc
--- /dev/null
+++ b/docs/superpowers/specs/2026-04-11-error-pages-design.md
@@ -0,0 +1,122 @@
+# Error Page Templates (404/500/403)
+
+## Overview
+
+Add dedicated error page templates for 404, 500, and 403 errors with two layers: Inertia-rendered React pages for normal error scenarios, and a static HTML fallback for catastrophic failures.
+
+## Current State
+
+- `GlobalExceptionHandler` returns JSON `ProblemDetails` for all errors
+- `app.tsx` shows toast notifications for HTTP errors during Inertia navigation
+- `PageErrorBoundary` catches React rendering errors with a generic UI
+- No dedicated error pages exist — errors are either toasts or generic boundary UI
+- No `ForbiddenException` class exists (only `NotFoundException`, `ConflictException`, `ValidationException`)
+
+## Design
+
+### Layer 1: Inertia Error Pages (React)
+
+Three components in `@simplemodule/ui`:
+
+| Component | Status Code | When Shown |
+|-----------|------------|------------|
+| `ErrorPage404` | 404 | Route not found, `NotFoundException` |
+| `ErrorPage500` | 500 | Unhandled server exceptions |
+| `ErrorPage403` | 403 | Authorization failures, `ForbiddenException` |
+
+**Visual design:** Minimal standalone (no sidebar/header). Centered content with:
+- Large status code number (e.g., "404") in muted color
+- Icon from lucide-react (SearchX for 404, AlertTriangle for 500, ShieldX for 403)
+- Short heading ("Page not found", "Something went wrong", "Access denied")
+- Brief description text
+- "Go Home" button linking to `/`
+- "Go Back" button using `window.history.back()`
+- Uses existing Tailwind theme tokens (works with dark mode)
+
+**Location:** `packages/SimpleModule.UI/components/errors/`
+- `error-page-404.tsx`
+- `error-page-500.tsx`
+- `error-page-403.tsx`
+- `error-page-layout.tsx` — shared layout wrapper (centering, max-width, theme tokens)
+
+### Layer 2: Static HTML Fallback
+
+A single `error.html` in `template/SimpleModule.Host/wwwroot/` with:
+- Inline CSS only (no external dependencies)
+- Respects dark mode via `prefers-color-scheme` media query
+- Displays: status code, title, description, "Go Home" link
+- Status code/message injected via simple string replacement in middleware
+- Works when React/JS/Inertia all fail
+
+### Backend Changes
+
+#### 1. New `ForbiddenException` class
+
+`framework/SimpleModule.Core/Exceptions/ForbiddenException.cs`
+- Sealed class extending `Exception`
+- Same pattern as `NotFoundException`
+
+#### 2. Update `GlobalExceptionHandler`
+
+Add `ForbiddenException` → 403 mapping alongside existing exception mappings.
+
+For requests that accept HTML (non-API, non-XHR): render an Inertia error page instead of JSON. Decision logic:
+- If request has `X-Inertia` header or `Accept: text/html` → render Inertia error page
+- Otherwise → return JSON `ProblemDetails` (current behavior, unchanged)
+
+The Inertia error page rendering calls `Inertia.Render("Error/{StatusCode}", props)` where props include `status`, `title`, and `message`.
+
+#### 3. Error page endpoint
+
+Add a catch-all error endpoint in the framework (`SimpleModule.Hosting`) that:
+- Registers error page routes via `UseStatusCodePagesWithReExecute("/error/{0}")` 
+- Has an error controller/endpoint that renders the appropriate Inertia error page
+- Handles bare 404s from routing (no matching route) and 403s from authorization middleware
+
+#### 4. Update middleware pipeline
+
+In `SimpleModuleHostExtensions.UseSimpleModuleInfrastructure()`:
+- Add `UseStatusCodePagesWithReExecute("/error/{0}")` before `UseExceptionHandler()`
+- Configure `UseExceptionHandler` fallback to serve `error.html` when Inertia rendering fails
+
+### Frontend Changes
+
+#### 1. Error page components in `@simplemodule/ui`
+
+New exports from the UI package. Each component receives props: `{ status: number, title: string, message: string }`.
+
+#### 2. Host ClientApp registers error pages
+
+In `app.tsx`, the page resolver handles `Error/*` pages by importing from `@simplemodule/ui`:
+- `Error/404` → `ErrorPage404`
+- `Error/500` → `ErrorPage500`  
+- `Error/403` → `ErrorPage403`
+
+#### 3. Update `httpException` handler
+
+In `app.tsx`, the `router.on('httpException')` handler changes from toast to Inertia visit:
+- For 404/403/500: navigate to the error page via `router.visit` with error props
+- For other errors: keep toast behavior
+
+## File Changes Summary
+
+| File | Action |
+|------|--------|
+| `framework/SimpleModule.Core/Exceptions/ForbiddenException.cs` | Create |
+| `framework/SimpleModule.Core/Exceptions/GlobalExceptionHandler.cs` | Modify — add 403 mapping, Inertia error rendering |
+| `framework/SimpleModule.Core/Constants/ErrorMessages.cs` | Modify — add forbidden message constants |
+| `framework/SimpleModule.Hosting/SimpleModuleHostExtensions.cs` | Modify — add status code pages middleware, error endpoint |
+| `packages/SimpleModule.UI/components/errors/error-page-layout.tsx` | Create |
+| `packages/SimpleModule.UI/components/errors/error-page-404.tsx` | Create |
+| `packages/SimpleModule.UI/components/errors/error-page-500.tsx` | Create |
+| `packages/SimpleModule.UI/components/errors/error-page-403.tsx` | Create |
+| `packages/SimpleModule.UI/index.ts` | Modify — export error components |
+| `template/SimpleModule.Host/wwwroot/error.html` | Create |
+| `template/SimpleModule.Host/ClientApp/app.tsx` | Modify — register error pages, update httpException handler |
+
+## Out of Scope
+
+- Error logging/monitoring integration (Sentry, etc.)
+- Custom error pages per module
+- Retry logic for transient failures
+- Error analytics/tracking

From 32167ae8d74b90fb7c437db90de2f5c5519ddf0c Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Wed, 15 Apr 2026 13:10:35 +0200
Subject: [PATCH 09/10] fix: scope error page re-execute to browser GETs, not
 API requests

UseStatusCodePagesWithReExecute was re-executing POST/PATCH/PUT requests
that got bare 4xx responses from routing (e.g. auth 401/403, validation
failures) through /error/{statusCode}. Since the endpoint is MapGet-only,
non-GET methods returned 405 MethodNotAllowed instead of the original
status code. It also replaced JSON ProblemDetails with Inertia HTML for
API clients.

Scope the status code pages middleware to GET requests on non-service
paths (/api, /connect, /swagger, /health, /_framework, /_vite excluded).
Browser navigations still get the nice error page; API clients keep
their ProblemDetails body and bare status code.
---
 .../SimpleModuleHostExtensions.cs             | 36 ++++++++++++++++++-
 1 file changed, 35 insertions(+), 1 deletion(-)

diff --git a/framework/SimpleModule.Hosting/SimpleModuleHostExtensions.cs b/framework/SimpleModule.Hosting/SimpleModuleHostExtensions.cs
index 5cff884e..866db602 100644
--- a/framework/SimpleModule.Hosting/SimpleModuleHostExtensions.cs
+++ b/framework/SimpleModule.Hosting/SimpleModuleHostExtensions.cs
@@ -183,7 +183,16 @@ public static async Task UseSimpleModuleInfrastructure(this WebApplication app)
                 }
             });
         });
-        app.UseStatusCodePagesWithReExecute("/error/{0}");
+        // Status code pages render the Inertia error page for browser
+        // navigations (GET to non-API paths). API requests must keep their
+        // ProblemDetails body and bare status code — re-executing a POST to
+        // /error/{n} would return 405 from the GET error endpoint and replace
+        // JSON with HTML. /api, /connect, /swagger, /health are excluded.
+        app.UseWhen(
+            context =>
+                HttpMethods.IsGet(context.Request.Method) && !IsServiceRoute(context.Request.Path),
+            branch => branch.UseStatusCodePagesWithReExecute("/error/{0}")
+        );
 
         var options = app.Services.GetRequiredService<SimpleModuleOptions>();
         if (options.EnableSwagger && app.Environment.IsDevelopment())
@@ -398,6 +407,31 @@ private static void UseHomePageRewrite(WebApplication app)
         );
     }
 
+    private static readonly string[] ServiceRoutePrefixes =
+    [
+        "/api/",
+        "/connect/",
+        "/swagger",
+        "/health",
+        "/_framework/",
+        "/_vite/",
+    ];
+
+    private static bool IsServiceRoute(PathString path)
+    {
+        if (!path.HasValue)
+            return false;
+
+        var value = path.Value!;
+        foreach (var prefix in ServiceRoutePrefixes)
+        {
+            if (value.StartsWith(prefix, StringComparison.OrdinalIgnoreCase))
+                return true;
+        }
+
+        return false;
+    }
+
     private static async Task WriteHealthCheckResponse(
         HttpContext context,
         Microsoft.Extensions.Diagnostics.HealthChecks.HealthReport report

From fc1a091e254047c92fbbd81473b75ec3590b715c Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Wed, 15 Apr 2026 13:22:49 +0200
Subject: [PATCH 10/10] fix: use MapFallback for unmatched routes instead of
 status code pages
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

UseStatusCodePagesWithReExecute was too aggressive — it re-executed on
ANY bare 4xx status code, including auth 401/403 from matched endpoints.
This broke unauthenticated access tests that expected bare 401 responses
(they got HTML error pages or 404 instead).

MapFallback only fires when no endpoint matches the URL, so browser
navigation to non-existent URLs gets a pretty Inertia 404 page while
auth failures on real endpoints keep returning their bare status code.

Also extracts the error-page render logic into a shared RenderErrorPage
helper used by both /error/{statusCode} and the fallback.
---
 .../SimpleModuleHostExtensions.cs             | 93 +++++++------------
 1 file changed, 33 insertions(+), 60 deletions(-)

diff --git a/framework/SimpleModule.Hosting/SimpleModuleHostExtensions.cs b/framework/SimpleModule.Hosting/SimpleModuleHostExtensions.cs
index 866db602..a1914260 100644
--- a/framework/SimpleModule.Hosting/SimpleModuleHostExtensions.cs
+++ b/framework/SimpleModule.Hosting/SimpleModuleHostExtensions.cs
@@ -183,16 +183,6 @@ public static async Task UseSimpleModuleInfrastructure(this WebApplication app)
                 }
             });
         });
-        // Status code pages render the Inertia error page for browser
-        // navigations (GET to non-API paths). API requests must keep their
-        // ProblemDetails body and bare status code — re-executing a POST to
-        // /error/{n} would return 405 from the GET error endpoint and replace
-        // JSON with HTML. /api, /connect, /swagger, /health are excluded.
-        app.UseWhen(
-            context =>
-                HttpMethods.IsGet(context.Request.Method) && !IsServiceRoute(context.Request.Path),
-            branch => branch.UseStatusCodePagesWithReExecute("/error/{0}")
-        );
 
         var options = app.Services.GetRequiredService<SimpleModuleOptions>();
         if (options.EnableSwagger && app.Environment.IsDevelopment())
@@ -286,38 +276,46 @@ public static async Task UseSimpleModuleInfrastructure(this WebApplication app)
                 .AllowAnonymous();
         }
 
-        app.MapGet(
-                "/error/{statusCode:int}",
-                (int statusCode) =>
+        app.MapGet("/error/{statusCode:int}", (int statusCode) => RenderErrorPage(statusCode))
+            .AllowAnonymous()
+            .ExcludeFromDescription();
+
+        // Catch-all for unmatched GET requests — renders a 404 Inertia page
+        // for browser navigation to non-existent URLs. Does NOT fire on
+        // matched endpoints that return bare 401/403 from auth, so API tests
+        // that verify bare status codes remain unaffected.
+        app.MapFallback(
+                "{**catchAll}",
+                (HttpContext context) =>
                 {
-                    var (title, message) = statusCode switch
-                    {
-                        403 => (
-                            ErrorMessages.ForbiddenTitle,
-                            ErrorMessages.DefaultForbiddenMessage
-                        ),
-                        404 => (ErrorMessages.NotFoundTitle, ErrorMessages.DefaultNotFoundMessage),
-                        _ => (
-                            ErrorMessages.InternalServerErrorTitle,
-                            ErrorMessages.UnexpectedError
-                        ),
-                    };
-
-                    return SimpleModule.Core.Inertia.Inertia.Render(
-                        $"Error/{statusCode}",
-                        new
-                        {
-                            status = statusCode,
-                            title,
-                            message,
-                        }
-                    );
+                    context.Response.StatusCode = StatusCodes.Status404NotFound;
+                    return RenderErrorPage(404);
                 }
             )
             .AllowAnonymous()
             .ExcludeFromDescription();
     }
 
+    private static IResult RenderErrorPage(int statusCode)
+    {
+        var (title, message) = statusCode switch
+        {
+            403 => (ErrorMessages.ForbiddenTitle, ErrorMessages.DefaultForbiddenMessage),
+            404 => (ErrorMessages.NotFoundTitle, ErrorMessages.DefaultNotFoundMessage),
+            _ => (ErrorMessages.InternalServerErrorTitle, ErrorMessages.UnexpectedError),
+        };
+
+        return SimpleModule.Core.Inertia.Inertia.Render(
+            $"Error/{statusCode}",
+            new
+            {
+                status = statusCode,
+                title,
+                message,
+            }
+        );
+    }
+
     private static void BridgeAspireConnectionString(ConfigurationManager configuration)
     {
         var aspireConnectionString = configuration.GetConnectionString("simplemoduledb");
@@ -407,31 +405,6 @@ private static void UseHomePageRewrite(WebApplication app)
         );
     }
 
-    private static readonly string[] ServiceRoutePrefixes =
-    [
-        "/api/",
-        "/connect/",
-        "/swagger",
-        "/health",
-        "/_framework/",
-        "/_vite/",
-    ];
-
-    private static bool IsServiceRoute(PathString path)
-    {
-        if (!path.HasValue)
-            return false;
-
-        var value = path.Value!;
-        foreach (var prefix in ServiceRoutePrefixes)
-        {
-            if (value.StartsWith(prefix, StringComparison.OrdinalIgnoreCase))
-                return true;
-        }
-
-        return false;
-    }
-
     private static async Task WriteHealthCheckResponse(
         HttpContext context,
         Microsoft.Extensions.Diagnostics.HealthChecks.HealthReport report