From 9efbe38c0c5c1c80f98d974d72cc6431b68fcd8f Mon Sep 17 00:00:00 2001
From: Relism <itzdrekkopvp@gmail.com>
Date: Fri, 17 Apr 2026 08:18:11 +0200
Subject: [PATCH] weeks of bullshit

---
 .idea/copilot.data.migration.agent.xml        |   6 +
 .idea/copilot.data.migration.ask.xml          |   6 +
 .idea/copilot.data.migration.edit.xml         |   6 +
 .idea/encodings.xml                           |   2 +
 .idea/workspace.xml                           | 275 +++++++-------
 flash-extensions/flash-ext-jackson/README.md  |  12 +-
 .../relism/ext/jackson/JacksonExtension.java  |  20 +-
 .../java/dev/relism/ext/jackson/Json.java     |  13 +-
 .../java/dev/relism/ext/limiter/Bucket.java   |   2 +
 .../java/dev/relism/ext/limiter/Guard.java    |  12 +-
 .../dev/relism/ext/limiter/LimitStrategy.java |  13 +
 .../relism/ext/limiter/LimiterExtension.java  |  43 ++-
 .../relism/ext/limiter/RateLimitStrategy.java |   1 +
 .../strategy/SlidingWindowStrategy.java       |  86 +++++
 .../limiter/strategy/TokenBucketStrategy.java |   9 +-
 flash-extensions/flash-ext-oidc/README.md     | 154 ++++++--
 .../dev/relism/ext/oidc/OidcAuthPolicy.java   |  98 +++++
 .../java/dev/relism/ext/oidc/OidcConfig.java  |  11 +
 .../dev/relism/ext/oidc/OidcExtension.java    | 159 +++-----
 .../dev/relism/ext/oidc/OidcMiddleware.java   | 298 +++++++++++++--
 .../java/dev/relism/ext/oidc/OidcUser.java    | 133 ++++++-
 .../dev/relism/ext/oidc/ScopesAllowed.java    |  45 +++
 .../relism/ext/oidc/OidcAuthPolicyTest.java   |  94 +++++
 .../ext/oidc/OidcMiddlewareAuthzTest.java     |  72 ++++
 .../relism/ext/oidc/OidcUserScopesTest.java   |  47 +++
 flash-extensions/flash-ext-openapi/README.md  |   9 +-
 flash-extensions/flash-ext-openapi/pom.xml    |   2 +-
 .../dev/relism/ext/openapi/ApiOperation.java  |   2 +-
 .../dev/relism/ext/openapi/ApiResponse.java   |   1 +
 .../dev/relism/ext/openapi/ArraySchema.java   |  16 +
 .../relism/ext/openapi/OpenApiBuilder.java    | 350 ++++++++++++++----
 .../relism/ext/openapi/OpenApiExtension.java  |  96 +++--
 .../java/dev/relism/ext/openapi/Schema.java   |  19 +
 .../relism/ext/openapi/SchemaProperty.java    |  19 +
 .../routeviewer/RouteViewerDataHandler.java   |   2 +-
 .../ext/routeviewer/RouteViewerExtension.java |  41 +-
 .../ext/routeviewer/RouteViewerHandler.java   |   2 +-
 .../routeviewer/RouteViewerStaticHandler.java |   6 +-
 .../relism/ext/view/EngineCapabilities.java   |   5 +
 .../ext/view/LegacyViewEngineAdapter.java     |  38 ++
 .../main/java/dev/relism/ext/view/Page.java   |  12 +
 .../java/dev/relism/ext/view/Partial.java     |  13 +
 .../dev/relism/ext/view/RenderOutput.java     |   9 +
 .../java/dev/relism/ext/view/Renderer.java    |   2 +-
 .../dev/relism/ext/view/ThymeleafEngine.java  |  23 +-
 .../relism/ext/view/ViewEngineAdapter.java    |  11 +
 .../dev/relism/ext/view/ViewEngineType.java   |  10 +-
 .../dev/relism/ext/view/ViewExtension.java    | 179 +++------
 .../java/dev/relism/ext/view/ViewGlobals.java |   8 +
 .../java/dev/relism/ext/view/ViewHandler.java |  32 ++
 .../java/dev/relism/ext/view/ViewKind.java    |   6 +
 .../java/dev/relism/ext/view/ViewModel.java   |  71 ++++
 .../java/dev/relism/ext/view/ViewRuntime.java |  79 ++++
 .../java/dev/relism/ext/view/ViewTarget.java  |   7 +
 .../relism/ext/view/ViewTargetResolver.java   |  62 ++++
 .../dev/relism/ext/view/ViewModelTest.java    |  56 +++
 .../ext/view/ViewRuntimeGlobalsTest.java      |  48 +++
 .../ext/view/ViewTargetResolverTest.java      |  95 +++++
 .../flash-web-bundler/docs/README.md          |  24 ++
 .../flash-web-bundler/docs/asset-sources.md   |  22 ++
 .../flash-web-bundler/docs/configuration.md   |  30 ++
 .../flash-web-bundler/docs/dev-lifecycle.md   |  16 +
 .../docs/frontend-selection.md                |  12 +
 .../flash-web-bundler/docs/modes.md           |  12 +
 .../docs/package-managers.md                  |  19 +
 .../flash-web-bundler/docs/performance.md     |  13 +
 .../flash-web-bundler/docs/prod-serving.md    |  17 +
 .../docs/routing-fallback.md                  |  10 +
 .../docs/security-policies.md                 |  11 +
 flash-extensions/flash-web-bundler/pom.xml    |  37 ++
 .../relism/ext/webbundler/AssetCatalog.java   |  33 ++
 .../dev/relism/ext/webbundler/AssetEntry.java |  11 +
 .../dev/relism/ext/webbundler/AssetIo.java    |  93 +++++
 .../ext/webbundler/AssetLoadRequest.java      |  12 +
 .../relism/ext/webbundler/AssetMetadata.java  |  16 +
 .../dev/relism/ext/webbundler/AssetPaths.java |  26 ++
 .../relism/ext/webbundler/AssetsSource.java   |   5 +
 .../relism/ext/webbundler/AssetsSources.java  |  16 +
 .../webbundler/BasePathEnforcementMode.java   |   6 +
 .../webbundler/ClasspathAssetManifest.java    |  16 +
 .../ext/webbundler/ClasspathAssetsSource.java |  91 +++++
 .../ext/webbundler/CommandOrchestrator.java   | 187 ++++++++++
 .../ext/webbundler/CommandSafetyMode.java     |   7 +
 .../ext/webbundler/CommandSafetyPolicy.java   |  27 ++
 .../relism/ext/webbundler/CommandTokens.java  |  14 +
 .../webbundler/FilesystemAssetsSource.java    |  72 ++++
 .../ext/webbundler/FrontendStrategy.java      |  12 +
 .../relism/ext/webbundler/FrontendType.java   |   5 +
 .../ext/webbundler/FrontendTypeResolver.java  |  24 ++
 .../relism/ext/webbundler/InstallCache.java   |  57 +++
 .../relism/ext/webbundler/InstallPolicy.java  |   6 +
 .../relism/ext/webbundler/LoggingMode.java    |   8 +
 .../dev/relism/ext/webbundler/MimeTypes.java  |  30 ++
 .../relism/ext/webbundler/ModeResolver.java   |  19 +
 .../relism/ext/webbundler/OperationMode.java  |   6 +
 .../relism/ext/webbundler/PackageManager.java |  24 ++
 .../ext/webbundler/PackageManagerAdapter.java |  44 +++
 .../ext/webbundler/RuntimeEnvironment.java    |   6 +
 .../relism/ext/webbundler/RuntimeMode.java    |   7 +
 .../ext/webbundler/SpaFallbackPolicy.java     |  17 +
 .../webbundler/StaticAssetServingPolicy.java  |  46 +++
 .../ext/webbundler/ViteFrontendStrategy.java  |  26 ++
 .../dev/relism/ext/webbundler/WatchList.java  |  43 +++
 .../ext/webbundler/WebBundlerConfig.java      | 210 +++++++++++
 .../ext/webbundler/WebBundlerExtension.java   | 163 ++++++++
 .../ext/webbundler/WebBundlerRuntime.java     |  29 ++
 .../ext/webbundler/AssetsSourceTest.java      |  39 ++
 .../webbundler/CommandSafetyPolicyTest.java   |  30 ++
 .../ext/webbundler/InstallCacheTest.java      |  29 ++
 .../ext/webbundler/ModeResolverTest.java      |  17 +
 .../webbundler/PackageManagerAdapterTest.java |  18 +
 .../ext/webbundler/WebBundlerConfigTest.java  |  58 +++
 .../WebBundlerExtensionDevGuardTest.java      |  16 +
 .../WebBundlerExtensionIntegrationTest.java   |  80 ++++
 flash-extensions/pom.xml                      |   6 +
 flash/pom.xml                                 |   1 +
 .../java/dev/relism/ChunkedInputStream.java   |  17 +-
 flash/src/main/java/dev/relism/Flash.java     |  36 +-
 .../src/main/java/dev/relism/HttpServer.java  | 158 ++++----
 .../main/java/dev/relism/ServerHandle.java    |  11 +-
 .../relism/extension/AnnotationProcessor.java |   4 +-
 .../dev/relism/extension/ExtensionPhase.java  |  32 ++
 .../java/dev/relism/extension/FlashApp.java   | 266 ++++++-------
 .../dev/relism/extension/FlashContext.java    | 171 ++++++---
 .../dev/relism/extension/FlashExtension.java  |  78 +++-
 .../dev/relism/extension/FlashRegistrar.java  | 115 ++++--
 .../java/dev/relism/extension/FlashScope.java | 121 +-----
 .../dev/relism/extension/PackageScanner.java  |  17 +-
 .../dev/relism/extension/RouteDefinition.java |   8 +-
 .../java/dev/relism/extension/RouteEvent.java |   4 +-
 .../java/dev/relism/models/HeaderMap.java     |  24 +-
 .../java/dev/relism/models/PathParams.java    |   9 +
 .../main/java/dev/relism/models/Request.java  |  22 +-
 .../java/dev/relism/models/RequestBody.java   |  17 +-
 .../dev/relism/models/RequestHandler.java     |  13 +-
 .../main/java/dev/relism/models/Response.java |  29 +-
 .../java/dev/relism/models/SimpleHandler.java |  11 +-
 .../dev/relism/routing/AbstractRouter.java    |  51 ++-
 .../main/java/dev/relism/routing/CONNECT.java |  16 +
 .../main/java/dev/relism/routing/DELETE.java  |  16 +
 .../src/main/java/dev/relism/routing/GET.java |  16 +
 .../main/java/dev/relism/routing/HEAD.java    |  16 +
 .../java/dev/relism/routing/Middleware.java   |  15 +-
 .../main/java/dev/relism/routing/OPTIONS.java |  16 +
 .../main/java/dev/relism/routing/PATCH.java   |  16 +
 .../main/java/dev/relism/routing/POST.java    |  16 +
 .../main/java/dev/relism/routing/PURGE.java   |  16 +
 .../src/main/java/dev/relism/routing/PUT.java |  16 +
 .../main/java/dev/relism/routing/Route.java   |  14 +-
 .../java/dev/relism/routing/RouteHandle.java  |  70 ----
 .../main/java/dev/relism/routing/Routes.java  |  34 ++
 .../main/java/dev/relism/routing/TRACE.java   |  16 +
 .../dev/relism/HttpServerConcurrencyTest.java |   4 +-
 .../test/java/dev/relism/HttpServerTest.java  |  20 +-
 .../java/dev/relism/models/ResponseTest.java  |  19 +-
 .../relism/routing/AbstractRouterTest.java    |   3 +-
 pom.xml                                       |  12 +
 157 files changed, 5171 insertions(+), 1273 deletions(-)
 create mode 100644 .idea/copilot.data.migration.agent.xml
 create mode 100644 .idea/copilot.data.migration.ask.xml
 create mode 100644 .idea/copilot.data.migration.edit.xml
 create mode 100644 flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/strategy/SlidingWindowStrategy.java
 create mode 100644 flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcAuthPolicy.java
 create mode 100644 flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/ScopesAllowed.java
 create mode 100644 flash-extensions/flash-ext-oidc/src/test/java/dev/relism/ext/oidc/OidcAuthPolicyTest.java
 create mode 100644 flash-extensions/flash-ext-oidc/src/test/java/dev/relism/ext/oidc/OidcMiddlewareAuthzTest.java
 create mode 100644 flash-extensions/flash-ext-oidc/src/test/java/dev/relism/ext/oidc/OidcUserScopesTest.java
 create mode 100644 flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ArraySchema.java
 create mode 100644 flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/Schema.java
 create mode 100644 flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/SchemaProperty.java
 create mode 100644 flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/EngineCapabilities.java
 create mode 100644 flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/LegacyViewEngineAdapter.java
 create mode 100644 flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/Page.java
 create mode 100644 flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/Partial.java
 create mode 100644 flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/RenderOutput.java
 create mode 100644 flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewEngineAdapter.java
 create mode 100644 flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewGlobals.java
 create mode 100644 flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewHandler.java
 create mode 100644 flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewKind.java
 create mode 100644 flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewModel.java
 create mode 100644 flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewRuntime.java
 create mode 100644 flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewTarget.java
 create mode 100644 flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewTargetResolver.java
 create mode 100644 flash-extensions/flash-ext-view/src/test/java/dev/relism/ext/view/ViewModelTest.java
 create mode 100644 flash-extensions/flash-ext-view/src/test/java/dev/relism/ext/view/ViewRuntimeGlobalsTest.java
 create mode 100644 flash-extensions/flash-ext-view/src/test/java/dev/relism/ext/view/ViewTargetResolverTest.java
 create mode 100644 flash-extensions/flash-web-bundler/docs/README.md
 create mode 100644 flash-extensions/flash-web-bundler/docs/asset-sources.md
 create mode 100644 flash-extensions/flash-web-bundler/docs/configuration.md
 create mode 100644 flash-extensions/flash-web-bundler/docs/dev-lifecycle.md
 create mode 100644 flash-extensions/flash-web-bundler/docs/frontend-selection.md
 create mode 100644 flash-extensions/flash-web-bundler/docs/modes.md
 create mode 100644 flash-extensions/flash-web-bundler/docs/package-managers.md
 create mode 100644 flash-extensions/flash-web-bundler/docs/performance.md
 create mode 100644 flash-extensions/flash-web-bundler/docs/prod-serving.md
 create mode 100644 flash-extensions/flash-web-bundler/docs/routing-fallback.md
 create mode 100644 flash-extensions/flash-web-bundler/docs/security-policies.md
 create mode 100644 flash-extensions/flash-web-bundler/pom.xml
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/AssetCatalog.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/AssetEntry.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/AssetIo.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/AssetLoadRequest.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/AssetMetadata.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/AssetPaths.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/AssetsSource.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/AssetsSources.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/BasePathEnforcementMode.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/ClasspathAssetManifest.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/ClasspathAssetsSource.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/CommandOrchestrator.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/CommandSafetyMode.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/CommandSafetyPolicy.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/CommandTokens.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/FilesystemAssetsSource.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/FrontendStrategy.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/FrontendType.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/FrontendTypeResolver.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/InstallCache.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/InstallPolicy.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/LoggingMode.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/MimeTypes.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/ModeResolver.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/OperationMode.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/PackageManager.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/PackageManagerAdapter.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/RuntimeEnvironment.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/RuntimeMode.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/SpaFallbackPolicy.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/StaticAssetServingPolicy.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/ViteFrontendStrategy.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/WatchList.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/WebBundlerConfig.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/WebBundlerExtension.java
 create mode 100644 flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/WebBundlerRuntime.java
 create mode 100644 flash-extensions/flash-web-bundler/src/test/java/dev/relism/ext/webbundler/AssetsSourceTest.java
 create mode 100644 flash-extensions/flash-web-bundler/src/test/java/dev/relism/ext/webbundler/CommandSafetyPolicyTest.java
 create mode 100644 flash-extensions/flash-web-bundler/src/test/java/dev/relism/ext/webbundler/InstallCacheTest.java
 create mode 100644 flash-extensions/flash-web-bundler/src/test/java/dev/relism/ext/webbundler/ModeResolverTest.java
 create mode 100644 flash-extensions/flash-web-bundler/src/test/java/dev/relism/ext/webbundler/PackageManagerAdapterTest.java
 create mode 100644 flash-extensions/flash-web-bundler/src/test/java/dev/relism/ext/webbundler/WebBundlerConfigTest.java
 create mode 100644 flash-extensions/flash-web-bundler/src/test/java/dev/relism/ext/webbundler/WebBundlerExtensionDevGuardTest.java
 create mode 100644 flash-extensions/flash-web-bundler/src/test/java/dev/relism/ext/webbundler/WebBundlerExtensionIntegrationTest.java
 create mode 100644 flash/src/main/java/dev/relism/extension/ExtensionPhase.java
 create mode 100644 flash/src/main/java/dev/relism/routing/CONNECT.java
 create mode 100644 flash/src/main/java/dev/relism/routing/DELETE.java
 create mode 100644 flash/src/main/java/dev/relism/routing/GET.java
 create mode 100644 flash/src/main/java/dev/relism/routing/HEAD.java
 create mode 100644 flash/src/main/java/dev/relism/routing/OPTIONS.java
 create mode 100644 flash/src/main/java/dev/relism/routing/PATCH.java
 create mode 100644 flash/src/main/java/dev/relism/routing/POST.java
 create mode 100644 flash/src/main/java/dev/relism/routing/PURGE.java
 create mode 100644 flash/src/main/java/dev/relism/routing/PUT.java
 delete mode 100644 flash/src/main/java/dev/relism/routing/RouteHandle.java
 create mode 100644 flash/src/main/java/dev/relism/routing/Routes.java
 create mode 100644 flash/src/main/java/dev/relism/routing/TRACE.java

diff --git a/.idea/copilot.data.migration.agent.xml b/.idea/copilot.data.migration.agent.xml
new file mode 100644
index 0000000..4ea72a9
--- /dev/null
+++ b/.idea/copilot.data.migration.agent.xml
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="AgentMigrationStateService">
+    <option name="migrationStatus" value="COMPLETED" />
+  </component>
+</project>
\ No newline at end of file
diff --git a/.idea/copilot.data.migration.ask.xml b/.idea/copilot.data.migration.ask.xml
new file mode 100644
index 0000000..7ef04e2
--- /dev/null
+++ b/.idea/copilot.data.migration.ask.xml
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="AskMigrationStateService">
+    <option name="migrationStatus" value="COMPLETED" />
+  </component>
+</project>
\ No newline at end of file
diff --git a/.idea/copilot.data.migration.edit.xml b/.idea/copilot.data.migration.edit.xml
new file mode 100644
index 0000000..8648f94
--- /dev/null
+++ b/.idea/copilot.data.migration.edit.xml
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="EditMigrationStateService">
+    <option name="migrationStatus" value="COMPLETED" />
+  </component>
+</project>
\ No newline at end of file
diff --git a/.idea/encodings.xml b/.idea/encodings.xml
index 976757e..420c512 100644
--- a/.idea/encodings.xml
+++ b/.idea/encodings.xml
@@ -17,6 +17,8 @@
     <file url="file://$PROJECT_DIR$/flash-extensions/flash-ext-routeviewer/src/main/resources" charset="UTF-8" />
     <file url="file://$PROJECT_DIR$/flash-extensions/flash-ext-view/src/main/java" charset="UTF-8" />
     <file url="file://$PROJECT_DIR$/flash-extensions/flash-ext-view/src/main/resources" charset="UTF-8" />
+    <file url="file://$PROJECT_DIR$/flash-extensions/flash-web-bundler/src/main/java" charset="UTF-8" />
+    <file url="file://$PROJECT_DIR$/flash-extensions/flash-web-bundler/src/main/resources" charset="UTF-8" />
     <file url="file://$PROJECT_DIR$/flash-extensions/src/main/java" charset="UTF-8" />
     <file url="file://$PROJECT_DIR$/flash-extensions/src/main/resources" charset="UTF-8" />
     <file url="file://$PROJECT_DIR$/flash/src/main/java" charset="UTF-8" />
diff --git a/.idea/workspace.xml b/.idea/workspace.xml
index 29eb7ad..c3a99ac 100644
--- a/.idea/workspace.xml
+++ b/.idea/workspace.xml
@@ -4,76 +4,65 @@
     <option name="autoReloadType" value="SELECTIVE" />
   </component>
   <component name="ChangeListManager">
-    <list default="true" id="fc757130-fe3e-4ea9-8d69-c26ffb8545a4" name="Changes" comment="preparing for a conceptual refactoring...">
-      <change afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-jackson/src/main/java/dev/relism/ext/jackson/Json.java" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-limiter/docs/README.md" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-limiter/docs/annotation.md" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-limiter/docs/guard.md" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-limiter/docs/http-headers.md" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-limiter/docs/key-resolvers.md" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-limiter/docs/strategies.md" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-limiter/pom.xml" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/Bucket.java" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/BucketStore.java" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/Guard.java" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/KeyResolver.java" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/Limit.java" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/LimitConfig.java" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/LimitStrategy.java" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/LimiterConfig.java" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/LimiterExtension.java" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/RateLimitStrategy.java" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/strategy/FixedWindowStrategy.java" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/strategy/TokenBucketStrategy.java" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-routeviewer/routeviewer-ui/pnpm-lock.yaml" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-view/pom.xml" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/Renderer.java" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/Template.java" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ThymeleafEngine.java" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/View.java" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewEngine.java" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewEngineType.java" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewExtension.java" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/exceptions/InitializationException.java" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/extension/FlashContext.java" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/extension/RouteDefinition.java" afterDir="false" />
+    <list default="true" id="fc757130-fe3e-4ea9-8d69-c26ffb8545a4" name="Changes" comment="preparing for another refactoring...">
       <change beforePath="$PROJECT_DIR$/.idea/encodings.xml" beforeDir="false" afterPath="$PROJECT_DIR$/.idea/encodings.xml" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/.idea/workspace.xml" beforeDir="false" afterPath="$PROJECT_DIR$/.idea/workspace.xml" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/README.md" beforeDir="false" afterPath="$PROJECT_DIR$/README.md" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/.idea/workspace.xml" beforeDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash-extensions/flash-ext-jackson/README.md" beforeDir="false" afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-jackson/README.md" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/flash-extensions/flash-ext-jackson/src/main/java/dev/relism/ext/jackson/JacksonExtension.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-jackson/src/main/java/dev/relism/ext/jackson/JacksonExtension.java" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/flash-extensions/flash-ext-jackson/src/main/java/dev/relism/ext/jackson/JacksonHandler.java" beforeDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash-extensions/flash-ext-jackson/src/main/java/dev/relism/ext/jackson/Json.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-jackson/src/main/java/dev/relism/ext/jackson/Json.java" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/Bucket.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/Bucket.java" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/Guard.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/Guard.java" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/LimitStrategy.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/LimitStrategy.java" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/LimiterExtension.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/LimiterExtension.java" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/RateLimitStrategy.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/RateLimitStrategy.java" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/strategy/TokenBucketStrategy.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/strategy/TokenBucketStrategy.java" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash-extensions/flash-ext-oidc/README.md" beforeDir="false" afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-oidc/README.md" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcConfig.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcConfig.java" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcExtension.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcExtension.java" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcMiddleware.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcMiddleware.java" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcUser.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcUser.java" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/flash-extensions/flash-ext-openapi/README.md" beforeDir="false" afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-openapi/README.md" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash-extensions/flash-ext-openapi/pom.xml" beforeDir="false" afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-openapi/pom.xml" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiOperation.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiOperation.java" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiResponse.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiResponse.java" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiBuilder.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiBuilder.java" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiExtension.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiExtension.java" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiSecurityContributor.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiSecurityContributor.java" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiSecurityRegistry.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiSecurityRegistry.java" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/flash-extensions/flash-ext-routeviewer/routeviewer-ui/src/layout.js" beforeDir="false" afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-routeviewer/routeviewer-ui/src/layout.js" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/flash-extensions/flash-ext-routeviewer/routeviewer-ui/src/nodes/HandlerNode.jsx" beforeDir="false" afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-routeviewer/routeviewer-ui/src/nodes/HandlerNode.jsx" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash-extensions/flash-ext-routeviewer/src/main/java/dev/relism/ext/routeviewer/RouteViewerDataHandler.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-routeviewer/src/main/java/dev/relism/ext/routeviewer/RouteViewerDataHandler.java" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/flash-extensions/flash-ext-routeviewer/src/main/java/dev/relism/ext/routeviewer/RouteViewerExtension.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-routeviewer/src/main/java/dev/relism/ext/routeviewer/RouteViewerExtension.java" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/flash-extensions/flash-ext-routeviewer/src/main/java/dev/relism/ext/routeviewer/model/RouteRecord.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-routeviewer/src/main/java/dev/relism/ext/routeviewer/model/RouteRecord.java" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/flash-extensions/flash-ext-routeviewer/src/main/resources/routeviewer/app.js" beforeDir="false" afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-routeviewer/src/main/resources/routeviewer/app.js" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash-extensions/flash-ext-routeviewer/src/main/java/dev/relism/ext/routeviewer/RouteViewerHandler.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-routeviewer/src/main/java/dev/relism/ext/routeviewer/RouteViewerHandler.java" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash-extensions/flash-ext-routeviewer/src/main/java/dev/relism/ext/routeviewer/RouteViewerStaticHandler.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-routeviewer/src/main/java/dev/relism/ext/routeviewer/RouteViewerStaticHandler.java" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/Renderer.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/Renderer.java" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewExtension.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewExtension.java" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/flash-extensions/pom.xml" beforeDir="false" afterPath="$PROJECT_DIR$/flash-extensions/pom.xml" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash/pom.xml" beforeDir="false" afterPath="$PROJECT_DIR$/flash/pom.xml" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/ChunkedInputStream.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/ChunkedInputStream.java" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/Flash.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/Flash.java" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/HttpServer.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/HttpServer.java" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/RequestParser.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/RequestParser.java" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/ServerHandle.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/ServerHandle.java" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/exceptions/DuplicateNamespaceException.java" beforeDir="false" />
       <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/extension/AnnotationProcessor.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/extension/AnnotationProcessor.java" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/extension/ExtensionContext.java" beforeDir="false" />
       <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/extension/FlashApp.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/extension/FlashApp.java" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/extension/FlashContext.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/extension/FlashContext.java" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/extension/FlashExtension.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/extension/FlashExtension.java" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/extension/FlashRegistrar.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/extension/FlashRegistrar.java" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/extension/FlashScope.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/extension/FlashScope.java" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/extension/PackageScanner.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/extension/PackageScanner.java" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/extension/RouteListener.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/extension/RouteListener.java" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/extension/RouteDefinition.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/extension/RouteDefinition.java" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/extension/RouteEvent.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/extension/RouteEvent.java" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/models/HeaderMap.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/models/HeaderMap.java" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/models/PathParams.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/models/PathParams.java" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/models/Request.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/models/Request.java" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/models/RequestBody.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/models/RequestBody.java" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/models/RequestHandler.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/models/RequestHandler.java" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/models/Response.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/models/Response.java" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/models/SimpleHandler.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/models/SimpleHandler.java" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/routing/AbstractRouter.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/routing/AbstractRouter.java" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/routing/GlobalRouter.java" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/routing/routers/fastpathrouter/FastPathRouterImpl.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/routing/routers/fastpathrouter/FastPathRouterImpl.java" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/routing/Middleware.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/routing/Middleware.java" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/routing/Route.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/routing/Route.java" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/routing/RouteHandle.java" beforeDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash/src/test/java/dev/relism/HttpServerConcurrencyTest.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/test/java/dev/relism/HttpServerConcurrencyTest.java" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash/src/test/java/dev/relism/HttpServerTest.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/test/java/dev/relism/HttpServerTest.java" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash/src/test/java/dev/relism/models/ResponseTest.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/test/java/dev/relism/models/ResponseTest.java" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/flash/src/test/java/dev/relism/routing/AbstractRouterTest.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/test/java/dev/relism/routing/AbstractRouterTest.java" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/flash/src/test/java/dev/relism/routing/GlobalRouterTest.java" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/flash/src/test/java/dev/relism/routing/routers/fastpathrouter/FastPathRouterImplTest.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/test/java/dev/relism/routing/routers/fastpathrouter/FastPathRouterImplTest.java" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/pom.xml" beforeDir="false" afterPath="$PROJECT_DIR$/pom.xml" afterDir="false" />
     </list>
     <option name="SHOW_DIALOG" value="false" />
@@ -88,7 +77,7 @@
     </persistenceIdMap>
   </component>
   <component name="EmbeddingIndexingInfo">
-    <option name="cachedIndexableFilesCount" value="226" />
+    <option name="cachedIndexableFilesCount" value="287" />
     <option name="fileBasedEmbeddingIndicesEnabled" value="true" />
   </component>
   <component name="FileTemplateManagerImpl">
@@ -127,52 +116,57 @@
     <option name="hideEmptyMiddlePackages" value="true" />
     <option name="showLibraryContents" value="true" />
   </component>
-  <component name="PropertiesComponent">{
-  &quot;keyToString&quot;: {
-    &quot;Application.ExternalBenchmark (1).executor&quot;: &quot;Run&quot;,
-    &quot;Application.ExternalBenchmark.executor&quot;: &quot;Run&quot;,
-    &quot;Application.Main.executor&quot;: &quot;Run&quot;,
-    &quot;Application.dev.relism.bench.Main.executor&quot;: &quot;Run&quot;,
-    &quot;JUnit.RequestParserTest.executor&quot;: &quot;Run&quot;,
-    &quot;JUnit.RequestParserTest.headers_caseInsensitive.executor&quot;: &quot;Debug&quot;,
-    &quot;Maven.FlashPractice [test].executor&quot;: &quot;Run&quot;,
-    &quot;Maven.flash [compile].executor&quot;: &quot;Run&quot;,
-    &quot;Maven.flash [install].executor&quot;: &quot;Run&quot;,
-    &quot;Maven.flash [test].executor&quot;: &quot;Run&quot;,
-    &quot;Maven.flash-bench [clean].executor&quot;: &quot;Run&quot;,
-    &quot;Maven.flash-bench [install].executor&quot;: &quot;Run&quot;,
-    &quot;Maven.flash-bench [package].executor&quot;: &quot;Run&quot;,
-    &quot;Maven.flash-bench [validate].executor&quot;: &quot;Run&quot;,
-    &quot;Maven.flash-ext-limiter [install].executor&quot;: &quot;Run&quot;,
-    &quot;Maven.flash-ext-limiter [package].executor&quot;: &quot;Run&quot;,
-    &quot;Maven.flash-parent [install].executor&quot;: &quot;Run&quot;,
-    &quot;Maven.flash-parent [package].executor&quot;: &quot;Run&quot;,
-    &quot;ModuleVcsDetector.initialDetectionPerformed&quot;: &quot;true&quot;,
-    &quot;RunOnceActivity.MCP Project settings loaded&quot;: &quot;true&quot;,
-    &quot;RunOnceActivity.ShowReadmeOnStart&quot;: &quot;true&quot;,
-    &quot;RunOnceActivity.TerminalTabsStorage.copyFrom.TerminalArrangementManager.252&quot;: &quot;true&quot;,
-    &quot;RunOnceActivity.git.unshallow&quot;: &quot;true&quot;,
-    &quot;RunOnceActivity.typescript.service.memoryLimit.init&quot;: &quot;true&quot;,
-    &quot;SHARE_PROJECT_CONFIGURATION_FILES&quot;: &quot;true&quot;,
-    &quot;git-widget-placeholder&quot;: &quot;master&quot;,
-    &quot;ignore.virus.scanning.warn.message&quot;: &quot;true&quot;,
-    &quot;kotlin-language-version-configured&quot;: &quot;true&quot;,
-    &quot;last_opened_file_path&quot;: &quot;C:/Users/elorc/Documents/Coding/Java/practice/Flash&quot;,
-    &quot;node.js.detected.package.eslint&quot;: &quot;true&quot;,
-    &quot;node.js.detected.package.tslint&quot;: &quot;true&quot;,
-    &quot;node.js.selected.package.eslint&quot;: &quot;(autodetect)&quot;,
-    &quot;node.js.selected.package.tslint&quot;: &quot;(autodetect)&quot;,
-    &quot;nodejs_package_manager_path&quot;: &quot;npm&quot;,
-    &quot;npm.build.executor&quot;: &quot;Run&quot;,
-    &quot;onboarding.tips.debug.path&quot;: &quot;C:/Users/elorc/Documents/Coding/Java/practice/FlashPractice/flash-bench/src/main/java/dev/relism/Main.java&quot;,
-    &quot;project.structure.last.edited&quot;: &quot;Modules&quot;,
-    &quot;project.structure.proportion&quot;: &quot;0.15&quot;,
-    &quot;project.structure.side.proportion&quot;: &quot;0.1150748&quot;,
-    &quot;settings.editor.selected.configurable&quot;: &quot;project.propVCSSupport.DirectoryMappings&quot;,
-    &quot;ts.external.directory.path&quot;: &quot;C:\\Users\\elorc\\Documents\\Coding\\Java\\practice\\Flash\\nuxt-shadcn-dashboard\\node_modules\\typescript\\lib&quot;,
-    &quot;vue.rearranger.settings.migration&quot;: &quot;true&quot;
+  <component name="PropertiesComponent"><![CDATA[{
+  "keyToString": {
+    "Application.(dev) flash-bench.executor": "Run",
+    "Application.ExternalBenchmark (1).executor": "Run",
+    "Application.ExternalBenchmark.executor": "Run",
+    "Application.Main.executor": "Run",
+    "Application.MainAlt.executor": "Run",
+    "Application.dev.relism.bench.Main.executor": "Run",
+    "JUnit.RequestParserTest.executor": "Run",
+    "JUnit.RequestParserTest.headers_caseInsensitive.executor": "Debug",
+    "Maven.FlashPractice [test].executor": "Run",
+    "Maven.flash [compile].executor": "Run",
+    "Maven.flash [install].executor": "Run",
+    "Maven.flash [test].executor": "Run",
+    "Maven.flash-bench [clean].executor": "Run",
+    "Maven.flash-bench [install].executor": "Run",
+    "Maven.flash-bench [package].executor": "Run",
+    "Maven.flash-bench [validate].executor": "Run",
+    "Maven.flash-ext-limiter [install].executor": "Run",
+    "Maven.flash-ext-limiter [package].executor": "Run",
+    "Maven.flash-parent [compile].executor": "Run",
+    "Maven.flash-parent [deploy].executor": "Run",
+    "Maven.flash-parent [install].executor": "Run",
+    "Maven.flash-parent [package].executor": "Run",
+    "Maven.flash-web-bundler [test].executor": "Run",
+    "ModuleVcsDetector.initialDetectionPerformed": "true",
+    "RunOnceActivity.MCP Project settings loaded": "true",
+    "RunOnceActivity.ShowReadmeOnStart": "true",
+    "RunOnceActivity.TerminalTabsStorage.copyFrom.TerminalArrangementManager.252": "true",
+    "RunOnceActivity.git.unshallow": "true",
+    "RunOnceActivity.typescript.service.memoryLimit.init": "true",
+    "SHARE_PROJECT_CONFIGURATION_FILES": "true",
+    "git-widget-placeholder": "master",
+    "ignore.virus.scanning.warn.message": "true",
+    "kotlin-language-version-configured": "true",
+    "last_opened_file_path": "C:/Users/elorc/Documents/Coding/Java/practice/Flash",
+    "node.js.detected.package.eslint": "true",
+    "node.js.detected.package.tslint": "true",
+    "node.js.selected.package.eslint": "(autodetect)",
+    "node.js.selected.package.tslint": "(autodetect)",
+    "nodejs_package_manager_path": "npm",
+    "npm.build.executor": "Run",
+    "onboarding.tips.debug.path": "C:/Users/elorc/Documents/Coding/Java/practice/FlashPractice/flash-bench/src/main/java/dev/relism/Main.java",
+    "project.structure.last.edited": "Modules",
+    "project.structure.proportion": "0.15",
+    "project.structure.side.proportion": "0.1150748",
+    "settings.editor.selected.configurable": "project.propVCSSupport.DirectoryMappings",
+    "ts.external.directory.path": "C:\\Users\\elorc\\Documents\\Coding\\Java\\practice\\Flash\\nuxt-shadcn-dashboard\\node_modules\\typescript\\lib",
+    "vue.rearranger.settings.migration": "true"
   }
-}</component>
+}]]></component>
   <component name="RecentsManager">
     <key name="MoveFile.RECENT_KEYS">
       <recent name="C:\Users\elorc\Documents\Coding\Java\practice\Flash" />
@@ -181,13 +175,13 @@
       <recent name="dev.relism" />
     </key>
   </component>
-  <component name="RunManager" selected="Application.dev.relism.bench.Main">
-    <configuration name="ExternalBenchmark (1)" type="Application" factoryName="Application" temporary="true" nameIsGenerated="true">
-      <option name="MAIN_CLASS_NAME" value="dev.relism.ExternalBenchmark" />
+  <component name="RunManager" selected="Application.MainAlt">
+    <configuration name="ExternalBenchmark" type="Application" factoryName="Application" temporary="true" nameIsGenerated="true">
+      <option name="MAIN_CLASS_NAME" value="dev.relism.bench.ExternalBenchmark" />
       <module name="flash" />
       <extension name="coverage">
         <pattern>
-          <option name="PATTERN" value="dev.relism.*" />
+          <option name="PATTERN" value="dev.relism.bench.*" />
           <option name="ENABLED" value="true" />
         </pattern>
       </extension>
@@ -195,9 +189,10 @@
         <option name="Make" enabled="true" />
       </method>
     </configuration>
-    <configuration name="ExternalBenchmark" type="Application" factoryName="Application" temporary="true" nameIsGenerated="true">
-      <option name="MAIN_CLASS_NAME" value="dev.relism.bench.ExternalBenchmark" />
+    <configuration name="MainAlt" type="Application" factoryName="Application" temporary="true" nameIsGenerated="true">
+      <option name="MAIN_CLASS_NAME" value="dev.relism.bench.MainAlt" />
       <module name="flash-bench" />
+      <option name="VM_PARAMETERS" value="-Dflash.env=dev" />
       <extension name="coverage">
         <pattern>
           <option name="PATTERN" value="dev.relism.bench.*" />
@@ -208,35 +203,10 @@
         <option name="Make" enabled="true" />
       </method>
     </configuration>
-    <configuration name="ExternalBenchmark" type="Application" factoryName="Application" temporary="true" nameIsGenerated="true">
-      <option name="MAIN_CLASS_NAME" value="dev.relism.bench.ExternalBenchmark" />
-      <module name="flash" />
-      <extension name="coverage">
-        <pattern>
-          <option name="PATTERN" value="dev.relism.bench.*" />
-          <option name="ENABLED" value="true" />
-        </pattern>
-      </extension>
-      <method v="2">
-        <option name="Make" enabled="true" />
-      </method>
-    </configuration>
-    <configuration name="Main" type="Application" factoryName="Application" temporary="true" nameIsGenerated="true">
-      <option name="MAIN_CLASS_NAME" value="dev.relism.Main" />
-      <module name="flash" />
-      <extension name="coverage">
-        <pattern>
-          <option name="PATTERN" value="dev.relism.bench.*" />
-          <option name="ENABLED" value="true" />
-        </pattern>
-      </extension>
-      <method v="2">
-        <option name="Make" enabled="true" />
-      </method>
-    </configuration>
-    <configuration name="dev.relism.bench.Main" type="Application" factoryName="Application" temporary="true" nameIsGenerated="true">
+    <configuration name="(dev) flash-bench" type="Application" factoryName="Application">
       <option name="MAIN_CLASS_NAME" value="dev.relism.bench.Main" />
       <module name="flash-bench" />
+      <option name="VM_PARAMETERS" value="-Dflash.env=dev" />
       <extension name="coverage">
         <pattern>
           <option name="PATTERN" value="dev.relism.bench.*" />
@@ -247,23 +217,14 @@
         <option name="Make" enabled="true" />
       </method>
     </configuration>
-    <configuration name="build" type="js.build_tools.npm" temporary="true" nameIsGenerated="true">
-      <package-json value="$PROJECT_DIR$/nuxt-shadcn-dashboard/package.json" />
-      <command value="run" />
-      <scripts>
-        <script value="build" />
-      </scripts>
-      <node-interpreter value="project" />
-      <envs />
-      <method v="2" />
-    </configuration>
+    <list>
+      <item itemvalue="Application.(dev) flash-bench" />
+      <item itemvalue="Application.ExternalBenchmark" />
+      <item itemvalue="Application.MainAlt" />
+    </list>
     <recent_temporary>
       <list>
-        <item itemvalue="Application.dev.relism.bench.Main" />
-        <item itemvalue="npm.build" />
-        <item itemvalue="Application.Main" />
-        <item itemvalue="Application.ExternalBenchmark (1)" />
-        <item itemvalue="Application.ExternalBenchmark" />
+        <item itemvalue="Application.MainAlt" />
       </list>
     </recent_temporary>
   </component>
@@ -320,7 +281,18 @@
       <workItem from="1774703412987" duration="25271000" />
       <workItem from="1774777423667" duration="2127000" />
       <workItem from="1774790933314" duration="10099000" />
-      <workItem from="1774814271256" duration="2412000" />
+      <workItem from="1774814271256" duration="6223000" />
+      <workItem from="1774872087063" duration="23188000" />
+      <workItem from="1774944423363" duration="2161000" />
+      <workItem from="1774953226940" duration="4167000" />
+      <workItem from="1775295922142" duration="5680000" />
+      <workItem from="1775312662640" duration="1858000" />
+      <workItem from="1775391482685" duration="1961000" />
+      <workItem from="1775495346638" duration="596000" />
+      <workItem from="1775747075572" duration="1237000" />
+      <workItem from="1776192895352" duration="3823000" />
+      <workItem from="1776198526994" duration="4187000" />
+      <workItem from="1776240695245" duration="14368000" />
     </task>
     <task id="LOCAL-00001" summary="Initial">
       <option name="closed" value="true" />
@@ -394,7 +366,15 @@
       <option name="project" value="LOCAL" />
       <updated>1774703474044</updated>
     </task>
-    <option name="localTasksCounter" value="10" />
+    <task id="LOCAL-00010" summary="preparing for another refactoring...">
+      <option name="closed" value="true" />
+      <created>1774819003821</created>
+      <option name="number" value="00010" />
+      <option name="presentableId" value="LOCAL-00010" />
+      <option name="project" value="LOCAL" />
+      <updated>1774819003821</updated>
+    </task>
+    <option name="localTasksCounter" value="11" />
     <servers />
   </component>
   <component name="TypeScriptGeneratedFilesManager">
@@ -433,7 +413,8 @@
     <MESSAGE value="enhanced router middleware support; added pre-fused middleware handling and improved handler registration" />
     <MESSAGE value="pre-major refactoring + ext api." />
     <MESSAGE value="preparing for a conceptual refactoring..." />
-    <option name="LAST_COMMIT_MESSAGE" value="preparing for a conceptual refactoring..." />
+    <MESSAGE value="preparing for another refactoring..." />
+    <option name="LAST_COMMIT_MESSAGE" value="preparing for another refactoring..." />
   </component>
   <component name="XSLT-Support.FileAssociations.UIState">
     <expand />
diff --git a/flash-extensions/flash-ext-jackson/README.md b/flash-extensions/flash-ext-jackson/README.md
index 30ec01e..07b0548 100644
--- a/flash-extensions/flash-ext-jackson/README.md
+++ b/flash-extensions/flash-ext-jackson/README.md
@@ -20,14 +20,16 @@ Jackson JSON integration for the Flash HTTP server.
 </dependency>
 ```
 
-Install before any extension that needs JSON (e.g. `flash-ext-openapi`, `flash-ext-oidc`):
-
 ```java
 FlashApp.create(8080)
     .install(new JacksonExtension())
-    // ... other extensions
+    .install(new OpenApiExtension("/openapi", "My API", "1.0.0"))
+    .start();
 ```
 
+Install order is irrelevant — Flash's two-phase extension model ensures `ObjectMapper` is
+resolved before any extension that calls `ctx.require(ObjectMapper.class)` needs it.
+
 ### Custom mapper
 
 ```java
@@ -56,7 +58,7 @@ public class CreateBlog extends JacksonHandler {
     public Object handle(Request req, Response res) throws Exception {
         CreateBlogRequest body = bodyAs(req, CreateBlogRequest.class);
         Blog created = service.create(body);
-        res.setStatusCode(201);
+        res.status(201);
         return json(res, created);         // sets Content-Type: application/json
     }
 }
@@ -96,7 +98,7 @@ For lambda-style routes, use the `ObjectMapper` directly from the context:
 ObjectMapper mapper = app.ctx().require(ObjectMapper.class);
 
 app.get("/api/status", (req, res) -> {
-    res.setContentType(ContentType.JSON);
+    res.type(ContentType.JSON);
     return mapper.writeValueAsString(Map.of("status", "ok"));
 });
 ```
diff --git a/flash-extensions/flash-ext-jackson/src/main/java/dev/relism/ext/jackson/JacksonExtension.java b/flash-extensions/flash-ext-jackson/src/main/java/dev/relism/ext/jackson/JacksonExtension.java
index 5292846..51d6e9b 100644
--- a/flash-extensions/flash-ext-jackson/src/main/java/dev/relism/ext/jackson/JacksonExtension.java
+++ b/flash-extensions/flash-ext-jackson/src/main/java/dev/relism/ext/jackson/JacksonExtension.java
@@ -4,21 +4,19 @@ import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.json.JsonMapper;
 import dev.relism.extension.FlashContext;
 import dev.relism.extension.FlashExtension;
-import dev.relism.extension.FlashRegistrar;
 
 /**
  * Registers JSON support into the Flash extension layer.
  *
  * <p>Exposes a {@link Json} utility instance in the {@link FlashContext} under
- * {@code Json.class}. Any handler or extension in the same scope can retrieve
- * it via {@code require(Json.class)} inside {@code onInit()}.
+ * {@code Json.class}. Any handler or extension can retrieve it via {@code ctx.require(Json.class)}
+ * inside {@code onInit()} (class-based) or inside {@link FlashExtension#routes} (extensions).
  *
  * <p>The raw {@link ObjectMapper} is also registered under {@code ObjectMapper.class}
  * for extensions that need direct mapper access (e.g. OpenAPI schema generation).
  *
  * <h3>Usage — composition (preferred)</h3>
  * <pre>{@code
- * // No mandatory base class. Works from any RequestHandler.
  * public class MyHandler extends RequestHandler {
  *     private Json json;
  *
@@ -33,16 +31,6 @@ import dev.relism.extension.FlashRegistrar;
  * }
  * }</pre>
  *
- * <h3>Usage — convenience base class</h3>
- * <pre>{@code
- * // JacksonHandler remains available as a thin opt-in wrapper.
- * public class MyHandler extends JacksonHandler {
- *     public Object handle(Request req, Response res) throws Exception {
- *         return json(res, service.findAll());
- *     }
- * }
- * }</pre>
- *
  * <h3>Custom mapper</h3>
  * <pre>{@code
  * ObjectMapper mapper = JsonMapper.builder()
@@ -69,9 +57,9 @@ public class JacksonExtension implements FlashExtension {
     }
 
     @Override
-    public void install(FlashRegistrar app, FlashContext ctx) {
+    public void provide(FlashContext ctx) {
         Json json = new Json(mapper);
         ctx.provide(Json.class,         json);
-        ctx.provide(ObjectMapper.class, mapper);   // backward compat for extensions (OpenAPI, etc.)
+        ctx.provide(ObjectMapper.class, mapper);
     }
 }
diff --git a/flash-extensions/flash-ext-jackson/src/main/java/dev/relism/ext/jackson/Json.java b/flash-extensions/flash-ext-jackson/src/main/java/dev/relism/ext/jackson/Json.java
index a8760f6..3a0b7c4 100644
--- a/flash-extensions/flash-ext-jackson/src/main/java/dev/relism/ext/jackson/Json.java
+++ b/flash-extensions/flash-ext-jackson/src/main/java/dev/relism/ext/jackson/Json.java
@@ -91,16 +91,7 @@ public final class Json {
      * <p>The returned string is used as the response body by the Flash runtime.
      */
     public String write(Response res, Object obj) throws Exception {
-        res.setContentType(ContentType.JSON);
-        return mapper.writeValueAsString(obj);
-    }
-
-    /**
-     * Like {@link #write(Response, Object)} but also sets an explicit HTTP status code.
-     */
-    public String write(Response res, int status, Object obj) throws Exception {
-        res.status(status);
-        res.setContentType(ContentType.JSON);
+        res.type(ContentType.JSON);
         return mapper.writeValueAsString(obj);
     }
 
@@ -109,7 +100,7 @@ public final class Json {
      * restricting serialization to fields visible under {@code view}.
      */
     public String writeView(Response res, Object obj, Class<?> view) throws Exception {
-        res.setContentType(ContentType.JSON);
+        res.type(ContentType.JSON);
         return mapper.writerWithView(view).writeValueAsString(obj);
     }
 
diff --git a/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/Bucket.java b/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/Bucket.java
index 89cfbce..4f60a51 100644
--- a/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/Bucket.java
+++ b/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/Bucket.java
@@ -9,6 +9,8 @@ import java.util.concurrent.atomic.AtomicLong;
  * <ul>
  *   <li><b>FIXED_WINDOW</b>: {@code slot0} = packed {@code (epoch << 32 | count)},
  *       {@code slot1} unused.</li>
+ *   <li><b>SLIDING_WINDOW</b>: {@code slot0} = packed {@code (epoch << 32 | count)},
+ *       {@code slot1} = request count from the immediately preceding epoch.</li>
  *   <li><b>TOKEN_BUCKET</b>: {@code slot0} = tokens × 1000 (scaled),
  *       {@code slot1} = last-refill timestamp (ms since epoch).</li>
  * </ul>
diff --git a/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/Guard.java b/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/Guard.java
index a43348a..8c36179 100644
--- a/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/Guard.java
+++ b/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/Guard.java
@@ -16,17 +16,15 @@ import java.util.concurrent.TimeUnit;
  * time — the resolver lambda is captured directly from the registry (no runtime map lookup):
  * <pre>{@code
  * // 50 req/s per IP — fixed window (default)
- * app.get("/api/search", handler)
- *    .with(guard.limit("ip", 50, 1, TimeUnit.SECONDS));
+ * app.get("/api/search", handler, guard.limit("ip", 50, 1, TimeUnit.SECONDS));
  *
  * // 10 req/min per authenticated user — token bucket
- * app.post("/api/export", handler)
- *    .with(guard.limit("auth_user", 10, 1, TimeUnit.MINUTES, LimitStrategy.TOKEN_BUCKET));
+ * app.post("/api/export", handler, guard.limit("auth_user", 10, 1, TimeUnit.MINUTES, LimitStrategy.TOKEN_BUCKET));
  * }</pre>
  *
- * <p>The resolver name is looked up once here (at {@code .with(guard.limit(...))} call time,
- * i.e. during app wiring, not on each request). If the name is not registered,
- * {@link dev.relism.exceptions.InitializationException} is thrown immediately.
+ * <p>The resolver name is looked up once here (at wiring time, not on each request).
+ * If the name is not registered, {@link dev.relism.exceptions.InitializationException}
+ * is thrown immediately.
  */
 public final class Guard {
 
diff --git a/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/LimitStrategy.java b/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/LimitStrategy.java
index 668f69b..c36792f 100644
--- a/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/LimitStrategy.java
+++ b/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/LimitStrategy.java
@@ -1,6 +1,7 @@
 package dev.relism.ext.limiter;
 
 import dev.relism.ext.limiter.strategy.FixedWindowStrategy;
+import dev.relism.ext.limiter.strategy.SlidingWindowStrategy;
 import dev.relism.ext.limiter.strategy.TokenBucketStrategy;
 
 /**
@@ -38,6 +39,18 @@ public enum LimitStrategy {
     TOKEN_BUCKET {
         @Override
         public RateLimitStrategy create() { return new TokenBucketStrategy(); }
+    },
+
+    /**
+     * Sliding-window counter: interpolates between the previous window's count and the
+     * current window's count weighted by how far into the current window we are.
+     * Eliminates the boundary burst of {@link #FIXED_WINDOW} while remaining O(1)
+     * memory and lock-free. Slight approximation — worst-case error ≈ a few percent at
+     * window boundaries.
+     */
+    SLIDING_WINDOW {
+        @Override
+        public RateLimitStrategy create() { return new SlidingWindowStrategy(); }
     };
 
     /** Creates a fresh, stateless {@link RateLimitStrategy} instance for this algorithm. */
diff --git a/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/LimiterExtension.java b/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/LimiterExtension.java
index c025886..c1b5e0e 100644
--- a/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/LimiterExtension.java
+++ b/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/LimiterExtension.java
@@ -1,24 +1,24 @@
 package dev.relism.ext.limiter;
 
+import dev.relism.extension.ExtensionPhase;
 import dev.relism.extension.FlashContext;
 import dev.relism.extension.FlashExtension;
-import dev.relism.extension.FlashRegistrar;
 import dev.relism.http.HttpStatus;
 import dev.relism.routing.Middleware;
 
+import java.nio.charset.StandardCharsets;
 import java.util.List;
 
 /**
  * Rate-limiting extension for Flash.
  *
- * <p>On {@link #install}:
+ * <p>At {@link #provide}:
  * <ol>
  *   <li>Creates a single {@link BucketStore} shared by all rules in this extension instance.</li>
  *   <li>Provides a {@link Guard} in the {@link FlashContext} for manual use on lambda routes.</li>
  *   <li>Registers an {@link dev.relism.extension.AnnotationProcessor} for {@link Limit}:
  *       reads the annotation once per handler class at boot, resolves the key lambda
- *       from the registry <em>fail-fast</em>, then returns a pre-compiled middleware
- *       that captures the lambda and config directly — zero map lookups at request time.</li>
+ *       fail-fast, then returns a pre-compiled middleware — zero map lookups at request time.</li>
  * </ol>
  *
  * <h3>Annotation-based (class handlers)</h3>
@@ -34,23 +34,24 @@ import java.util.List;
  *
  * <h3>Lambda routes (via Guard)</h3>
  * <pre>{@code
- * LimiterConfig conf = new LimiterConfig()
- *     .registerResolver("auth_user", req -> ClaimsHolder.user().sub());
+ * app.install(new LimiterExtension(
+ *     new LimiterConfig().registerResolver("auth_user", req -> ClaimsHolder.user().sub())));
  *
- * app.install(new LimiterExtension(conf));
- *
- * Guard guard = app.ctx().require(Guard.class);
- * app.get("/api/search", handler).with(guard.limit("ip", 50, 1, TimeUnit.SECONDS));
+ * // inside FlashExtension.routes() or after install():
+ * Guard guard = ctx.require(Guard.class);
+ * app.get("/api/search", handler, guard.limit("ip", 50, 1, TimeUnit.SECONDS));
  * }</pre>
- *
- * <h3>Installation order matters</h3>
- * Install {@code LimiterExtension} <em>before</em> authentication extensions so that
- * rate-limit checks short-circuit before expensive token validation on over-limit requests.
  */
 public final class LimiterExtension implements FlashExtension {
 
     private final LimiterConfig config;
 
+    /**
+     * Rate limiting runs before authentication — cheaper check rejects over-limit
+     * requests before any token validation occurs.
+     */
+    @Override public int priority() { return ExtensionPhase.EARLY.value; }
+
     /** Installs with default config (only the built-in {@code "ip"} resolver). */
     public LimiterExtension() {
         this(new LimiterConfig());
@@ -62,7 +63,7 @@ public final class LimiterExtension implements FlashExtension {
     }
 
     @Override
-    public void install(FlashRegistrar app, FlashContext ctx) {
+    public void provide(FlashContext ctx) {
         BucketStore store = new BucketStore();
         Guard       guard = new Guard(config, store);
 
@@ -96,14 +97,13 @@ public final class LimiterExtension implements FlashExtension {
      *   <li>{@code resolver} is captured directly in the closure — no registry lookup per request.</li>
      *   <li>{@code resultBuf} is a per-{@link Middleware}-instance ThreadLocal {@code long[2]}.
      *       Allocated once per thread, reused forever — zero per-request allocation.</li>
-     *   <li>Header values ({@code String.valueOf(...)}) are the only unavoidable allocations;
-     *       they are tiny and bounded.</li>
+     *   <li>The static {@code X-RateLimit-Limit} header is pre-encoded at boot — zero-alloc.</li>
      * </ul>
      */
     static Middleware buildMiddleware(KeyResolver resolver, LimitConfig cfg, BucketStore store) {
-        // One result buffer per thread, per middleware instance.
-        // ThreadLocal is captured in the closure at boot time — not re-created per request.
-        ThreadLocal<long[]> resultBuf = ThreadLocal.withInitial(() -> new long[2]);
+        ThreadLocal<long[]> resultBuf  = ThreadLocal.withInitial(() -> new long[2]);
+        byte[]              limitHeader = ("X-RateLimit-Limit: " + cfg.limit() + "\r\n")
+                .getBytes(StandardCharsets.UTF_8);
 
         return next -> (req, res) -> {
             String key    = resolver.resolve(req);
@@ -112,8 +112,7 @@ public final class LimiterExtension implements FlashExtension {
 
             boolean allowed = cfg.strategy().check(bucket, cfg, out);
 
-            // Always inject rate-limit headers — useful even on allowed requests.
-            res.header("X-RateLimit-Limit",     String.valueOf(cfg.limit()));
+            res.header(limitHeader);
             res.header("X-RateLimit-Remaining", String.valueOf(out[0]));
             res.header("X-RateLimit-Reset",     String.valueOf(out[1]));
 
diff --git a/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/RateLimitStrategy.java b/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/RateLimitStrategy.java
index 3434f49..b5584d6 100644
--- a/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/RateLimitStrategy.java
+++ b/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/RateLimitStrategy.java
@@ -11,6 +11,7 @@ package dev.relism.ext.limiter;
  * <p>Called on every request — must not allocate on the hot path.
  *
  * @see dev.relism.ext.limiter.strategy.FixedWindowStrategy
+ * @see dev.relism.ext.limiter.strategy.SlidingWindowStrategy
  * @see dev.relism.ext.limiter.strategy.TokenBucketStrategy
  */
 public interface RateLimitStrategy {
diff --git a/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/strategy/SlidingWindowStrategy.java b/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/strategy/SlidingWindowStrategy.java
new file mode 100644
index 0000000..0e2dedd
--- /dev/null
+++ b/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/strategy/SlidingWindowStrategy.java
@@ -0,0 +1,86 @@
+package dev.relism.ext.limiter.strategy;
+
+import dev.relism.ext.limiter.Bucket;
+import dev.relism.ext.limiter.LimitConfig;
+import dev.relism.ext.limiter.RateLimitStrategy;
+
+/**
+ * Sliding-window counter rate limit: approximates a true sliding window by interpolating
+ * between the previous fixed window's count and the current window's count.
+ *
+ * <pre>
+ *   estimate = prevCount × (1 − elapsed / windowMs) + currentCount
+ * </pre>
+ *
+ * <p>This is the same approximation used by Redis. It eliminates the boundary burst
+ * problem of {@link FixedWindowStrategy} while staying O(1) memory and lock-free.
+ * The error is bounded: in the worst case the true rate at the boundary can exceed
+ * the limit by at most {@code limit × (1 − elapsed/windowMs)} — typically a few percent.
+ *
+ * <h3>Slot layout</h3>
+ * <ul>
+ *   <li>{@link Bucket#slot0} — packed {@code (reducedEpoch << 32 | currentCount)}</li>
+ *   <li>{@link Bucket#slot1} — count from the immediately preceding epoch (0 = none)</li>
+ * </ul>
+ *
+ * <p>On a window transition the thread that wins the {@code slot0} CAS also writes
+ * {@code slot1}. A concurrent thread that reads {@code slot0} after the transition but
+ * before {@code slot1} is written sees a slightly stale previous count — acceptable for
+ * an approximation algorithm.
+ */
+public final class SlidingWindowStrategy implements RateLimitStrategy {
+
+    @Override
+    public boolean check(Bucket bucket, LimitConfig cfg, long[] out) {
+        long now      = System.currentTimeMillis();
+        long windowMs = cfg.windowMs();
+        long absEpoch = now / windowMs;
+        int  epoch    = (int)(absEpoch & 0xFFFFFFFFL);
+        long elapsed  = now % windowMs;   // ms elapsed inside the current window
+
+        while (true) {
+            long packed      = bucket.slot0.get();
+            int  storedEpoch = (int)(packed >>> 32);
+            int  count       = (int)(packed & 0xFFFFFFFFL);
+
+            if (storedEpoch == epoch) {
+                // ── Same window ──────────────────────────────────────────────────
+                long prevCount = bucket.slot1.get();
+                // Integer interpolation — no floating-point on hot path.
+                long estimate  = (prevCount * (windowMs - elapsed)) / windowMs + count + 1;
+
+                if (estimate > cfg.limit()) {
+                    out[0] = 0L;
+                    out[1] = (absEpoch + 1) * windowMs / 1000L;
+                    return false;
+                }
+
+                int  newCount  = Math.min(count + 1, cfg.limit() + 1);
+                long newPacked = ((long) epoch << 32) | (newCount & 0xFFFFFFFFL);
+                if (!bucket.slot0.compareAndSet(packed, newPacked)) continue; // CAS lost, retry
+
+                out[0] = Math.max(0L, cfg.limit() - estimate);
+                out[1] = (absEpoch + 1) * windowMs / 1000L;
+                return true;
+
+            } else {
+                // ── Window transition ────────────────────────────────────────────
+                // If the stored epoch is exactly the one before ours, carry its count forward.
+                // If it's older (gap ≥ 2 windows), the previous window is effectively empty.
+                int  prevEpoch = (int)((absEpoch - 1) & 0xFFFFFFFFL);
+                long oldCount  = (storedEpoch == prevEpoch) ? count : 0L;
+
+                long newPacked = ((long) epoch << 32) | 1L;
+                if (!bucket.slot0.compareAndSet(packed, newPacked)) continue; // CAS lost, retry
+
+                // Won the transition: publish old count so the same-window branch can read it.
+                bucket.slot1.set(oldCount);
+
+                long estimate = (oldCount * (windowMs - elapsed)) / windowMs + 1;
+                out[0] = Math.max(0L, cfg.limit() - estimate);
+                out[1] = (absEpoch + 1) * windowMs / 1000L;
+                return estimate <= cfg.limit();
+            }
+        }
+    }
+}
diff --git a/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/strategy/TokenBucketStrategy.java b/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/strategy/TokenBucketStrategy.java
index f77545a..cb49430 100644
--- a/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/strategy/TokenBucketStrategy.java
+++ b/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/ext/limiter/strategy/TokenBucketStrategy.java
@@ -17,9 +17,8 @@ import dev.relism.ext.limiter.RateLimitStrategy;
  *   <li>{@link Bucket#slot1} — last-refill timestamp in ms. 0 = not yet initialised.</li>
  * </ul>
  *
- * <p>Each request CAS-loops on {@code slot0}; {@code slot1} is updated best-effort after a
- * successful CAS. The resulting inaccuracy is bounded by the nanoseconds between the CAS
- * and the {@code set} — negligible and self-correcting for rate limiting purposes.
+ * <p>Each request CAS-loops on {@code slot0}; {@code slot1} is advanced monotonically via CAS
+ * after a successful token consumption — never regresses to an older timestamp under concurrent load.
  */
 public final class TokenBucketStrategy implements RateLimitStrategy {
 
@@ -57,8 +56,8 @@ public final class TokenBucketStrategy implements RateLimitStrategy {
 
             long newTokens = currentTokens - SCALE;
             if (bucket.slot0.compareAndSet(rawTokens, newTokens)) {
-                // Consumed successfully. Update refill baseline best-effort.
-                bucket.slot1.set(now);
+                // Advance refill baseline: CAS ensures we never regress to an older timestamp.
+                if (lastMs < now) bucket.slot1.compareAndSet(lastMs, now);
                 out[0] = newTokens / SCALE;
                 out[1] = now / 1000L;
                 return true;
diff --git a/flash-extensions/flash-ext-oidc/README.md b/flash-extensions/flash-ext-oidc/README.md
index 1814a03..8382dce 100644
--- a/flash-extensions/flash-ext-oidc/README.md
+++ b/flash-extensions/flash-ext-oidc/README.md
@@ -3,6 +3,9 @@
 Full OIDC Authorization Code + PKCE flow for the Flash HTTP server.
 Supports Keycloak, Authelia, Auth0, Google, and any RFC 8414-compliant provider.
 
+Standards alignment focuses on OIDC Core + OAuth2 bearer APIs while preserving Flash's
+hot-path model (middleware compiled at mount time, no heavy runtime work).
+
 ## What it provides
 
 | Component | Description |
@@ -12,6 +15,7 @@ Supports Keycloak, Authelia, Auth0, Google, and any RFC 8414-compliant provider.
 | `POST {prefix}/logout` | Invalidates the session, redirects to the provider's `end_session_endpoint` |
 | `@Authenticated` | Annotation: protects a class-based handler (redirects browsers, 401 for API clients) |
 | `@RolesAllowed(...)` | Annotation: protects with role check (OR semantics) |
+| `@ScopesAllowed(...)` | Annotation: protects with scope check (`ALL` default, `ANY` optional) |
 | `OidcMiddleware` | Programmatic middleware for lambda routes |
 | `ClaimsHolder` / `OidcUser` | Thread-local user info accessible from any protected handler |
 | `JwtValidator` | JWKS-backed JWT validator (PKCE + key rotation + caching) |
@@ -40,9 +44,14 @@ FlashApp.create(8080)
                 "https://idp.example.com",
                 "my-client", "my-secret", "/auth/callback")
             .build()
-    ));
+    ))
+    .start();
 ```
 
+Install order is irrelevant. The two-phase extension model guarantees all services
+(including `OpenApiSecurityRegistry` from `flash-ext-openapi`) are registered before
+any extension's routes phase runs.
+
 ### Keycloak shortcut
 
 ```java
@@ -86,6 +95,7 @@ OidcConfig.builder("https://auth.example.com", "my-client", "secret", "/auth/cal
 | `.selfScheme("http")` | `"http"` | Scheme used when resolving server-relative redirect URIs |
 | `.https()` | — | Shorthand for `.selfScheme("https")` |
 | `.rolesClaimPath("realm_access.roles")` | `"realm_access.roles"` | Dot-path to the roles array in JWT claims |
+| `.scopeClaimPaths("scope,scp")` | `"scope,scp"` | Comma-separated claim paths used to resolve OAuth scopes |
 | `.algorithm("RS256")` | `"RS256"` | JWS algorithm for token validation |
 | `.postLogoutRedirectUri("/")` | `"/"` | Where to redirect after logout |
 | `.sessionStore(store)` | `InMemoryOidcSessionStore` | Custom session store (see below) |
@@ -104,6 +114,7 @@ OIDC_SCOPES                default: openid profile email
 OIDC_ROUTE_PREFIX          default: /auth
 OIDC_SELF_SCHEME           default: http
 OIDC_ROLES_CLAIM           default: realm_access.roles
+OIDC_SCOPE_CLAIMS          default: scope,scp
 OIDC_ALGORITHM             default: RS256
 OIDC_POST_LOGOUT_REDIRECT  default: /
 OIDC_CLIENT_AUTH_METHOD    default: POST
@@ -128,14 +139,35 @@ public class MePage extends JacksonHandler {
 @RolesAllowed("admin")           // OR semantics: "admin" OR "superuser"
 // @RolesAllowed({"admin", "superuser"})
 public class AdminPage extends JacksonHandler { ... }
+
+@Route(method = HttpMethod.POST, path = "/orders")
+@ScopesAllowed("orders:write")   // default = ALL semantics
+public class CreateOrder extends JacksonHandler { ... }
+
+@Route(method = HttpMethod.POST, path = "/payments")
+@ScopesAllowed(value = {"payments:write", "payments:admin"}, match = ScopesAllowed.Match.ANY)
+public class PayOrder extends JacksonHandler { ... }
+
+@Route(method = HttpMethod.DELETE, path = "/admin/users/{id}")
+@RolesAllowed("admin")
+@ScopesAllowed("users:delete")   // combined with AND semantics
+public class DeleteUser extends JacksonHandler { ... }
 ```
 
 The middleware is injected automatically by the annotation processor — no manual wiring needed.
 
+Annotation composition rules:
+
+- `@Authenticated` requires auth only
+- `@RolesAllowed` implies authentication + role OR-check
+- `@ScopesAllowed` implies authentication + scope check (`ALL`/`ANY`)
+- combining `@RolesAllowed` + `@ScopesAllowed` uses AND semantics
+- `@Authenticated(optional = true)` cannot be combined with role/scope constraints
+
 ### Lambda routes (manual middleware)
 
-For lambda routes you must apply the middleware explicitly. Retrieve it from the context
-after `install()` completes:
+For lambda routes, pass the middleware as a varargs argument. Retrieve `OidcMiddleware`
+from the context inside another extension's `routes()` phase, or after `start()`:
 
 ```java
 OidcMiddleware oidc = app.ctx().require(OidcMiddleware.class);
@@ -144,21 +176,26 @@ OidcMiddleware oidc = app.ctx().require(OidcMiddleware.class);
 app.get("/api/me", (req, res) -> {
     OidcUser u = ClaimsHolder.user();   // never null here
     return Map.of("sub", u.sub(), "email", u.email());
-}).with(oidc.protect());
+}, oidc.protect());
 
 // Authentication + role check
 app.delete("/api/admin/users/{id}", (req, res) -> {
     OidcUser u = ClaimsHolder.user();
     // ...
-}).with(oidc.requireRole("admin"));
+}, oidc.requireRole("admin"));
 
 // Multiple roles (OR): passes if user holds any one of them
-app.get("/api/reports", (req, res) -> { ... })
-   .with(oidc.requireRole("admin", "reports-viewer"));
+app.get("/api/reports", (req, res) -> { ... }, oidc.requireRole("admin", "reports-viewer"));
+
+// Require all listed scopes
+app.post("/api/orders", (req, res) -> { ... }, oidc.requireScopes("orders:write", "payments:write"));
+
+// Require at least one listed scope
+app.post("/api/payments", (req, res) -> { ... }, oidc.requireAnyScope("payments:write", "payments:admin"));
 ```
 
-`oidc.protect()` / `oidc.requireRole(...)` return a `Middleware` — a composable
-`Handler -> Handler` wrapper. Flash applies middleware right-to-left so the OIDC check
+`oidc.protect()` / `oidc.requireRole(...)` / `oidc.requireScopes(...)` return a `Middleware` — a composable
+`Handler → Handler` wrapper. Flash applies middleware right-to-left so the OIDC check
 runs before your handler.
 
 ## Accessing the authenticated user
@@ -185,6 +222,14 @@ List<String> groups = u.roles("groups");              // Authelia
 
 boolean isAdmin = u.hasRole("realm_access.roles", "admin");
 
+// Scopes (OIDC/OAuth2 generic): checks "scope" then "scp"
+List<String> scopes = u.scopes();
+boolean canWrite = u.hasScope("orders:write");
+
+// Custom claim path resolution (for provider-specific payloads)
+List<String> customScopes = u.scopes("scope,scp,permissions.scopes");
+boolean canApprove = u.hasScope("permissions.scopes", "orders:approve");
+
 // Arbitrary claim
 String locale = (String) u.claim("locale");
 Long   exp    = u.claim("exp", Long.class);
@@ -207,7 +252,7 @@ The middleware adds negligible overhead on the hot path for authenticated reques
 | Step | Cost |
 |---|---|
 | `Authorization` header check | `O(1)` map lookup |
-| Cookie parse | `O(cookie_count)` string split |
+| Cookie parse | `O(cookie_length)` single pass scan |
 | Session lookup | `O(1)` `ConcurrentHashMap.get()` |
 | Token expiry check | `O(1)` `Instant` comparison |
 | `ClaimsHolder.set()` | `O(1)` `ThreadLocal.set()` |
@@ -216,6 +261,8 @@ No network calls, no cryptography, no JSON parsing on the happy path (valid sess
 JWKS key fetching only happens for Bearer token validation and is cached + rate-limited by
 Nimbus's `JWKSourceBuilder`. Silent token refresh only triggers when the access token expires.
 
+Role/scope claim paths are compiled once during middleware construction (mount time), not per request.
+
 ## Authentication flow details
 
 On each request the middleware resolves credentials in this order:
@@ -227,6 +274,16 @@ On each request the middleware resolves credentials in this order:
    - Browser clients (no `Accept: application/json`) → redirect to `{prefix}/login?redirect={path}`
    - API clients → `401 Unauthorized`
 
+### API error semantics (RFC 6750)
+
+For API clients (`Accept: application/json`) the middleware includes `WWW-Authenticate`:
+
+- missing credentials: `Bearer realm="<schemeName>"`
+- invalid bearer token: `Bearer realm="<schemeName>", error="invalid_token"`
+- insufficient scopes: `Bearer realm="<schemeName>", error="insufficient_scope", scope="<required scopes>"`
+
+This enables interoperable client-side handling and proper OAuth2 challenge semantics.
+
 ### Token validation (OIDC Core §3.1.3.7)
 
 | Check | Access token | ID token |
@@ -249,6 +306,52 @@ At callback time the extension merges access token + ID token claims:
 This is provider-agnostic: authorization claims live in the AT per RFC 9068,
 identity claims live in the IT per OIDC Core.
 
+## Standards & compliance notes
+
+This extension is designed to be compliant with the most relevant OIDC/OAuth2 RFCs:
+
+- RFC 8414 (Authorization Server Metadata): discovery via `/.well-known/openid-configuration`
+- OpenID Connect Core 1.0: Authorization Code flow + PKCE + `nonce` validation on ID token
+- RFC 7636 (PKCE): S256 challenge/verifier flow
+- RFC 6750 (Bearer Token Usage): `WWW-Authenticate` challenges with standard error codes
+- RFC 9068 (JWT Profile for Access Tokens): JWT bearer access-token validation path
+- RFC 7519 / RFC 7517 / RFC 7515 family: JWT/JWK/JWS validation via Nimbus + JWKS caching/rotation
+
+Provider interoperability details:
+
+- scope extraction supports both standard forms: `scope` (space-delimited string) and `scp` (list/string)
+- roles remain configurable via `rolesClaimPath` (`realm_access.roles`, `groups`, etc.)
+- scope claim fallback chain is configurable via `scopeClaimPaths`
+
+## Testing scopes with Keycloak
+
+Quick path to test `@ScopesAllowed` end-to-end:
+
+1. **Create a client scope**
+   - Realm -> Client scopes -> Create
+   - Name: `orders:write` (or any scope name you want to enforce)
+2. **Attach it to your client**
+   - Clients -> `<your-client>` -> Client scopes
+   - Add the scope as `Default` (always in token) or `Optional` (requested via `scope` param)
+3. **Ensure scope mapper reaches the token**
+   - For most Keycloak setups this is automatic via built-in `microprofile-jwt`/scope mappers
+   - Verify the access token contains either `scope` string or `scp` list
+4. **Request the scope in Flash config**
+   - Include it in `OidcConfig.scopes(...)`, e.g. `"openid profile email orders:write"`
+5. **Protect a handler**
+   - `@ScopesAllowed("orders:write")` on class-based handlers
+   - or `oidc.requireScopes("orders:write")` for lambda routes
+6. **Verify behavior**
+   - token with scope -> 200
+   - token without scope -> 403 + `WWW-Authenticate: ... insufficient_scope`
+
+Useful token inspection flow while testing:
+
+- Obtain a token from Keycloak
+- Decode payload (`jwt.io` or local tool)
+- check `scope` / `scp` claims
+- call your protected endpoint and inspect status + `WWW-Authenticate`
+
 ## Session store
 
 The default `InMemoryOidcSessionStore` is sufficient for single-instance deployments.
@@ -316,32 +419,39 @@ app.install(new OidcExtension(tenantA))
    .install(new OidcExtension(tenantB));
 ```
 
-To reference a specific tenant's middleware on lambda routes, keep the extension reference
-and retrieve `OidcMiddleware` from context **after** each install:
+To reference a specific tenant's middleware on lambda routes, keep the extension instances
+and retrieve `OidcMiddleware` from context after `start()`:
 
 ```java
-app.install(new OidcExtension(tenantA));
-OidcMiddleware mwA = app.ctx().require(OidcMiddleware.class);   // tenantA's middleware
+OidcExtension extA = new OidcExtension(tenantA);
+OidcExtension extB = new OidcExtension(tenantB);
 
-app.install(new OidcExtension(tenantB));
-OidcMiddleware mwB = app.ctx().require(OidcMiddleware.class);   // tenantB's middleware
+FlashApp app = FlashApp.create(8080)
+    .install(extA)
+    .install(extB)
+    .start()
+    .join();    // wait for bind
 
-app.get("/a/dashboard", (req, res) -> { ... }).with(mwA.protect());
-app.get("/b/dashboard", (req, res) -> { ... }).with(mwB.protect());
+OidcMiddleware mwA = app.ctx().require(OidcMiddleware.class);  // last registered = tenantB
 ```
 
+> **Note:** because both extensions register `OidcMiddleware.class` in the same context,
+> only the last one wins under that key. For multi-tenant setups, use distinct context
+> keys or provide middleware under a wrapper/alias type, or use lambda routes with explicit
+> middleware captured from the extension instance before `install()`.
+
 Class-based handlers annotated with `@Authenticated` / `@RolesAllowed` get the last
-registered middleware injected. For multi-tenant class-based handlers, use lambdas or
-install tenant-specific annotation processors.
+registered processor's middleware. For true multi-tenant class-based routing, install
+tenant-specific annotation processors with different annotations.
 
 ## OpenAPI integration
 
-If `flash-ext-openapi` is on the classpath and installed **before** `flash-ext-oidc`,
+If `flash-ext-openapi` is on the classpath and installed (order irrelevant),
 the extension automatically:
 
 - Adds a `components.securitySchemes` entry for the provider (OAuth2, authorizationCode flow)
 - Adds `security` requirements to every operation whose handler carries `@Authenticated`
-  or `@RolesAllowed`
+  , `@RolesAllowed`, or `@ScopesAllowed`
 
 No extra code needed. To customize the scheme name:
 
diff --git a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcAuthPolicy.java b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcAuthPolicy.java
new file mode 100644
index 0000000..23ccce7
--- /dev/null
+++ b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcAuthPolicy.java
@@ -0,0 +1,98 @@
+package dev.relism.ext.oidc;
+
+import java.util.LinkedHashSet;
+import java.util.List;
+
+/**
+ * Compiled authorization policy derived from handler annotations at mount time.
+ * Immutable and allocation-free on the request hot path.
+ */
+final class OidcAuthPolicy {
+
+    private static final String[] EMPTY = new String[0];
+
+    private static final OidcAuthPolicy AUTH_REQUIRED = new OidcAuthPolicy(
+            false, EMPTY, EMPTY, ScopesAllowed.Match.ALL);
+    private static final OidcAuthPolicy AUTH_OPTIONAL = new OidcAuthPolicy(
+            true, EMPTY, EMPTY, ScopesAllowed.Match.ALL);
+
+    private final boolean optionalAuth;
+    private final String[] requiredRoles;
+    private final String[] requiredScopes;
+    private final ScopesAllowed.Match scopeMatch;
+
+    private OidcAuthPolicy(boolean optionalAuth,
+                           String[] requiredRoles,
+                           String[] requiredScopes,
+                           ScopesAllowed.Match scopeMatch) {
+        this.optionalAuth   = optionalAuth;
+        this.requiredRoles  = requiredRoles;
+        this.requiredScopes = requiredScopes;
+        this.scopeMatch     = scopeMatch;
+    }
+
+    static OidcAuthPolicy authenticated() { return AUTH_REQUIRED; }
+
+    static OidcAuthPolicy optional() { return AUTH_OPTIONAL; }
+
+    static OidcAuthPolicy rolesAny(String... roles) {
+        return new OidcAuthPolicy(false, normalizeRequired("RolesAllowed", roles), EMPTY, ScopesAllowed.Match.ALL);
+    }
+
+    static OidcAuthPolicy scopes(String[] scopes, ScopesAllowed.Match match) {
+        return new OidcAuthPolicy(false, EMPTY, normalizeRequired("ScopesAllowed", scopes), match);
+    }
+
+    static OidcAuthPolicy compileFromAnnotations(Class<?> handlerClass) {
+        Authenticated auth = handlerClass.getAnnotation(Authenticated.class);
+        RolesAllowed roles = handlerClass.getAnnotation(RolesAllowed.class);
+        ScopesAllowed scopes = handlerClass.getAnnotation(ScopesAllowed.class);
+
+        if (auth == null && roles == null && scopes == null) return null;
+
+        boolean optionalAuth = auth != null && auth.optional();
+        String[] requiredRoles = roles != null ? normalizeRequired("RolesAllowed", roles.value()) : EMPTY;
+        String[] requiredScopes = scopes != null ? normalizeRequired("ScopesAllowed", scopes.value()) : EMPTY;
+        ScopesAllowed.Match scopeMatch = scopes != null ? scopes.match() : ScopesAllowed.Match.ALL;
+
+        if (optionalAuth && (requiredRoles.length > 0 || requiredScopes.length > 0)) {
+            throw new IllegalStateException("@Authenticated(optional = true) cannot be combined with @RolesAllowed/@ScopesAllowed on "
+                    + handlerClass.getName());
+        }
+
+        return new OidcAuthPolicy(optionalAuth, requiredRoles, requiredScopes, scopeMatch);
+    }
+
+    static List<String> openApiScopesFor(Class<?> handlerClass) {
+        Authenticated auth = handlerClass.getAnnotation(Authenticated.class);
+        RolesAllowed roles = handlerClass.getAnnotation(RolesAllowed.class);
+        ScopesAllowed scopes = handlerClass.getAnnotation(ScopesAllowed.class);
+        if (auth == null && roles == null && scopes == null) return null;
+        if (scopes == null) return List.of();
+        return List.of(normalizeRequired("ScopesAllowed", scopes.value()));
+    }
+
+    boolean optionalAuth() { return optionalAuth; }
+
+    String[] requiredRoles() { return requiredRoles; }
+
+    String[] requiredScopes() { return requiredScopes; }
+
+    ScopesAllowed.Match scopeMatch() { return scopeMatch; }
+
+    private static String[] normalizeRequired(String annotation, String[] values) {
+        if (values == null || values.length == 0)
+            throw new IllegalStateException("@" + annotation + " requires at least one value");
+
+        LinkedHashSet<String> normalized = new LinkedHashSet<>(values.length);
+        for (String raw : values) {
+            if (raw == null) continue;
+            String trimmed = raw.trim();
+            if (!trimmed.isEmpty()) normalized.add(trimmed);
+        }
+        if (normalized.isEmpty())
+            throw new IllegalStateException("@" + annotation + " requires at least one non-empty value");
+
+        return normalized.toArray(String[]::new);
+    }
+}
diff --git a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcConfig.java b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcConfig.java
index c8e0390..4820097 100644
--- a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcConfig.java
+++ b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcConfig.java
@@ -17,6 +17,7 @@ package dev.relism.ext.oidc;
  *         "https://keycloak.example.com/realms/myrealm",
  *         "my-app", "secret", "/auth/callback")
  *     .rolesClaimPath("realm_access.roles")   // Keycloak default
+ *     .scopeClaimPaths("scope,scp")           // default; supports many IdPs
  *     .build();
  *
  * // Authelia
@@ -24,6 +25,7 @@ package dev.relism.ext.oidc;
  *         "https://auth.example.com",
  *         "my-app", "secret", "/auth/callback")
  *     .rolesClaimPath("groups")
+ *     .scopeClaimPaths("scope,scp")
  *     .build();
  *
  * // Two tenants on one server
@@ -45,6 +47,7 @@ public final class OidcConfig {
     private final String           routePrefix;
     private final String           selfScheme;
     private final String           rolesClaimPath;
+    private final String           scopeClaimPaths;
     private final String           algorithm;
     private final String           postLogoutRedirectUri;
     private final OidcSessionStore sessionStore;
@@ -61,6 +64,7 @@ public final class OidcConfig {
         this.routePrefix           = b.routePrefix;
         this.selfScheme            = b.selfScheme;
         this.rolesClaimPath        = b.rolesClaimPath;
+        this.scopeClaimPaths       = b.scopeClaimPaths;
         this.algorithm             = b.algorithm;
         this.postLogoutRedirectUri = b.postLogoutRedirectUri;
         this.sessionStore          = b.sessionStore != null ? b.sessionStore
@@ -80,6 +84,8 @@ public final class OidcConfig {
     public String           routePrefix()           { return routePrefix; }
     public String           selfScheme()            { return selfScheme; }
     public String           rolesClaimPath()        { return rolesClaimPath; }
+    /** Comma-separated claim paths used to read OAuth2 scopes (default: {@code "scope,scp"}). */
+    public String           scopeClaimPaths()       { return scopeClaimPaths; }
     public String           algorithm()             { return algorithm; }
     public String           postLogoutRedirectUri() { return postLogoutRedirectUri; }
     public OidcSessionStore sessionStore()          { return sessionStore; }
@@ -102,6 +108,7 @@ public final class OidcConfig {
      * OIDC_ROUTE_PREFIX         default: /auth
      * OIDC_SELF_SCHEME          default: http
      * OIDC_ROLES_CLAIM          default: realm_access.roles
+     * OIDC_SCOPE_CLAIMS         default: scope,scp
      * OIDC_ALGORITHM            default: RS256
      * OIDC_POST_LOGOUT_REDIRECT default: /
      * </pre>
@@ -113,6 +120,7 @@ public final class OidcConfig {
                 .routePrefix          (envOr("OIDC_ROUTE_PREFIX",          "/auth"))
                 .selfScheme           (envOr("OIDC_SELF_SCHEME",           "http"))
                 .rolesClaimPath       (envOr("OIDC_ROLES_CLAIM",           "realm_access.roles"))
+                .scopeClaimPaths      (envOr("OIDC_SCOPE_CLAIMS",          "scope,scp"))
                 .algorithm            (envOr("OIDC_ALGORITHM",             "RS256"))
                 .postLogoutRedirectUri(envOr("OIDC_POST_LOGOUT_REDIRECT",  "/"))
                 .clientAuthMethod(ClientAuthMethod.valueOf(
@@ -179,6 +187,7 @@ public final class OidcConfig {
         private String           routePrefix           = "/auth";
         private String           selfScheme            = "http";
         private String           rolesClaimPath        = "realm_access.roles";
+        private String           scopeClaimPaths       = "scope,scp";
         private String           algorithm             = "RS256";
         private String           postLogoutRedirectUri = "/";
         private OidcSessionStore sessionStore;
@@ -203,6 +212,8 @@ public final class OidcConfig {
         public Builder https()                                      { return selfScheme("https"); }
         /** Dot-separated path to the roles array in JWT claims (default: {@code realm_access.roles}). */
         public Builder rolesClaimPath(String path)                  { this.rolesClaimPath = path;                         return this; }
+        /** Comma-separated claim paths used to resolve OAuth2 scopes (default: {@code scope,scp}). */
+        public Builder scopeClaimPaths(String paths)                { this.scopeClaimPaths = paths;                       return this; }
         /** JWS algorithm (default: {@code RS256}). */
         public Builder algorithm(String algorithm)                  { this.algorithm = algorithm;                         return this; }
         /** Where to redirect after logout (default: {@code /}). */
diff --git a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcExtension.java b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcExtension.java
index 9ac0a66..940fbd0 100644
--- a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcExtension.java
+++ b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcExtension.java
@@ -21,21 +21,22 @@ import java.util.UUID;
 /**
  * Full OIDC Authorization Code + PKCE flow for Flash.
  *
- * <p>On {@link #install}, the extension:
+ * <p>At {@link #provide}, the extension:
  * <ol>
  *   <li>Fetches the provider discovery document — fail-fast at startup.</li>
- *   <li>Registers three routes on the {@link FlashApp}:
- *     <ul>
- *       <li>{@code GET  {prefix}/login}    — builds the authorization URL and redirects.</li>
- *       <li>{@code GET  {prefix}/callback} — exchanges the code, creates a session, redirects.</li>
- *       <li>{@code POST {prefix}/logout}   — invalidates the session, redirects to the provider's
- *           end-session endpoint (if available) or to {@link OidcConfig#postLogoutRedirectUri()}.</li>
- *     </ul>
- *   </li>
  *   <li>Provides {@link OidcMiddleware} and {@link JwtValidator} in the context.</li>
- *   <li>Registers an annotation processor for {@link Authenticated} and {@link RolesAllowed}.</li>
+ *   <li>Registers annotation processors for {@link Authenticated}, {@link RolesAllowed}
+ *       and {@link ScopesAllowed}.</li>
  * </ol>
  *
+ * <p>At {@link #routes}, three routes are registered:
+ * <ul>
+ *   <li>{@code GET  {prefix}/login}    — builds the authorization URL and redirects.</li>
+ *   <li>{@code GET  {prefix}/callback} — exchanges the code, creates a session, redirects.</li>
+ *   <li>{@code POST {prefix}/logout}   — invalidates the session, redirects to provider
+ *       end-session endpoint (if available) or to {@link OidcConfig#postLogoutRedirectUri()}.</li>
+ * </ul>
+ *
  * <pre>{@code
  * // Keycloak
  * app.install(new OidcExtension(
@@ -54,41 +55,48 @@ public class OidcExtension implements FlashExtension {
 
     private final OidcConfig config;
 
+    // Initialized in provide(), used in routes() — private to this extension instance.
+    private OidcProviderMetadata meta;
+    private OidcStateStore       stateStore;
+    private TokenClient          tokenClient;
+    private JwtValidator         validator;
+    private OidcMiddleware       oidcMw;
+
     public OidcExtension(OidcConfig config) {
         this.config = config;
     }
 
-    @Override
-    public void install(FlashRegistrar app, FlashContext ctx) {
+    // ── Phase 1: services ─────────────────────────────────────────────────────
 
-        // 1. Build the shared HttpClient (optionally with TLS verification disabled)
+    @Override
+    public void provide(FlashContext ctx) {
         HttpClient http = buildHttpClient(config);
 
-        // 2. Discover provider endpoints (blocking; fail fast at startup)
-        OidcProviderMetadata meta;
+        // Discover provider endpoints (blocking; fail fast at startup).
         try {
             meta = DiscoveryClient.fetch(config.issuer(), http);
         } catch (Exception e) {
-            throw new IllegalStateException(
-                    "OIDC discovery failed for issuer: " + config.issuer(), e);
+            throw new IllegalStateException("OIDC discovery failed for issuer: " + config.issuer(), e);
         }
 
-        // 3. JWKS-backed access-token validator
-        JwtValidator validator = new JwtValidator(
-                meta.jwksUri(), config.issuer(), config.clientId(),
-                config.algorithm(), http);
+        validator   = new JwtValidator(meta.jwksUri(), config.issuer(), config.clientId(), config.algorithm(), http);
+        stateStore  = new OidcStateStore();
+        tokenClient = new TokenClient(http, config);
+        oidcMw      = new OidcMiddleware(validator, config, meta, tokenClient);
 
-        // 4. PKCE state store (per extension instance — safe for multi-tenant)
-        OidcStateStore stateStore = new OidcStateStore();
-
-        // 5. Shared token client (injected into middleware for refresh)
-        TokenClient tokenClient = new TokenClient(http, config);
-
-        // 6. Middleware (also exposed in context for manual lambda-route protection)
-        OidcMiddleware oidcMw = new OidcMiddleware(validator, config, meta, tokenClient);
         ctx.provide(OidcMiddleware.class, oidcMw);
         ctx.provide(JwtValidator.class,   validator);
 
+        ctx.addAnnotationProcessor(handlerClass -> {
+            OidcAuthPolicy policy = OidcAuthPolicy.compileFromAnnotations(handlerClass);
+            return policy != null ? List.of(oidcMw.policyMiddleware(policy)) : List.of();
+        });
+    }
+
+    // ── Phase 2: routes ───────────────────────────────────────────────────────
+
+    @Override
+    public void routes(FlashRegistrar<?> app, FlashContext ctx) {
         String prefix = config.routePrefix();
 
         // ── GET {prefix}/login ────────────────────────────────────────────────
@@ -97,11 +105,10 @@ public class OidcExtension implements FlashExtension {
         app.get(prefix + "/login", (req, res) -> {
             String verifier  = PkceUtils.generateVerifier();
             String challenge = PkceUtils.computeChallenge(verifier);
-            String state     = UUID.randomUUID().toString(); // CSRF protection
-            String nonce     = UUID.randomUUID().toString(); // ID token replay protection
+            String state     = UUID.randomUUID().toString();
+            String nonce     = UUID.randomUUID().toString();
 
             String redirect = req.query("redirect");
-            // Only allow relative paths — prevents open-redirect attacks
             if (redirect == null || !redirect.startsWith("/")) redirect = "/";
 
             stateStore.put(state, redirect, verifier, nonce);
@@ -118,7 +125,7 @@ public class OidcExtension implements FlashExtension {
 
             res.redirect(authUrl);
             return null;
-        }).with();
+        });
 
         // ── GET {prefix}/callback ─────────────────────────────────────────────
         // Validates state, exchanges code for tokens, creates session, redirects.
@@ -154,32 +161,24 @@ public class OidcExtension implements FlashExtension {
             }
 
             Map<String, Object> claims = mergeClaims(tokens);
-
             OidcSession session = new OidcSession(
                     UUID.randomUUID().toString(),
-                    tokens.accessToken(),
-                    tokens.idToken(),
-                    tokens.refreshToken(),
-                    Instant.now().plusSeconds(tokens.expiresIn()),
-                    claims
-            );
+                    tokens.accessToken(), tokens.idToken(), tokens.refreshToken(),
+                    Instant.now().plusSeconds(tokens.expiresIn()), claims);
             config.sessionStore().save(session);
 
             res.header("Set-Cookie", sessionCookie(session.id()))
                .redirect(entry.originalUrl());
             return null;
-        }).with();
+        });
 
         // ── POST {prefix}/logout ──────────────────────────────────────────────
-        // Invalidates the local session and redirects to the provider's
-        // end_session_endpoint (with id_token_hint) if available.
+        // Invalidates the local session and redirects to end_session_endpoint.
         app.post(prefix + "/logout", (req, res) -> {
             String sessionId   = OidcMiddleware.cookieValue(req, "oidc_session");
             String idTokenHint = null;
 
             if (sessionId != null) {
-                config.sessionStore().find(sessionId)
-                        .ifPresent(s -> {});          // capture id_token before delete
                 OidcSession session = config.sessionStore().find(sessionId).orElse(null);
                 if (session != null) idTokenHint = session.idToken();
                 config.sessionStore().delete(sessionId);
@@ -199,25 +198,11 @@ public class OidcExtension implements FlashExtension {
                 location = config.postLogoutRedirectUri();
             }
 
-            res.header("Set-Cookie", clearCookie)
-               .redirect(location);
+            res.header("Set-Cookie", clearCookie).redirect(location);
             return null;
-        }).with();
-
-        // 5. Annotation processor for @Authenticated / @RolesAllowed
-        ctx.addAnnotationProcessor(handlerClass -> {
-            RolesAllowed roles = handlerClass.getAnnotation(RolesAllowed.class);
-            if (roles != null) return List.of(oidcMw.rolesMiddleware(roles.value()));
-
-            Authenticated auth = handlerClass.getAnnotation(Authenticated.class);
-            if (auth != null) return List.of(auth.optional()
-                    ? oidcMw.optionalMiddleware()
-                    : oidcMw.authenticatedMiddleware());
-
-            return List.of();
         });
 
-        // Register OpenAPI security scheme if flash-ext-openapi is on the classpath
+        // Register OpenAPI security scheme if flash-ext-openapi is on the classpath.
         try {
             OpenApiIntegration.register(ctx, config, meta);
         } catch (NoClassDefFoundError ignored) {
@@ -225,24 +210,16 @@ public class OidcExtension implements FlashExtension {
         }
     }
 
-    // -- Helpers --------------------------------------------------------------
+    // ── Helpers ───────────────────────────────────────────────────────────────
 
     /**
      * Merges claims from both the access token and the ID token.
-     * The access token carries provider-specific data like {@code realm_access.roles};
-     * the ID token carries standard identity claims (sub, email, name, …).
      * ID token values win on conflict so that verified identity claims are authoritative.
      */
     private static Map<String, Object> mergeClaims(OidcTokenResponse tokens) {
         Map<String, Object> merged = new HashMap<>();
-        // Access token first — provides roles, resource_access, etc.
-        if (tokens.accessToken() != null) {
-            merged.putAll(JwtUtils.parseClaims(tokens.accessToken()));
-        }
-        // ID token overrides — its identity claims (sub, email, name, …) take priority.
-        if (tokens.idToken() != null) {
-            merged.putAll(JwtUtils.parseClaims(tokens.idToken()));
-        }
+        if (tokens.accessToken() != null) merged.putAll(JwtUtils.parseClaims(tokens.accessToken()));
+        if (tokens.idToken()     != null) merged.putAll(JwtUtils.parseClaims(tokens.idToken()));
         return Map.copyOf(merged);
     }
 
@@ -255,22 +232,18 @@ public class OidcExtension implements FlashExtension {
         if (!config.insecureTls()) return HttpClient.newHttpClient();
         try {
             TrustManager[] trustAll = { new X509TrustManager() {
-                public X509Certificate[] getAcceptedIssuers()                          { return new X509Certificate[0]; }
-                public void checkClientTrusted(X509Certificate[] c, String a)          {}
-                public void checkServerTrusted(X509Certificate[] c, String a)          {}
+                public X509Certificate[] getAcceptedIssuers()                 { return new X509Certificate[0]; }
+                public void checkClientTrusted(X509Certificate[] c, String a) {}
+                public void checkServerTrusted(X509Certificate[] c, String a) {}
             }};
-            SSLContext ctx = SSLContext.getInstance("TLS");
-            ctx.init(null, trustAll, new SecureRandom());
-            return HttpClient.newBuilder().sslContext(ctx).build();
+            SSLContext sslCtx = SSLContext.getInstance("TLS");
+            sslCtx.init(null, trustAll, new SecureRandom());
+            return HttpClient.newBuilder().sslContext(sslCtx).build();
         } catch (Exception e) {
             throw new IllegalStateException("Failed to create trust-all SSLContext", e);
         }
     }
 
-    /**
-     * Resolves the configured {@code redirectUri}. If it starts with {@code /},
-     * prepends {@code selfScheme://Host} from the current request.
-     */
     private String absoluteRedirectUri(dev.relism.models.Request req) {
         return absoluteSelf(req, config.redirectUri());
     }
@@ -291,7 +264,6 @@ public class OidcExtension implements FlashExtension {
     /**
      * Loaded lazily so that {@code flash-ext-openapi} classes are only resolved at
      * runtime when {@link dev.relism.ext.openapi.OpenApiSecurityRegistry} is actually on the classpath.
-     * If not present, the {@link NoClassDefFoundError} is caught at the call site.
      */
     private static final class OpenApiIntegration {
         static void register(dev.relism.extension.FlashContext ctx,
@@ -304,9 +276,6 @@ public class OidcExtension implements FlashExtension {
 
                    @Override
                    public java.util.Map<String, Object> schemeDefinition() {
-                       // Declare only the authorizationCode flow so Swagger UI shows
-                       // a single clean "Authorize" dialog instead of expanding every
-                       // grant type from the discovery document.
                        java.util.Map<String, String> scopesMap = new java.util.LinkedHashMap<>();
                        for (String s : config.scopes().split("\\s+")) {
                            if (!s.isBlank()) scopesMap.put(s, s);
@@ -322,19 +291,11 @@ public class OidcExtension implements FlashExtension {
                        return scheme;
                    }
 
-                   @Override
-                   public java.util.List<String> requiredFor(Class<?> handlerClass) {
-                       dev.relism.ext.oidc.RolesAllowed roles =
-                               handlerClass.getAnnotation(dev.relism.ext.oidc.RolesAllowed.class);
-                       if (roles != null) return java.util.Arrays.asList(roles.value());
-
-                       dev.relism.ext.oidc.Authenticated auth =
-                               handlerClass.getAnnotation(dev.relism.ext.oidc.Authenticated.class);
-                       if (auth != null) return java.util.List.of();
-
-                       return null; // not secured by this contributor
-                   }
-               }));
+                    @Override
+                    public java.util.List<String> requiredFor(Class<?> handlerClass) {
+                        return OidcAuthPolicy.openApiScopesFor(handlerClass);
+                    }
+                }));
         }
     }
 }
diff --git a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcMiddleware.java b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcMiddleware.java
index 58952ae..a64c260 100644
--- a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcMiddleware.java
+++ b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcMiddleware.java
@@ -7,6 +7,7 @@ import dev.relism.routing.Middleware;
 import java.net.URLEncoder;
 import java.nio.charset.StandardCharsets;
 import java.time.Instant;
+import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
@@ -15,7 +16,7 @@ import java.util.Optional;
 /**
  * Request-level OIDC middleware. Exposed in the {@link dev.relism.extension.FlashContext}
  * for manual use on lambda routes; injected automatically for handlers annotated with
- * {@link Authenticated} or {@link RolesAllowed}.
+ * {@link Authenticated}, {@link RolesAllowed} or {@link ScopesAllowed}.
  *
  * <p>Resolution order on each request:
  * <ol>
@@ -36,10 +37,14 @@ import java.util.Optional;
  */
 public class OidcMiddleware {
 
+    private static final String BEARER = "Bearer";
+
     private final JwtValidator         validator;
     private final OidcConfig           config;
     private final OidcProviderMetadata meta;
     private final TokenClient          tokenClient;
+    private final String[]             roleClaimPathParts;
+    private final String[][]           scopeClaimPathParts;
 
     OidcMiddleware(JwtValidator validator, OidcConfig config,
                    OidcProviderMetadata meta, TokenClient tokenClient) {
@@ -47,6 +52,8 @@ public class OidcMiddleware {
         this.config      = config;
         this.meta        = meta;
         this.tokenClient = tokenClient;
+        this.roleClaimPathParts = splitClaimPath(config.rolesClaimPath());
+        this.scopeClaimPathParts = splitClaimPaths(config.scopeClaimPaths());
     }
 
     // -- Public API -----------------------------------------------------------
@@ -75,7 +82,7 @@ public class OidcMiddleware {
      * logged in (e.g. showing a username on a landing page).
      *
      * <pre>{@code
-     * app.get("/", handler).with(oidc.optional());
+     * app.get("/", handler, oidc.optional());
      * // Inside handler: ClaimsHolder.user() is non-null iff the user is logged in.
      * }</pre>
      */
@@ -92,15 +99,15 @@ public class OidcMiddleware {
     }
 
     /**
-     * Like {@link #protect()} but also enforces that the caller holds at least one
-     * of the given roles (OR semantics). Roles are extracted via
-     * {@link OidcConfig#rolesClaimPath()}.
+     * Compiled authorization policy path used by annotation-driven mounting.
+     * The policy is immutable and built once at boot.
      */
-    public Middleware requireRole(String... roles) {
+    public Middleware authorize(OidcAuthPolicy policy) {
+        if (policy.optionalAuth()) return optional();
         return next -> (req, res) -> {
             Map<String, Object> claims = resolve(req, res);
             if (claims == null) return null;
-            checkRoles(claims, roles);
+            enforcePolicy(claims, policy, res);
             ClaimsHolder.set(claims);
             try {
                 return next.handle(req, res);
@@ -110,11 +117,40 @@ public class OidcMiddleware {
         };
     }
 
+    /**
+     * Like {@link #protect()} but also enforces that the caller holds at least one
+     * of the given roles (OR semantics). Roles are extracted via
+     * {@link OidcConfig#rolesClaimPath()}.
+     */
+    public Middleware requireRole(String... roles) {
+        return authorize(OidcAuthPolicy.rolesAny(roles));
+    }
+
+    /**
+     * Requires all listed scopes to be present in the token.
+     * Scopes are resolved from configured claim paths (default: {@code scope,scp}).
+     */
+    public Middleware requireScopes(String... scopes) {
+        return authorize(OidcAuthPolicy.scopes(scopes, ScopesAllowed.Match.ALL));
+    }
+
+    /**
+     * Requires at least one of the listed scopes to be present in the token.
+     * Scopes are resolved from configured claim paths (default: {@code scope,scp}).
+     */
+    public Middleware requireAnyScope(String... scopes) {
+        return authorize(OidcAuthPolicy.scopes(scopes, ScopesAllowed.Match.ANY));
+    }
+
     // -- Package-private: AnnotationProcessor hooks ---------------------------
 
     Middleware authenticatedMiddleware()          { return protect(); }
     Middleware optionalMiddleware()               { return optional(); }
     Middleware rolesMiddleware(String[] required) { return requireRole(required); }
+    Middleware scopesMiddleware(String[] required, ScopesAllowed.Match match) {
+        return authorize(OidcAuthPolicy.scopes(required, match));
+    }
+    Middleware policyMiddleware(OidcAuthPolicy policy) { return authorize(policy); }
 
     // -- Internals ------------------------------------------------------------
 
@@ -123,9 +159,14 @@ public class OidcMiddleware {
      * when no valid credentials are present. Used by {@link #optional()}.
      */
     private Map<String, Object> resolveQuiet(Request req) {
-        String auth = req.header("Authorization");
-        if (auth != null && auth.startsWith("Bearer "))
-            return validator.validate(auth.substring(7));
+        String bearerToken = extractBearerToken(req.header("Authorization"));
+        if (bearerToken != null) {
+            try {
+                return validator.validate(bearerToken);
+            } catch (Exception ignored) {
+                return null;
+            }
+        }
 
         String sessionId = cookieValue(req, "oidc_session");
         if (sessionId != null) {
@@ -153,9 +194,15 @@ public class OidcMiddleware {
      */
     private Map<String, Object> resolve(Request req, dev.relism.models.Response res) {
         // 1. Bearer token
-        String auth = req.header("Authorization");
-        if (auth != null && auth.startsWith("Bearer "))
-            return validator.validate(auth.substring(7));
+        String bearerToken = extractBearerToken(req.header("Authorization"));
+        if (bearerToken != null) {
+            try {
+                return validator.validate(bearerToken);
+            } catch (HttpException e) {
+                res.header("WWW-Authenticate", invalidTokenChallenge());
+                throw e;
+            }
+        }
 
         // 2. Session cookie
         String sessionId = cookieValue(req, "oidc_session");
@@ -183,8 +230,10 @@ public class OidcMiddleware {
 
         // 3. No valid credentials
         String accept = req.header("Accept");
-        if (accept != null && accept.contains("application/json"))
+        if (accept != null && accept.contains("application/json")) {
+            res.header("WWW-Authenticate", bearerChallenge());
             throw HttpException.unauthorized();
+        }
 
         // Browser — redirect to login, preserving the original URL in state
         String loginUrl = config.routePrefix() + "/login?redirect="
@@ -209,25 +258,200 @@ public class OidcMiddleware {
         );
     }
 
+    private void enforcePolicy(Map<String, Object> claims, OidcAuthPolicy policy, dev.relism.models.Response res) {
+        checkRoles(claims, policy.requiredRoles());
+        checkScopes(claims, policy.requiredScopes(), policy.scopeMatch(), res);
+    }
+
     private void checkRoles(Map<String, Object> claims, String[] required) {
-        List<String> actual = extractRoles(claims);
-        for (String role : required) {
-            if (actual.contains(role)) return;
-        }
+        if (required.length == 0) return;
+        if (rolesAllowed(claims, required)) return;
         throw HttpException.forbidden();
     }
 
-    @SuppressWarnings("unchecked")
-    private List<String> extractRoles(Map<String, Object> claims) {
-        String[] parts   = config.rolesClaimPath().split("\\.");
-        Object   current = claims;
-        for (String part : parts) {
-            if (!(current instanceof Map<?, ?> m)) return List.of();
-            current = m.get(part);
+    private void checkScopes(Map<String, Object> claims, String[] required, ScopesAllowed.Match match,
+                             dev.relism.models.Response res) {
+        if (required.length == 0) return;
+        if (scopesAllowed(claims, required, match)) return;
+        res.header("WWW-Authenticate", insufficientScopeChallenge(required));
+        throw HttpException.forbidden();
+    }
+
+    static String extractBearerToken(String authorizationHeader) {
+        if (authorizationHeader == null) return null;
+        int len = authorizationHeader.length();
+        int start = 0;
+        while (start < len && Character.isWhitespace(authorizationHeader.charAt(start))) start++;
+        int schemeEnd = start + BEARER.length();
+        if (schemeEnd > len || !authorizationHeader.regionMatches(true, start, BEARER, 0, BEARER.length())) {
+            return null;
         }
-        if (current instanceof List<?> list)
-            return list.stream().map(Object::toString).toList();
-        return List.of();
+        if (schemeEnd == len || !Character.isWhitespace(authorizationHeader.charAt(schemeEnd))) {
+            return null;
+        }
+        int tokenStart = schemeEnd;
+        while (tokenStart < len && Character.isWhitespace(authorizationHeader.charAt(tokenStart))) tokenStart++;
+        if (tokenStart >= len) return null;
+        int tokenEnd = len;
+        while (tokenEnd > tokenStart && Character.isWhitespace(authorizationHeader.charAt(tokenEnd - 1))) tokenEnd--;
+        return tokenEnd > tokenStart ? authorizationHeader.substring(tokenStart, tokenEnd) : null;
+    }
+
+    String bearerChallenge() {
+        return BEARER + " realm=\"" + quoted(config.schemeName()) + "\"";
+    }
+
+    String invalidTokenChallenge() {
+        return bearerChallenge() + ", error=\"invalid_token\"";
+    }
+
+    String insufficientScopeChallenge(String[] requiredScopes) {
+        return bearerChallenge() + ", error=\"insufficient_scope\", scope=\""
+                + quoted(spaceDelimited(requiredScopes)) + "\"";
+    }
+
+    private static String spaceDelimited(String[] values) {
+        if (values == null || values.length == 0) return "";
+        StringBuilder sb = new StringBuilder();
+        for (int i = 0; i < values.length; i++) {
+            if (i > 0) sb.append(' ');
+            sb.append(values[i]);
+        }
+        return sb.toString();
+    }
+
+    private static String quoted(String value) {
+        StringBuilder out = new StringBuilder(value.length() + 8);
+        for (int i = 0; i < value.length(); i++) {
+            char c = value.charAt(i);
+            if (c == '"' || c == '\\') out.append('\\');
+            out.append(c);
+        }
+        return out.toString();
+    }
+
+    boolean rolesAllowed(Map<String, Object> claims, String[] required) {
+        Object actual = valueAtPath(claims, roleClaimPathParts);
+        if (actual == null) return false;
+        for (String role : required) {
+            if (containsToken(actual, role)) return true;
+        }
+        return false;
+    }
+
+    boolean scopesAllowed(Map<String, Object> claims, String[] required, ScopesAllowed.Match match) {
+        if (match == ScopesAllowed.Match.ALL) {
+            for (String scope : required) {
+                if (!hasScope(claims, scope)) return false;
+            }
+            return true;
+        }
+        for (String scope : required) {
+            if (hasScope(claims, scope)) return true;
+        }
+        return false;
+    }
+
+    private boolean hasScope(Map<String, Object> claims, String scope) {
+        for (String[] pathParts : scopeClaimPathParts) {
+            Object value = valueAtPath(claims, pathParts);
+            if (value != null && containsToken(value, scope)) return true;
+        }
+        return false;
+    }
+
+    private static Object valueAtPath(Map<String, Object> claims, String[] pathParts) {
+        Object current = claims;
+        for (String part : pathParts) {
+            if (!(current instanceof Map<?, ?> map)) return null;
+            current = map.get(part);
+            if (current == null) return null;
+        }
+        return current;
+    }
+
+    private static boolean containsToken(Object source, String token) {
+        if (source instanceof String s) return containsDelimitedToken(s, token);
+        if (source instanceof List<?> list) {
+            for (Object item : list) {
+                if (item == null) continue;
+                if (tokenEquals(item.toString(), token)) return true;
+            }
+            return false;
+        }
+        if (source instanceof Object[] arr) {
+            for (Object item : arr) {
+                if (item == null) continue;
+                if (tokenEquals(item.toString(), token)) return true;
+            }
+            return false;
+        }
+        return tokenEquals(source.toString(), token);
+    }
+
+    private static boolean containsDelimitedToken(String value, String token) {
+        int len = value.length();
+        int i = 0;
+        while (i < len) {
+            while (i < len && isScopeDelimiter(value.charAt(i))) i++;
+            int start = i;
+            while (i < len && !isScopeDelimiter(value.charAt(i))) i++;
+            int end = i;
+            if (end > start && end - start == token.length() && value.regionMatches(start, token, 0, token.length())) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    private static boolean tokenEquals(String value, String token) {
+        int start = 0;
+        int end = value.length();
+        while (start < end && Character.isWhitespace(value.charAt(start))) start++;
+        while (end > start && Character.isWhitespace(value.charAt(end - 1))) end--;
+        return end - start == token.length() && value.regionMatches(start, token, 0, token.length());
+    }
+
+    private static boolean isScopeDelimiter(char c) {
+        return c == ' ' || c == '\t' || c == '\n' || c == '\r' || c == ',';
+    }
+
+    private static String[] splitClaimPath(String path) {
+        if (path == null || path.isBlank()) {
+            throw new IllegalStateException("OIDC claim path cannot be blank");
+        }
+        List<String> parts = new ArrayList<>(4);
+        int start = 0;
+        int len = path.length();
+        for (int i = 0; i <= len; i++) {
+            if (i == len || path.charAt(i) == '.') {
+                String p = path.substring(start, i).trim();
+                if (!p.isEmpty()) parts.add(p);
+                start = i + 1;
+            }
+        }
+        if (parts.isEmpty()) {
+            throw new IllegalStateException("OIDC claim path cannot be blank");
+        }
+        return parts.toArray(String[]::new);
+    }
+
+    private static String[][] splitClaimPaths(String paths) {
+        String source = (paths == null || paths.isBlank()) ? "scope,scp" : paths;
+        List<String[]> out = new ArrayList<>(4);
+        int start = 0;
+        int len = source.length();
+        for (int i = 0; i <= len; i++) {
+            if (i == len || source.charAt(i) == ',') {
+                String raw = source.substring(start, i).trim();
+                if (!raw.isEmpty()) out.add(splitClaimPath(raw));
+                start = i + 1;
+            }
+        }
+        if (out.isEmpty()) {
+            return new String[][]{ splitClaimPath("scope"), splitClaimPath("scp") };
+        }
+        return out.toArray(String[][]::new);
     }
 
     private static Map<String, Object> mergeRefreshedClaims(OidcTokenResponse tokens, OidcSession old) {
@@ -246,10 +470,20 @@ public class OidcMiddleware {
     static String cookieValue(Request req, String name) {
         String header = req.header("Cookie");
         if (header == null || header.isBlank()) return null;
-        for (String part : header.split(";")) {
-            int eq = part.indexOf('=');
-            if (eq > 0 && part.substring(0, eq).strip().equals(name))
-                return part.substring(eq + 1).strip();
+        int len   = header.length();
+        int start = 0;
+        while (start < len) {
+            int semi = header.indexOf(';', start);
+            int end  = semi < 0 ? len : semi;
+            int eq   = header.indexOf('=', start);
+            if (eq > start && eq < end) {
+                int ns = start, ne = eq;
+                while (ns < ne && header.charAt(ns)   == ' ') ns++;
+                while (ne > ns && header.charAt(ne-1) == ' ') ne--;
+                if (ne - ns == name.length() && header.regionMatches(ns, name, 0, name.length()))
+                    return header.substring(eq + 1, end).strip();
+            }
+            start = end + 1;
         }
         return null;
     }
diff --git a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcUser.java b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcUser.java
index 2d73f2e..e8382b1 100644
--- a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcUser.java
+++ b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcUser.java
@@ -2,6 +2,7 @@ package dev.relism.ext.oidc;
 
 import java.util.List;
 import java.util.Map;
+import java.util.ArrayList;
 
 /**
  * Type-safe view over the JWT claims stored in {@link ClaimsHolder}.
@@ -16,7 +17,7 @@ import java.util.Map;
  * // Lambda route (OidcMiddleware injected):
  * app.get("/api/whoami", (req, res) -> {
  *     OidcUser u = ClaimsHolder.user();
- *     return Map.of("sub", u.sub(), "email", u.email(), "roles", u.roles());
+ *     return Map.of("sub", u.sub(), "email", u.email(), "roles", u.roles("realm_access.roles"), "scopes", u.scopes());
  * }, oidcMw.protect());
  *
  * // Class-based handler (currentUser is the DB entity; oidcUser() for raw claims):
@@ -80,6 +81,67 @@ public final class OidcUser {
         return roles(claimPath).contains(role);
     }
 
+    // -- Scopes ---------------------------------------------------------------
+
+    /**
+     * Resolves OAuth2 scopes from standard OIDC/OAuth claims using fallback order:
+     * {@code scope} then {@code scp}. Supports both space-separated string and list forms.
+     */
+    public List<String> scopes() {
+        return scopes("scope,scp");
+    }
+
+    /**
+     * Resolves scopes from comma-separated claim paths (example: {@code "scope,scp,permissions.scopes"}).
+     */
+    public List<String> scopes(String claimPaths) {
+        List<String> out = new ArrayList<>();
+        for (String[] path : splitClaimPaths(claimPaths)) {
+            Object value = valueAtPath(path);
+            if (value == null) continue;
+            if (value instanceof String s) {
+                appendDelimitedTokens(out, s);
+                continue;
+            }
+            if (value instanceof List<?> list) {
+                for (Object item : list) {
+                    if (item == null) continue;
+                    String token = item.toString().trim();
+                    if (!token.isEmpty()) out.add(token);
+                }
+                continue;
+            }
+            String token = value.toString().trim();
+            if (!token.isEmpty()) out.add(token);
+        }
+        return out.isEmpty() ? List.of() : List.copyOf(out);
+    }
+
+    /** Returns {@code true} if the user has {@code scope}, searching default claim paths {@code scope,scp}. */
+    public boolean hasScope(String scope) {
+        return hasScope("scope,scp", scope);
+    }
+
+    /** Returns {@code true} if the user has {@code scope} in any of {@code claimPaths}. */
+    public boolean hasScope(String claimPaths, String scope) {
+        if (scope == null || scope.isBlank()) return false;
+        String target = scope.trim();
+        for (String[] path : splitClaimPaths(claimPaths)) {
+            Object value = valueAtPath(path);
+            if (value == null) continue;
+            if (value instanceof String s && containsDelimitedToken(s, target)) return true;
+            if (value instanceof List<?> list) {
+                for (Object item : list) {
+                    if (item == null) continue;
+                    if (target.equals(item.toString().trim())) return true;
+                }
+                continue;
+            }
+            if (target.equals(value.toString().trim())) return true;
+        }
+        return false;
+    }
+
     // ── Arbitrary claim access ─────────────────────────────────────────────
 
     /**
@@ -103,4 +165,73 @@ public final class OidcUser {
         Object v = claims.get(key);
         return v != null ? v.toString() : null;
     }
+
+    private Object valueAtPath(String[] path) {
+        Object current = claims;
+        for (String part : path) {
+            if (!(current instanceof Map<?, ?> m)) return null;
+            current = m.get(part);
+            if (current == null) return null;
+        }
+        return current;
+    }
+
+    private static String[][] splitClaimPaths(String claimPaths) {
+        String source = (claimPaths == null || claimPaths.isBlank()) ? "scope,scp" : claimPaths;
+        List<String[]> out = new ArrayList<>(4);
+        int start = 0;
+        int len = source.length();
+        for (int i = 0; i <= len; i++) {
+            if (i == len || source.charAt(i) == ',') {
+                String raw = source.substring(start, i).trim();
+                if (!raw.isEmpty()) out.add(splitPath(raw));
+                start = i + 1;
+            }
+        }
+        return out.isEmpty() ? new String[][]{ splitPath("scope"), splitPath("scp") } : out.toArray(String[][]::new);
+    }
+
+    private static String[] splitPath(String path) {
+        List<String> out = new ArrayList<>(4);
+        int start = 0;
+        int len = path.length();
+        for (int i = 0; i <= len; i++) {
+            if (i == len || path.charAt(i) == '.') {
+                String raw = path.substring(start, i).trim();
+                if (!raw.isEmpty()) out.add(raw);
+                start = i + 1;
+            }
+        }
+        return out.isEmpty() ? new String[]{ path } : out.toArray(String[]::new);
+    }
+
+    private static void appendDelimitedTokens(List<String> target, String source) {
+        int len = source.length();
+        int i = 0;
+        while (i < len) {
+            while (i < len && isDelimiter(source.charAt(i))) i++;
+            int start = i;
+            while (i < len && !isDelimiter(source.charAt(i))) i++;
+            if (i > start) target.add(source.substring(start, i));
+        }
+    }
+
+    private static boolean containsDelimitedToken(String source, String token) {
+        int len = source.length();
+        int i = 0;
+        while (i < len) {
+            while (i < len && isDelimiter(source.charAt(i))) i++;
+            int start = i;
+            while (i < len && !isDelimiter(source.charAt(i))) i++;
+            int end = i;
+            if (end > start && end - start == token.length() && source.regionMatches(start, token, 0, token.length())) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    private static boolean isDelimiter(char c) {
+        return c == ' ' || c == '\t' || c == '\n' || c == '\r' || c == ',';
+    }
 }
diff --git a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/ScopesAllowed.java b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/ScopesAllowed.java
new file mode 100644
index 0000000..5213e6d
--- /dev/null
+++ b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/ScopesAllowed.java
@@ -0,0 +1,45 @@
+package dev.relism.ext.oidc;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Restricts a handler to callers whose token carries the required OAuth2 scopes.
+ * Authentication is implicitly required.
+ *
+ * <p>Scopes are resolved from the configured claim paths in
+ * {@link OidcConfig#scopeClaimPaths()} (default: {@code "scope,scp"}) and support
+ * both standard formats:
+ * <ul>
+ *   <li>{@code scope}: space-separated string</li>
+ *   <li>{@code scp}: string list (or string)</li>
+ * </ul>
+ *
+ * <pre>{@code
+ * @Route(method = HttpMethod.GET, path = "/api/orders")
+ * @ScopesAllowed("orders:read")
+ * public class ListOrders extends JacksonHandler { ... }
+ *
+ * @Route(method = HttpMethod.POST, path = "/api/orders")
+ * @ScopesAllowed(value = {"orders:write", "payments:write"}, match = ScopesAllowed.Match.ANY)
+ * public class CreateOrder extends JacksonHandler { ... }
+ * }</pre>
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+public @interface ScopesAllowed {
+    /** Required scopes. */
+    String[] value();
+
+    /** Matching mode for {@link #value()}. */
+    Match match() default Match.ALL;
+
+    enum Match {
+        /** Any one required scope is sufficient. */
+        ANY,
+        /** All required scopes must be present. */
+        ALL
+    }
+}
diff --git a/flash-extensions/flash-ext-oidc/src/test/java/dev/relism/ext/oidc/OidcAuthPolicyTest.java b/flash-extensions/flash-ext-oidc/src/test/java/dev/relism/ext/oidc/OidcAuthPolicyTest.java
new file mode 100644
index 0000000..0223937
--- /dev/null
+++ b/flash-extensions/flash-ext-oidc/src/test/java/dev/relism/ext/oidc/OidcAuthPolicyTest.java
@@ -0,0 +1,94 @@
+package dev.relism.ext.oidc;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+class OidcAuthPolicyTest {
+
+    static class PlainHandler {}
+
+    @Authenticated
+    static class AuthenticatedHandler {}
+
+    @Authenticated(optional = true)
+    static class OptionalHandler {}
+
+    @RolesAllowed({"admin", " editor ", "admin"})
+    static class RolesHandler {}
+
+    @ScopesAllowed(value = {"orders:write", " payments:write ", "orders:write"}, match = ScopesAllowed.Match.ANY)
+    static class ScopesHandler {}
+
+    @Authenticated
+    @RolesAllowed("admin")
+    @ScopesAllowed(value = {"orders:read", "payments:read"}, match = ScopesAllowed.Match.ALL)
+    static class CombinedHandler {}
+
+    @Authenticated(optional = true)
+    @ScopesAllowed("orders:read")
+    static class InvalidOptionalHandler {}
+
+    @Test
+    void compileFromAnnotations_noSecurityAnnotations_returnsNull() {
+        assertNull(OidcAuthPolicy.compileFromAnnotations(PlainHandler.class));
+    }
+
+    @Test
+    void compileFromAnnotations_authenticated_createsRequiredAuthPolicy() {
+        OidcAuthPolicy policy = OidcAuthPolicy.compileFromAnnotations(AuthenticatedHandler.class);
+        assertNotNull(policy);
+        assertFalse(policy.optionalAuth());
+        assertEquals(0, policy.requiredRoles().length);
+        assertEquals(0, policy.requiredScopes().length);
+    }
+
+    @Test
+    void compileFromAnnotations_optionalAuth_createsOptionalPolicy() {
+        OidcAuthPolicy policy = OidcAuthPolicy.compileFromAnnotations(OptionalHandler.class);
+        assertNotNull(policy);
+        assertTrue(policy.optionalAuth());
+    }
+
+    @Test
+    void compileFromAnnotations_rolesAndScopes_areNormalizedAndMerged() {
+        OidcAuthPolicy policy = OidcAuthPolicy.compileFromAnnotations(CombinedHandler.class);
+        assertNotNull(policy);
+        assertFalse(policy.optionalAuth());
+        assertArrayEquals(new String[]{"admin"}, policy.requiredRoles());
+        assertArrayEquals(new String[]{"orders:read", "payments:read"}, policy.requiredScopes());
+        assertEquals(ScopesAllowed.Match.ALL, policy.scopeMatch());
+    }
+
+    @Test
+    void compileFromAnnotations_scopesAny_preservesMatchModeAndDedupes() {
+        OidcAuthPolicy policy = OidcAuthPolicy.compileFromAnnotations(ScopesHandler.class);
+        assertNotNull(policy);
+        assertArrayEquals(new String[]{"orders:write", "payments:write"}, policy.requiredScopes());
+        assertEquals(ScopesAllowed.Match.ANY, policy.scopeMatch());
+    }
+
+    @Test
+    void compileFromAnnotations_optionalCannotBeCombinedWithConstraints() {
+        assertThrows(IllegalStateException.class,
+                () -> OidcAuthPolicy.compileFromAnnotations(InvalidOptionalHandler.class));
+    }
+
+    @Test
+    void openApiScopesFor_returnsScopesWhenPresent() {
+        assertEquals(List.of("orders:write", "payments:write"),
+                OidcAuthPolicy.openApiScopesFor(ScopesHandler.class));
+    }
+
+    @Test
+    void openApiScopesFor_rolesOnly_returnsEmptyList() {
+        assertEquals(List.of(), OidcAuthPolicy.openApiScopesFor(RolesHandler.class));
+    }
+
+    @Test
+    void openApiScopesFor_noSecurity_returnsNull() {
+        assertNull(OidcAuthPolicy.openApiScopesFor(PlainHandler.class));
+    }
+}
diff --git a/flash-extensions/flash-ext-oidc/src/test/java/dev/relism/ext/oidc/OidcMiddlewareAuthzTest.java b/flash-extensions/flash-ext-oidc/src/test/java/dev/relism/ext/oidc/OidcMiddlewareAuthzTest.java
new file mode 100644
index 0000000..588777c
--- /dev/null
+++ b/flash-extensions/flash-ext-oidc/src/test/java/dev/relism/ext/oidc/OidcMiddlewareAuthzTest.java
@@ -0,0 +1,72 @@
+package dev.relism.ext.oidc;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+class OidcMiddlewareAuthzTest {
+
+    private static OidcMiddleware middleware(String rolesPath, String scopePaths) {
+        OidcConfig cfg = OidcConfig.builder("https://idp.example.com", "client", "secret", "/auth/callback")
+                .rolesClaimPath(rolesPath)
+                .scopeClaimPaths(scopePaths)
+                .build();
+        return new OidcMiddleware(null, cfg, null, null);
+    }
+
+    @Test
+    void rolesAllowed_readsConfiguredNestedClaimPath() {
+        OidcMiddleware mw = middleware("realm_access.roles", "scope,scp");
+        Map<String, Object> claims = Map.of("realm_access", Map.of("roles", List.of("user", "admin")));
+
+        assertTrue(mw.rolesAllowed(claims, new String[]{"admin"}));
+        assertFalse(mw.rolesAllowed(claims, new String[]{"ops"}));
+    }
+
+    @Test
+    void scopesAllowed_all_requiresEveryScope() {
+        OidcMiddleware mw = middleware("roles", "scope,scp");
+        Map<String, Object> claims = Map.of("scope", "openid profile orders:read");
+
+        assertTrue(mw.scopesAllowed(claims, new String[]{"openid", "orders:read"}, ScopesAllowed.Match.ALL));
+        assertFalse(mw.scopesAllowed(claims, new String[]{"openid", "orders:write"}, ScopesAllowed.Match.ALL));
+    }
+
+    @Test
+    void scopesAllowed_any_acceptsAnyConfiguredScopeSource() {
+        OidcMiddleware mw = middleware("roles", "scope,scp,permissions.scopes");
+        Map<String, Object> claims = Map.of(
+                "scp", List.of("payments:write"),
+                "permissions", Map.of("scopes", "orders:approve")
+        );
+
+        assertTrue(mw.scopesAllowed(claims, new String[]{"orders:approve", "orders:read"}, ScopesAllowed.Match.ANY));
+        assertTrue(mw.scopesAllowed(claims, new String[]{"payments:write"}, ScopesAllowed.Match.ANY));
+        assertFalse(mw.scopesAllowed(claims, new String[]{"unknown"}, ScopesAllowed.Match.ANY));
+    }
+
+    @Test
+    void extractBearerToken_acceptsCaseInsensitiveBearerAndTrimsSpaces() {
+        assertEquals("abc.def.ghi", OidcMiddleware.extractBearerToken("Bearer abc.def.ghi"));
+        assertEquals("abc", OidcMiddleware.extractBearerToken("   bearer    abc   "));
+        assertNull(OidcMiddleware.extractBearerToken("Basic Zm9vOmJhcg=="));
+        assertNull(OidcMiddleware.extractBearerToken("Bearer"));
+    }
+
+    @Test
+    void bearerChallenge_containsRealmAndRfcErrors() {
+        OidcMiddleware mw = middleware("roles", "scope,scp");
+
+        String basic = mw.bearerChallenge();
+        String invalid = mw.invalidTokenChallenge();
+        String insufficient = mw.insufficientScopeChallenge(new String[]{"orders:read", "payments:write"});
+
+        assertTrue(basic.startsWith("Bearer realm=\""));
+        assertTrue(invalid.contains("error=\"invalid_token\""));
+        assertTrue(insufficient.contains("error=\"insufficient_scope\""));
+        assertTrue(insufficient.contains("scope=\"orders:read payments:write\""));
+    }
+}
diff --git a/flash-extensions/flash-ext-oidc/src/test/java/dev/relism/ext/oidc/OidcUserScopesTest.java b/flash-extensions/flash-ext-oidc/src/test/java/dev/relism/ext/oidc/OidcUserScopesTest.java
new file mode 100644
index 0000000..5657000
--- /dev/null
+++ b/flash-extensions/flash-ext-oidc/src/test/java/dev/relism/ext/oidc/OidcUserScopesTest.java
@@ -0,0 +1,47 @@
+package dev.relism.ext.oidc;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+class OidcUserScopesTest {
+
+    @Test
+    void scopes_readsStandardScopeString() {
+        OidcUser user = new OidcUser(Map.of("scope", "openid profile orders:read"));
+
+        assertEquals(List.of("openid", "profile", "orders:read"), user.scopes());
+        assertTrue(user.hasScope("orders:read"));
+        assertFalse(user.hasScope("orders:write"));
+    }
+
+    @Test
+    void scopes_fallsBackToScpArray() {
+        OidcUser user = new OidcUser(Map.of("scp", List.of("orders:write", "payments:write")));
+
+        assertEquals(List.of("orders:write", "payments:write"), user.scopes());
+        assertTrue(user.hasScope("payments:write"));
+    }
+
+    @Test
+    void scopes_supportsCustomClaimPaths() {
+        OidcUser user = new OidcUser(Map.of("permissions", Map.of("scopes", List.of("a", "b"))));
+
+        assertEquals(List.of("a", "b"), user.scopes("permissions.scopes"));
+        assertTrue(user.hasScope("permissions.scopes", "a"));
+        assertFalse(user.hasScope("permissions.scopes", "x"));
+    }
+
+    @Test
+    void scopes_combinesMultipleClaimPathsInOrder() {
+        OidcUser user = new OidcUser(Map.of(
+                "scope", "openid",
+                "scp", List.of("profile", "orders:read")
+        ));
+
+        assertEquals(List.of("openid", "profile", "orders:read"), user.scopes("scope,scp"));
+    }
+}
diff --git a/flash-extensions/flash-ext-openapi/README.md b/flash-extensions/flash-ext-openapi/README.md
index 5994374..25f95c3 100644
--- a/flash-extensions/flash-ext-openapi/README.md
+++ b/flash-extensions/flash-ext-openapi/README.md
@@ -15,8 +15,9 @@ from class-based handlers annotated with `@ApiOperation`.
 
 ## Dependencies
 
-Requires `flash-ext-jackson` installed **before** this extension (shares its `ObjectMapper` from context).
-If `flash-ext-oidc` is installed **after** this extension, OIDC security schemes are injected automatically.
+Requires `flash-ext-jackson` (shares its `ObjectMapper` from context).
+If `flash-ext-oidc` is also installed, OIDC security schemes are injected automatically.
+Install order is irrelevant — the two-phase extension model handles dependency ordering.
 
 ```xml
 <dependency>
@@ -51,7 +52,7 @@ All annotations target the **handler class** (`@Target(ElementType.TYPE)`).
 ### @ApiOperation
 
 ```java
-@Route(method = HttpMethod.GET, path = "/api/blogs")
+@GET("/api/blogs")
 @ApiOperation(
     summary     = "List all blogs",
     description = "Returns a paginated list of published blog posts.",
@@ -98,7 +99,7 @@ Repeatable — declare query, path, header, or cookie parameters explicitly.
 public class GetBlog extends JacksonHandler { ... }
 ```
 
-> Path parameters declared in `@Route(path = "/blogs/{id}")` are extracted and added automatically
+> Path parameters in the route (e.g. `@GET("/blogs/{id}")` or `@Route(path = "/blogs/{id}")`) are extracted automatically
 > as required path parameters — you only need `@ApiParam` for query / header / cookie params.
 
 `@ApiParam` is repeatable. If you prefer grouping them, `@ApiParams({ @ApiParam(...), @ApiParam(...) })` is
diff --git a/flash-extensions/flash-ext-openapi/pom.xml b/flash-extensions/flash-ext-openapi/pom.xml
index 448ade5..aa85872 100644
--- a/flash-extensions/flash-ext-openapi/pom.xml
+++ b/flash-extensions/flash-ext-openapi/pom.xml
@@ -15,7 +15,7 @@
     <dependencies>
         <dependency>
             <groupId>dev.relism</groupId>
-            <artifactId>flash-ext-jackson</artifactId>
+            <artifactId>flash</artifactId>
         </dependency>
         <dependency>
             <groupId>com.fasterxml.jackson.dataformat</groupId>
diff --git a/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiOperation.java b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiOperation.java
index 8cb4c93..3817cb0 100644
--- a/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiOperation.java
+++ b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiOperation.java
@@ -10,7 +10,7 @@ import java.lang.annotation.Target;
  * Picked up by {@link OpenApiExtension} via {@link FlashApp#register}.
  *
  * <pre>{@code
- * @Route(method = HttpMethod.GET, path = "/api/blogs")
+ * @GET("/api/blogs")
  * @ApiOperation(summary = "List all blogs", tags = {"blogs"})
  * public class ListBlogs extends JacksonHandler { ... }
  * }</pre>
diff --git a/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiResponse.java b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiResponse.java
index 282e1b6..773506b 100644
--- a/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiResponse.java
+++ b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiResponse.java
@@ -20,4 +20,5 @@ public @interface ApiResponse {
     int    status();
     String description() default "";
     Class<?> schema()    default Void.class;
+    boolean useReturnType() default false;
 }
diff --git a/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ArraySchema.java b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ArraySchema.java
new file mode 100644
index 0000000..93253a8
--- /dev/null
+++ b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ArraySchema.java
@@ -0,0 +1,16 @@
+package dev.relism.ext.openapi;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/** Optional array-specific schema metadata. */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.FIELD, ElementType.METHOD})
+public @interface ArraySchema {
+    Class<?> itemClass() default Void.class;
+    boolean uniqueItems() default false;
+    int minItems() default -1;
+    int maxItems() default -1;
+}
diff --git a/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiBuilder.java b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiBuilder.java
index 499602e..4b7bd26 100644
--- a/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiBuilder.java
+++ b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiBuilder.java
@@ -1,68 +1,65 @@
 package dev.relism.ext.openapi;
 
+import com.fasterxml.jackson.annotation.JsonIgnore;
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.annotation.JsonProperty.Access;
 import dev.relism.routing.Route;
 
+import java.lang.reflect.*;
+import java.time.*;
 import java.util.*;
 
 /**
- * Accumulates OpenAPI 3.0 operations and builds the spec document as a plain
- * {@code Map} for Jackson to serialize. Operations are added at registration time
- * via {@link OpenApiExtension}'s {@link dev.relism.AnnotationProcessor}.
+ * OpenAPI document assembler.
+ *
+ * Collects operation metadata at route registration time and renders an OpenAPI 3.0.3 map.
+ * Response schemas are resolved automatically into components.schemas.
  */
-public class OpenApiBuilder {
+public final class OpenApiBuilder {
 
-    private String title   = "API";
+    private String title = "API";
     private String version = "1.0.0";
     private String description = "";
 
     private final Map<String, Map<String, Object>> paths = new LinkedHashMap<>();
     private final Map<String, Map<String, Class<?>>> operationHandlers = new LinkedHashMap<>();
+    private final SchemaRegistry schemas = new SchemaRegistry();
     private OpenApiSecurityRegistry securityRegistry;
+    // Build cache: OpenAPI is rendered only when the document revision changes.
+    private int revision;
+    private int builtRevision = -1;
+    private Map<String, Object> cachedSpec;
 
-    // ── Configuration ─────────────────────────────────────────────────────────
-
-    public OpenApiBuilder title(String title)             { this.title = title; return this; }
-    public OpenApiBuilder version(String version)         { this.version = version; return this; }
+    public OpenApiBuilder title(String title) { this.title = title; return this; }
+    public OpenApiBuilder version(String version) { this.version = version; return this; }
     public OpenApiBuilder description(String description) { this.description = description; return this; }
+    void setSecurityRegistry(OpenApiSecurityRegistry registry) { this.securityRegistry = registry; }
 
-    void setSecurityRegistry(OpenApiSecurityRegistry registry) {
-        this.securityRegistry = registry;
-    }
-
-    // ── Operation registration ────────────────────────────────────────────────
-
-    /**
-     * Adds an operation derived from the handler's {@link Route}, {@link ApiOperation},
-     * {@link ApiResponse}, and {@link ApiParam} annotations.
-     */
     public void addOperation(Route route, ApiOperation op, Class<?> handlerClass) {
-        String path   = normalizePath(route.path());
-        String method = route.method().name().toLowerCase();
+        String path = normalizePath(route.path());
+        String method = route.method().name().toLowerCase(Locale.ROOT);
 
-        Map<String, Object> pathItem  = paths.computeIfAbsent(path, k -> new LinkedHashMap<>());
         Map<String, Object> operation = new LinkedHashMap<>();
-
-        if (!op.operationId().isEmpty())  operation.put("operationId", op.operationId());
-        if (!op.summary().isEmpty())      operation.put("summary", op.summary());
-        if (!op.description().isEmpty())  operation.put("description", op.description());
-        if (op.tags().length > 0)         operation.put("tags", Arrays.asList(op.tags()));
-        if (op.deprecated())              operation.put("deprecated", true);
+        if (!op.operationId().isEmpty()) operation.put("operationId", op.operationId());
+        if (!op.summary().isEmpty()) operation.put("summary", op.summary());
+        if (!op.description().isEmpty()) operation.put("description", op.description());
+        if (op.tags().length > 0) operation.put("tags", Arrays.asList(op.tags()));
+        if (op.deprecated()) operation.put("deprecated", true);
 
         buildParameters(operation, handlerClass, route);
         buildResponses(operation, handlerClass);
 
-        pathItem.put(method, operation);
+        paths.computeIfAbsent(path, k -> new LinkedHashMap<>()).put(method, operation);
         operationHandlers.computeIfAbsent(path, k -> new LinkedHashMap<>()).put(method, handlerClass);
+        revision++;
     }
 
-    // ── Spec build ────────────────────────────────────────────────────────────
-
-    /**
-     * Returns the complete OpenAPI 3.0.3 spec as a plain map ready for JSON
-     * serialization. Called on each request to {@code /openapi.json} so that
-     * handlers registered after the extension is installed are included.
-     */
     public Map<String, Object> build() {
+        int r = revision;
+        Map<String, Object> cached = cachedSpec;
+        if (cached != null && builtRevision == r) return cached;
+
         Map<String, Object> info = new LinkedHashMap<>();
         info.put("title", title);
         info.put("version", version);
@@ -71,8 +68,6 @@ public class OpenApiBuilder {
         List<OpenApiSecurityContributor> contributors = securityRegistry != null
                 ? securityRegistry.contributors() : List.of();
 
-        // Build paths with security injected per-operation (fresh copy each time so
-        // repeated calls don't accumulate duplicate security entries)
         Map<String, Object> renderedPaths = new LinkedHashMap<>();
         for (var pathEntry : paths.entrySet()) {
             Map<String, Object> renderedPathItem = new LinkedHashMap<>();
@@ -80,7 +75,7 @@ public class OpenApiBuilder {
             for (var methodEntry : pathEntry.getValue().entrySet()) {
                 @SuppressWarnings("unchecked")
                 Map<String, Object> original = (Map<String, Object>) methodEntry.getValue();
-                Map<String, Object> op = new LinkedHashMap<>(original); // shallow copy
+                Map<String, Object> op = new LinkedHashMap<>(original);
                 Class<?> handler = handlers.get(methodEntry.getKey());
                 if (handler != null && !contributors.isEmpty()) {
                     List<Map<String, List<String>>> security = buildOperationSecurity(contributors, handler);
@@ -96,23 +91,24 @@ public class OpenApiBuilder {
         spec.put("info", info);
         spec.put("paths", renderedPaths);
 
+        Map<String, Object> components = new LinkedHashMap<>();
+        Map<String, Object> renderedSchemas = schemas.render();
+        if (!renderedSchemas.isEmpty()) components.put("schemas", renderedSchemas);
         if (!contributors.isEmpty()) {
-            Map<String, Object> schemes = new LinkedHashMap<>();
-            for (OpenApiSecurityContributor c : contributors) {
-                schemes.put(c.schemeName(), c.schemeDefinition());
-            }
-            spec.put("components", Map.of("securitySchemes", schemes));
+            Map<String, Object> securitySchemes = new LinkedHashMap<>();
+            for (OpenApiSecurityContributor c : contributors) securitySchemes.put(c.schemeName(), c.schemeDefinition());
+            components.put("securitySchemes", securitySchemes);
         }
+        if (!components.isEmpty()) spec.put("components", components);
 
+        cachedSpec = spec;
+        builtRevision = r;
         return spec;
     }
 
-    // ── Internals ─────────────────────────────────────────────────────────────
-
     private void buildParameters(Map<String, Object> op, Class<?> cls, Route route) {
         List<Map<String, Object>> params = new ArrayList<>();
 
-        // Path params from @Route path — add them automatically as required
         String path = route.path();
         int i = 0;
         while (i < path.length()) {
@@ -121,18 +117,16 @@ public class OpenApiBuilder {
             int close = path.indexOf('}', open);
             if (close < 0) break;
             String name = path.substring(open + 1, close);
-            Map<String, Object> p = new LinkedHashMap<>();
-            p.put("name", name);
-            p.put("in", "path");
-            p.put("required", true);
-            p.put("schema", Map.of("type", "string"));
-            params.add(p);
+            params.add(new LinkedHashMap<>(Map.of(
+                    "name", name,
+                    "in", "path",
+                    "required", true,
+                    "schema", Map.of("type", "string")
+            )));
             i = close + 1;
         }
 
-        // Explicit @ApiParam annotations
-        ApiParam[] apiParams = cls.getAnnotationsByType(ApiParam.class);
-        for (ApiParam ann : apiParams) {
+        for (ApiParam ann : cls.getAnnotationsByType(ApiParam.class)) {
             Map<String, Object> p = new LinkedHashMap<>();
             p.put("name", ann.name());
             p.put("in", ann.in());
@@ -149,27 +143,46 @@ public class OpenApiBuilder {
     }
 
     private void buildResponses(Map<String, Object> op, Class<?> cls) {
-        ApiResponse[] annotations = cls.getAnnotationsByType(ApiResponse.class);
+        ApiResponse[] anns = cls.getAnnotationsByType(ApiResponse.class);
         Map<String, Object> responses = new LinkedHashMap<>();
 
-        if (annotations.length == 0) {
+        if (anns.length == 0) {
             responses.put("200", Map.of("description", "OK"));
-        } else {
-            for (ApiResponse ann : annotations) {
-                Map<String, Object> r = new LinkedHashMap<>();
-                r.put("description", ann.description().isEmpty() ? httpPhrase(ann.status()) : ann.description());
-                if (ann.schema() != Void.class) {
-                    r.put("content", Map.of(
-                            "application/json", Map.of(
-                                    "schema", Map.of("$ref", "#/components/schemas/" + ann.schema().getSimpleName()))));
-                }
-                responses.put(String.valueOf(ann.status()), r);
-            }
+            op.put("responses", responses);
+            return;
         }
+
+        for (ApiResponse ann : anns) {
+            Map<String, Object> r = new LinkedHashMap<>();
+            r.put("description", ann.description().isEmpty() ? httpPhrase(ann.status()) : ann.description());
+
+            Class<?> schemaType = resolveSchemaType(ann, cls);
+            if (schemaType != null && schemaType != Void.class) {
+                r.put("content", Map.of(
+                        "application/json", Map.of("schema", schemas.referenceFor(schemaType))
+                ));
+            }
+            responses.put(String.valueOf(ann.status()), r);
+        }
+
         op.put("responses", responses);
     }
 
-    /** Converts Flash path params ({id}) to OpenAPI path params ({id}) — already compatible. */
+    private static Class<?> resolveSchemaType(ApiResponse ann, Class<?> handlerClass) {
+        if (ann.schema() != Void.class) return ann.schema();
+        if (!ann.useReturnType()) return null;
+        try {
+            Method handle = handlerClass.getMethod("handle", dev.relism.models.Request.class, dev.relism.models.Response.class);
+            Type ret = handle.getGenericReturnType();
+            Class<?> raw = rawType(ret);
+            if (raw == null || raw == Object.class || raw == dev.relism.models.Response.class || raw == Void.class || raw == void.class)
+                return null;
+            return raw;
+        } catch (NoSuchMethodException e) {
+            return null;
+        }
+    }
+
     private static String normalizePath(String path) {
         return path.startsWith("/") ? path : "/" + path;
     }
@@ -186,19 +199,204 @@ public class OpenApiBuilder {
             case 409 -> "Conflict";
             case 422 -> "Unprocessable Entity";
             case 500 -> "Internal Server Error";
-            default  -> "";
+            default -> "";
         };
     }
 
-    private static List<Map<String, List<String>>> buildOperationSecurity(
-            List<OpenApiSecurityContributor> contributors, Class<?> handlerClass) {
+    private static List<Map<String, List<String>>> buildOperationSecurity(List<OpenApiSecurityContributor> contributors,
+                                                                          Class<?> handlerClass) {
         List<Map<String, List<String>>> security = new ArrayList<>();
         for (OpenApiSecurityContributor c : contributors) {
             List<String> scopes = c.requiredFor(handlerClass);
-            if (scopes != null) {
-                security.add(Map.of(c.schemeName(), scopes));
-            }
+            if (scopes != null) security.add(Map.of(c.schemeName(), scopes));
         }
         return security;
     }
+
+    private static Class<?> rawType(Type type) {
+        if (type instanceof Class<?> c) return c;
+        if (type instanceof ParameterizedType p && p.getRawType() instanceof Class<?> c) return c;
+        if (type instanceof GenericArrayType a) {
+            Class<?> component = rawType(a.getGenericComponentType());
+            return component == null ? null : Array.newInstance(component, 0).getClass();
+        }
+        return null;
+    }
+
+    private static final class SchemaRegistry {
+        private static final Set<Class<?>> SIMPLE = Set.of(
+                String.class, CharSequence.class,
+                Boolean.class, Byte.class, Short.class, Integer.class, Long.class, Float.class, Double.class,
+                boolean.class, byte.class, short.class, int.class, long.class, float.class, double.class,
+                UUID.class, LocalDate.class, LocalDateTime.class, OffsetDateTime.class, Instant.class
+        );
+
+        private final Map<Class<?>, String> names = new LinkedHashMap<>();
+        private final Map<String, Map<String, Object>> docs = new LinkedHashMap<>();
+        private final Set<Class<?>> resolving = new HashSet<>();
+
+        Map<String, Object> referenceFor(Class<?> type) {
+            return schemaFor(type);
+        }
+
+        Map<String, Object> render() {
+            Map<String, Object> out = new LinkedHashMap<>();
+            for (var e : docs.entrySet()) out.put(e.getKey(), e.getValue());
+            return out;
+        }
+
+        private Map<String, Object> schemaFor(Type type) {
+            if (type instanceof ParameterizedType p) {
+                Class<?> raw = rawType(p);
+                if (raw != null && Collection.class.isAssignableFrom(raw)) {
+                    Type item = p.getActualTypeArguments()[0];
+                    return Map.of("type", "array", "items", schemaFor(item));
+                }
+                if (raw != null && Map.class.isAssignableFrom(raw)) {
+                    Type value = p.getActualTypeArguments().length > 1 ? p.getActualTypeArguments()[1] : Object.class;
+                    return Map.of("type", "object", "additionalProperties", schemaFor(value));
+                }
+                if (raw != null) return schemaFor(raw);
+            }
+
+            Class<?> cls = rawType(type);
+            if (cls == null || cls == Object.class) return Map.of("type", "object");
+
+            if (cls.isArray()) return Map.of("type", "array", "items", schemaFor(cls.getComponentType()));
+            if (Collection.class.isAssignableFrom(cls)) return Map.of("type", "array", "items", Map.of("type", "object"));
+            if (Map.class.isAssignableFrom(cls)) return Map.of("type", "object", "additionalProperties", Map.of("type", "object"));
+
+            Map<String, Object> simple = simpleSchema(cls);
+            if (simple != null) return simple;
+
+            return Map.of("$ref", "#/components/schemas/" + registerPojo(cls));
+        }
+
+        private String registerPojo(Class<?> cls) {
+            String existing = names.get(cls);
+            if (existing != null) return existing;
+
+            String base = schemaName(cls);
+            String name = base;
+            int i = 2;
+            while (docs.containsKey(name)) name = base + i++;
+            names.put(cls, name);
+
+            if (resolving.contains(cls)) return name;
+            resolving.add(cls);
+            docs.put(name, buildPojoSchema(cls));
+            resolving.remove(cls);
+            return name;
+        }
+
+        private Map<String, Object> buildPojoSchema(Class<?> cls) {
+            Schema typeSchema = cls.getAnnotation(Schema.class);
+            JsonIgnoreProperties ignoredType = cls.getAnnotation(JsonIgnoreProperties.class);
+            Set<String> ignored = ignoredType == null
+                    ? Set.of()
+                    : new HashSet<>(Arrays.asList(ignoredType.value()));
+
+            Map<String, Object> out = new LinkedHashMap<>();
+            out.put("type", "object");
+            if (typeSchema != null && !typeSchema.description().isEmpty()) out.put("description", typeSchema.description());
+
+            Map<String, Object> properties = new LinkedHashMap<>();
+            List<String> required = new ArrayList<>();
+
+            for (Field f : cls.getDeclaredFields()) {
+                int mod = f.getModifiers();
+                if (Modifier.isStatic(mod) || Modifier.isTransient(mod)) continue;
+                if (f.isAnnotationPresent(JsonIgnore.class)) continue;
+                if (ignored.contains(f.getName())) continue;
+
+                String name = f.getName();
+                JsonProperty jp = f.getAnnotation(JsonProperty.class);
+                if (jp != null && !jp.value().isEmpty()) name = jp.value();
+
+                Schema ps = f.getAnnotation(Schema.class);
+                SchemaProperty sp = f.getAnnotation(SchemaProperty.class);
+                ArraySchema array = f.getAnnotation(ArraySchema.class);
+                if ((ps != null && ps.hidden()) || (sp != null && sp.hidden())) continue;
+
+                if (sp != null && !sp.name().isEmpty()) name = sp.name();
+
+                Map<String, Object> property = new LinkedHashMap<>(schemaFor(f.getGenericType()));
+                if (ps != null) applySchemaHints(property, ps);
+                if (sp != null) applySchemaHints(property, sp);
+                if (array != null) applyArrayHints(property, array);
+                if (jp != null) {
+                    if (jp.access() == Access.READ_ONLY) property.put("readOnly", true);
+                    if (jp.access() == Access.WRITE_ONLY) property.put("writeOnly", true);
+                }
+
+                properties.put(name, property);
+                if ((ps != null && ps.required()) || (sp != null && sp.required()) || (jp != null && jp.required())) required.add(name);
+            }
+
+            if (!properties.isEmpty()) out.put("properties", properties);
+            if (!required.isEmpty()) out.put("required", required);
+            return out;
+        }
+
+        private static void applySchemaHints(Map<String, Object> property, Schema schema) {
+            if (!schema.description().isEmpty()) property.put("description", schema.description());
+            if (!schema.format().isEmpty()) property.put("format", schema.format());
+            if (!schema.example().isEmpty()) property.put("example", schema.example());
+            if (schema.nullable()) property.put("nullable", true);
+        }
+
+        private static void applySchemaHints(Map<String, Object> property, SchemaProperty schema) {
+            if (!schema.description().isEmpty()) property.put("description", schema.description());
+            if (!schema.format().isEmpty()) property.put("format", schema.format());
+            if (!schema.example().isEmpty()) property.put("example", schema.example());
+            if (schema.nullable()) property.put("nullable", true);
+        }
+
+        private Map<String, Object> withArrayType(Map<String, Object> property, ArraySchema array) {
+            if ("array".equals(property.get("type"))) return property;
+            Type itemType = array.itemClass() != Void.class ? array.itemClass() : Object.class;
+            Map<String, Object> wrapped = new LinkedHashMap<>();
+            wrapped.put("type", "array");
+            wrapped.put("items", schemaFor(itemType));
+            return wrapped;
+        }
+
+        private void applyArrayHints(Map<String, Object> property, ArraySchema array) {
+            Map<String, Object> target = withArrayType(property, array);
+            if (target != property) {
+                property.clear();
+                property.putAll(target);
+            }
+            if (array.uniqueItems()) property.put("uniqueItems", true);
+            if (array.minItems() >= 0) property.put("minItems", array.minItems());
+            if (array.maxItems() >= 0) property.put("maxItems", array.maxItems());
+        }
+
+        private static String schemaName(Class<?> cls) {
+            Schema schema = cls.getAnnotation(Schema.class);
+            if (schema != null && !schema.name().isEmpty()) return schema.name();
+            return cls.getSimpleName();
+        }
+
+        private Map<String, Object> simpleSchema(Class<?> cls) {
+            if (cls == String.class || cls == CharSequence.class || cls == UUID.class) return Map.of("type", "string");
+            if (cls == boolean.class || cls == Boolean.class) return Map.of("type", "boolean");
+            if (cls == byte.class || cls == Byte.class || cls == short.class || cls == Short.class ||
+                    cls == int.class || cls == Integer.class) return Map.of("type", "integer", "format", "int32");
+            if (cls == long.class || cls == Long.class) return Map.of("type", "integer", "format", "int64");
+            if (cls == float.class || cls == Float.class) return Map.of("type", "number", "format", "float");
+            if (cls == double.class || cls == Double.class) return Map.of("type", "number", "format", "double");
+            if (cls == LocalDate.class) return Map.of("type", "string", "format", "date");
+            if (cls == LocalDateTime.class || cls == OffsetDateTime.class || cls == Instant.class)
+                return Map.of("type", "string", "format", "date-time");
+            if (cls.isEnum()) {
+                Object[] constants = cls.getEnumConstants();
+                List<String> values = new ArrayList<>(constants.length);
+                for (Object c : constants) values.add(((Enum<?>) c).name());
+                return Map.of("type", "string", "enum", values);
+            }
+            if (!SIMPLE.contains(cls) && cls.getName().startsWith("java.")) return Map.of("type", "string");
+            return null;
+        }
+    }
 }
diff --git a/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiExtension.java b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiExtension.java
index 62bbaaf..ebe6db3 100644
--- a/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiExtension.java
+++ b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiExtension.java
@@ -1,13 +1,17 @@
 package dev.relism.ext.openapi;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.json.JsonMapper;
 import com.fasterxml.jackson.dataformat.yaml.YAMLMapper;
 import dev.relism.extension.FlashContext;
 import dev.relism.extension.FlashExtension;
 import dev.relism.extension.FlashRegistrar;
 import dev.relism.http.ContentType;
+import dev.relism.http.HttpMethod;
 import dev.relism.routing.Route;
 
+import java.lang.annotation.Annotation;
+
 /**
  * Generates and serves an OpenAPI 3.0 spec and Swagger UI under a configurable base path.
  *
@@ -18,17 +22,16 @@ import dev.relism.routing.Route;
  *   <li>{@code GET /openapi/swagger} — Swagger UI pointing at {@code /openapi.json}</li>
  * </ul>
  *
- * <p><b>Requires</b> {@code flash-ext-jackson} to be installed first (shares its
- * {@link ObjectMapper}). The YAML endpoint uses its own {@link YAMLMapper} instance.
+ * <p>If {@code flash-ext-jackson} is installed, this extension reuses its
+ * {@link ObjectMapper}. Otherwise it uses a local default mapper.
  *
- * <p>Operations are collected automatically from handlers annotated with
- * {@link ApiOperation} as they are registered via {@link FlashApp#register}.
+ * <p>Operations are collected at boot from handlers annotated with {@link ApiOperation}
+ * that also have route metadata ({@link Route} or shorthand verb annotations).
  *
  * <pre>{@code
- * FlashApp.of(new HttpServer(config))
+ * FlashApp.create(8080)
  *     .install(new JacksonExtension())
  *     .install(new OpenApiExtension("/openapi", "My API", "2.0.0"))
- *     .register(new BlogHandlers.Index())
  *     .start();
  * }</pre>
  */
@@ -60,54 +63,40 @@ public class OpenApiExtension implements FlashExtension {
         this.description = description;
     }
 
+    // ── FlashExtension ────────────────────────────────────────────────────────
+
     @Override
-    public void install(FlashRegistrar app, FlashContext ctx) {
-        ObjectMapper jsonMapper = ctx.require(ObjectMapper.class);
-        YAMLMapper   yamlMapper = new YAMLMapper();
-
-        OpenApiBuilder builder = new OpenApiBuilder()
-                .title(title)
-                .version(version)
-                .description(description);
-
+    public void provide(FlashContext ctx) {
+        OpenApiBuilder          builder     = new OpenApiBuilder().title(title).version(version).description(description);
         OpenApiSecurityRegistry secRegistry = new OpenApiSecurityRegistry();
+
         ctx.provide(OpenApiSecurityRegistry.class, secRegistry);
+        ctx.provide(OpenApiBuilder.class,          builder);
         builder.setSecurityRegistry(secRegistry);
 
-        ctx.provide(OpenApiBuilder.class, builder);
-
-        // Collect operation metadata at handler-registration time (no middleware injected)
+        // Collect operation metadata at handler-registration time (no middleware injected).
         ctx.addAnnotationProcessor(handlerClass -> {
             ApiOperation op    = handlerClass.getAnnotation(ApiOperation.class);
-            Route        route = handlerClass.getAnnotation(Route.class);
-            if (op != null && route != null) {
-                builder.addOperation(route, op, handlerClass);
-            }
+            Route        route = routeOf(handlerClass);
+            if (op != null && route != null) builder.addOperation(route, op, handlerClass);
             return java.util.List.of();
         });
+    }
+
+    @Override
+    public void routes(FlashRegistrar<?> app, FlashContext ctx) {
+        ObjectMapper jsonMapper = ctx.find(ObjectMapper.class).orElseGet(() -> JsonMapper.builder().build());
+        YAMLMapper   yamlMapper = new YAMLMapper();
+        OpenApiBuilder builder  = ctx.require(OpenApiBuilder.class);
 
         String jsonPath    = basePath + ".json";
         String yamlPath    = basePath + ".yaml";
         String swaggerPath = basePath + "/swagger";
-
-        // JSON spec
-        app.get(jsonPath, (req, res) -> {
-            res.setContentType(ContentType.JSON);
-            return jsonMapper.writeValueAsString(builder.build());
-        }).with();
-
-        // YAML spec
-        app.get(yamlPath, (req, res) -> {
-            res.type(YAML_CONTENT_TYPE);
-            return yamlMapper.writeValueAsString(builder.build());
-        }).with();
-
-        // Swagger UI — loads from CDN, points at the JSON spec
         String swaggerHtml = buildSwaggerHtml(jsonPath);
-        app.get(swaggerPath, (req, res) -> {
-            res.setContentType(ContentType.TEXT_HTML);
-            return swaggerHtml;
-        }).with();
+
+        app.get(jsonPath,    (req, res) -> { res.type(ContentType.JSON);     return jsonMapper.writeValueAsString(builder.build()); });
+        app.get(yamlPath,    (req, res) -> { res.type(YAML_CONTENT_TYPE);              return yamlMapper.writeValueAsString(builder.build()); });
+        app.get(swaggerPath, (req, res) -> { res.type(ContentType.TEXT_HTML); return swaggerHtml; });
     }
 
     // ── Swagger UI HTML ───────────────────────────────────────────────────────
@@ -136,4 +125,31 @@ public class OpenApiExtension implements FlashExtension {
                "</body>\n" +
                "</html>";
     }
+
+    private static Route routeOf(Class<?> cls) {
+        Route direct = cls.getAnnotation(Route.class);
+        if (direct != null) return direct;
+        for (Annotation ann : cls.getAnnotations()) {
+            Route meta = ann.annotationType().getAnnotation(Route.class);
+            if (meta == null) continue;
+            String path = readPathValue(ann);
+            if (path == null) continue;
+            HttpMethod method = meta.method();
+            return new Route() {
+                @Override public HttpMethod method() { return method; }
+                @Override public String path() { return path; }
+                @Override public Class<? extends Annotation> annotationType() { return Route.class; }
+            };
+        }
+        return null;
+    }
+
+    private static String readPathValue(Annotation ann) {
+        try {
+            Object v = ann.annotationType().getMethod("value").invoke(ann);
+            return v instanceof String s ? s : null;
+        } catch (ReflectiveOperationException ignored) {
+            return null;
+        }
+    }
 }
diff --git a/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/Schema.java b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/Schema.java
new file mode 100644
index 0000000..1d5b9e9
--- /dev/null
+++ b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/Schema.java
@@ -0,0 +1,19 @@
+package dev.relism.ext.openapi;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/** Minimal OpenAPI schema metadata for model classes and properties. */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD})
+public @interface Schema {
+    String name() default "";
+    String description() default "";
+    String format() default "";
+    String example() default "";
+    boolean nullable() default false;
+    boolean required() default false;
+    boolean hidden() default false;
+}
diff --git a/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/SchemaProperty.java b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/SchemaProperty.java
new file mode 100644
index 0000000..02f1e40
--- /dev/null
+++ b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/SchemaProperty.java
@@ -0,0 +1,19 @@
+package dev.relism.ext.openapi;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/** Optional alias for property-level schema metadata. */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.FIELD, ElementType.METHOD})
+public @interface SchemaProperty {
+    String name() default "";
+    String description() default "";
+    String format() default "";
+    String example() default "";
+    boolean nullable() default false;
+    boolean required() default false;
+    boolean hidden() default false;
+}
diff --git a/flash-extensions/flash-ext-routeviewer/src/main/java/dev/relism/ext/routeviewer/RouteViewerDataHandler.java b/flash-extensions/flash-ext-routeviewer/src/main/java/dev/relism/ext/routeviewer/RouteViewerDataHandler.java
index 2aca676..0d995e2 100644
--- a/flash-extensions/flash-ext-routeviewer/src/main/java/dev/relism/ext/routeviewer/RouteViewerDataHandler.java
+++ b/flash-extensions/flash-ext-routeviewer/src/main/java/dev/relism/ext/routeviewer/RouteViewerDataHandler.java
@@ -23,7 +23,7 @@ class RouteViewerDataHandler {
 
     Object handle(Request req, Response res) {
         if (cachedJson == null) cachedJson = GraphSerializer.toJson(graph);
-        res.setContentType(ContentType.JSON);
+        res.type(ContentType.JSON);
         res.header("Cache-Control", "no-cache");
         return cachedJson;
     }
diff --git a/flash-extensions/flash-ext-routeviewer/src/main/java/dev/relism/ext/routeviewer/RouteViewerExtension.java b/flash-extensions/flash-ext-routeviewer/src/main/java/dev/relism/ext/routeviewer/RouteViewerExtension.java
index 60ad14a..4b22acf 100644
--- a/flash-extensions/flash-ext-routeviewer/src/main/java/dev/relism/ext/routeviewer/RouteViewerExtension.java
+++ b/flash-extensions/flash-ext-routeviewer/src/main/java/dev/relism/ext/routeviewer/RouteViewerExtension.java
@@ -1,6 +1,7 @@
 package dev.relism.ext.routeviewer;
 
 import dev.relism.ext.routeviewer.model.RouteGraph;
+import dev.relism.extension.ExtensionPhase;
 import dev.relism.extension.FlashContext;
 import dev.relism.extension.FlashExtension;
 import dev.relism.extension.FlashRegistrar;
@@ -21,22 +22,17 @@ import dev.relism.http.ContentType;
  *   <li>{@code GET <path>/data}    — graph JSON consumed by the SPA</li>
  * </ul>
  *
- * <h3>Install order</h3>
- * Install <em>after</em> extensions that register annotation processors
- * (e.g. {@code OidcExtension}) but <em>before</em> {@code scan()} or
- * {@code register()} calls so the listener captures all routes:
+ * <p>The route listener is registered during the {@link #provide} phase, before any routes
+ * are compiled. Combined with the two-phase extension model, this guarantees all routes
+ * (including those from other extensions) are always captured — install order is irrelevant.
  *
  * <pre>{@code
  * FlashApp.create(8080)
  *     .install(new OidcExtension(config))
- *     .install(new JacksonExtension())
- *     .install(new RouteViewerExtension())   // before scan
+ *     .install(new RouteViewerExtension())
  *     .scan("dev.example.handlers")
  *     .start();
  * }</pre>
- *
- * <p>All route metadata is collected once at boot time via
- * {@link FlashContext#addRouteListener}. Zero overhead on the request hot-path.
  */
 public class RouteViewerExtension implements FlashExtension {
 
@@ -45,6 +41,9 @@ public class RouteViewerExtension implements FlashExtension {
     private final String     path;
     private final RouteGraph graph = new RouteGraph();
 
+    /** Observability — runs last so the viewer sees the complete middleware chain. */
+    @Override public int priority() { return ExtensionPhase.LATE.value; }
+
     /** Installs the viewer at {@value #DEFAULT_PATH}. */
     public RouteViewerExtension() { this(DEFAULT_PATH); }
 
@@ -55,20 +54,16 @@ public class RouteViewerExtension implements FlashExtension {
     public RouteViewerExtension(String path) { this.path = path; }
 
     @Override
-    public void install(FlashRegistrar app, FlashContext ctx) {
-        RouteViewerHandler     shell = new RouteViewerHandler();
-        RouteViewerDataHandler data  = new RouteViewerDataHandler(graph);
-
-        // Static assets (Vite build output, bundled in JAR)
-        app.get(path,              shell::handle);
-        app.get(path + "/app.js",  new RouteViewerStaticHandler("routeviewer/app.js",  ContentType.TEXT_JAVASCRIPT)::handle);
-        app.get(path + "/app.css", new RouteViewerStaticHandler("routeviewer/app.css", ContentType.TEXT_CSS)::handle);
-
-        // Graph data API — must be registered before the listener so it is
-        // flushed and captured AFTER the listener is attached (shows in the graph)
-        app.get(path + "/data", data::handle);
-
-        // Start listening — routes registered after this point are captured
+    public void provide(FlashContext ctx) {
+        // Register listener before any routes compile — captures everything.
         ctx.addRouteListener(graph::add);
     }
+
+    @Override
+    public void routes(FlashRegistrar<?> app, FlashContext ctx) {
+        app.get(path,              new RouteViewerHandler()::handle);
+        app.get(path + "/app.js",  new RouteViewerStaticHandler("routeviewer/app.js",  ContentType.TEXT_JAVASCRIPT)::handle);
+        app.get(path + "/app.css", new RouteViewerStaticHandler("routeviewer/app.css", ContentType.TEXT_CSS)::handle);
+        app.get(path + "/data",    new RouteViewerDataHandler(graph)::handle);
+    }
 }
diff --git a/flash-extensions/flash-ext-routeviewer/src/main/java/dev/relism/ext/routeviewer/RouteViewerHandler.java b/flash-extensions/flash-ext-routeviewer/src/main/java/dev/relism/ext/routeviewer/RouteViewerHandler.java
index d0fb1df..8df2138 100644
--- a/flash-extensions/flash-ext-routeviewer/src/main/java/dev/relism/ext/routeviewer/RouteViewerHandler.java
+++ b/flash-extensions/flash-ext-routeviewer/src/main/java/dev/relism/ext/routeviewer/RouteViewerHandler.java
@@ -25,7 +25,7 @@ class RouteViewerHandler {
 
     Object handle(Request req, Response res) throws IOException {
         if (cached == null) cached = load();
-        res.setContentType(ContentType.TEXT_HTML);
+        res.type(ContentType.TEXT_HTML);
         return cached;
     }
 
diff --git a/flash-extensions/flash-ext-routeviewer/src/main/java/dev/relism/ext/routeviewer/RouteViewerStaticHandler.java b/flash-extensions/flash-ext-routeviewer/src/main/java/dev/relism/ext/routeviewer/RouteViewerStaticHandler.java
index 6e16bec..1135015 100644
--- a/flash-extensions/flash-ext-routeviewer/src/main/java/dev/relism/ext/routeviewer/RouteViewerStaticHandler.java
+++ b/flash-extensions/flash-ext-routeviewer/src/main/java/dev/relism/ext/routeviewer/RouteViewerStaticHandler.java
@@ -28,11 +28,11 @@ class RouteViewerStaticHandler {
     Object handle(Request req, Response res) throws IOException {
         if (cached == null) cached = load();
         if (cached == null) {
-            res.setStatusCode(404);
+            res.status(404);
             return null;
         }
-        res.setStatusCode(200);
-        res.setContentType(contentType);
+        res.status(200);
+        res.type(contentType);
         res.header("Cache-Control", "public, max-age=3600");
         return cached;
     }
diff --git a/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/EngineCapabilities.java b/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/EngineCapabilities.java
new file mode 100644
index 0000000..4f9ca1b
--- /dev/null
+++ b/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/EngineCapabilities.java
@@ -0,0 +1,5 @@
+package dev.relism.ext.view;
+
+public record EngineCapabilities(boolean supportsPartialSlot) {
+    public static final EngineCapabilities NONE = new EngineCapabilities(false);
+}
diff --git a/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/LegacyViewEngineAdapter.java b/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/LegacyViewEngineAdapter.java
new file mode 100644
index 0000000..07f96bc
--- /dev/null
+++ b/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/LegacyViewEngineAdapter.java
@@ -0,0 +1,38 @@
+package dev.relism.ext.view;
+
+import dev.relism.http.ContentType;
+import dev.relism.models.Request;
+import dev.relism.models.Response;
+
+import java.util.Map;
+
+final class LegacyViewEngineAdapter implements ViewEngineAdapter {
+    private static final String DEFAULT_FRAGMENT_SLOT = "content";
+
+    private final ViewEngine engine;
+
+    LegacyViewEngineAdapter(ViewEngine engine) {
+        this.engine = engine;
+    }
+
+    @Override
+    public EngineCapabilities capabilities() {
+        return EngineCapabilities.NONE;
+    }
+
+    @Override
+    public RenderOutput render(ViewTarget target, Map<String, Object> model, Request req, Response res) throws Exception {
+        String template = target.template();
+        boolean fragment = target.kind() == ViewKind.PARTIAL;
+
+        if (fragment && target.slot() != null && !target.slot().isBlank()) {
+            template = template + " :: " + target.slot();
+            fragment = false;
+        } else if (fragment) {
+            template = template + " :: " + DEFAULT_FRAGMENT_SLOT;
+            fragment = false;
+        }
+
+        return new RenderOutput(engine.render(template, model, fragment), ContentType.TEXT_HTML);
+    }
+}
diff --git a/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/Page.java b/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/Page.java
new file mode 100644
index 0000000..82c3ab5
--- /dev/null
+++ b/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/Page.java
@@ -0,0 +1,12 @@
+package dev.relism.ext.view;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+public @interface Page {
+    String value();
+}
diff --git a/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/Partial.java b/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/Partial.java
new file mode 100644
index 0000000..7ceb43b
--- /dev/null
+++ b/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/Partial.java
@@ -0,0 +1,13 @@
+package dev.relism.ext.view;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+public @interface Partial {
+    String template();
+    String slot() default "";
+}
diff --git a/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/RenderOutput.java b/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/RenderOutput.java
new file mode 100644
index 0000000..2a861e8
--- /dev/null
+++ b/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/RenderOutput.java
@@ -0,0 +1,9 @@
+package dev.relism.ext.view;
+
+import dev.relism.http.ContentType;
+
+public record RenderOutput(String body, ContentType contentType) {
+    public static RenderOutput html(String body) {
+        return new RenderOutput(body, ContentType.TEXT_HTML);
+    }
+}
diff --git a/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/Renderer.java b/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/Renderer.java
index 764d9e1..033c2f0 100644
--- a/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/Renderer.java
+++ b/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/Renderer.java
@@ -54,7 +54,7 @@ public final class Renderer {
      * header to {@code type}, and returns the rendered string as the handler body.
      */
     public String view(Response res, String template, Object model, ContentType type) throws Exception {
-        res.setContentType(type);
+        res.type(type);
         return engine.render(template, model);
     }
 
diff --git a/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ThymeleafEngine.java b/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ThymeleafEngine.java
index 7a6967a..a6f7ce6 100644
--- a/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ThymeleafEngine.java
+++ b/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ThymeleafEngine.java
@@ -41,7 +41,7 @@ import java.util.Map;
  *   <li>{@code null} model → empty context.</li>
  * </ul>
  */
-final class ThymeleafEngine implements ViewEngine {
+final class ThymeleafEngine implements ViewEngine, ViewEngineAdapter {
 
     private static final String PREFIX   = "/templates/";
     private static final String SUFFIX   = ".html";
@@ -71,6 +71,27 @@ final class ThymeleafEngine implements ViewEngine {
         return engine.process(fragment ? template + FRAGMENT : template, ctx);
     }
 
+    @Override
+    public EngineCapabilities capabilities() {
+        return new EngineCapabilities(true);
+    }
+
+    @Override
+    public RenderOutput render(ViewTarget target, Map<String, Object> model,
+                               dev.relism.models.Request req,
+                               dev.relism.models.Response res) {
+        String selector;
+        if (target.kind() == ViewKind.PAGE) {
+            selector = target.template();
+        } else {
+            String slot = target.slot();
+            selector = target.template() + " :: " + ((slot == null || slot.isBlank()) ? "content" : slot);
+        }
+        Context ctx = new Context();
+        populateContext(ctx, model);
+        return RenderOutput.html(engine.process(selector, ctx));
+    }
+
     private static void populateContext(Context ctx, Object model) {
         if (model instanceof Map<?, ?> map) {
             map.forEach((k, v) -> ctx.setVariable(String.valueOf(k), v));
diff --git a/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewEngineAdapter.java b/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewEngineAdapter.java
new file mode 100644
index 0000000..966af61
--- /dev/null
+++ b/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewEngineAdapter.java
@@ -0,0 +1,11 @@
+package dev.relism.ext.view;
+
+import dev.relism.models.Request;
+import dev.relism.models.Response;
+
+import java.util.Map;
+
+public interface ViewEngineAdapter {
+    EngineCapabilities capabilities();
+    RenderOutput render(ViewTarget target, Map<String, Object> model, Request req, Response res) throws Exception;
+}
diff --git a/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewEngineType.java b/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewEngineType.java
index b1bd71a..e04b7c2 100644
--- a/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewEngineType.java
+++ b/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewEngineType.java
@@ -53,15 +53,21 @@ public enum ViewEngineType {
      * @param cacheEnabled whether the engine should cache compiled templates
      * @throws IllegalStateException if the required library is not on the classpath
      */
-    ViewEngine createEngine(boolean cacheEnabled) {
+    ViewEngineAdapter createAdapter(boolean cacheEnabled) {
         return switch (this) {
             case THYMELEAF -> createThymeleaf(cacheEnabled);
         };
     }
 
+    ViewEngine createEngine(boolean cacheEnabled) {
+        ViewEngineAdapter adapter = createAdapter(cacheEnabled);
+        if (adapter instanceof ViewEngine engine) return engine;
+        throw new IllegalStateException("Selected engine does not expose legacy ViewEngine interface: " + this);
+    }
+
     // ── Engine factories ──────────────────────────────────────────────────────
 
-    private static ViewEngine createThymeleaf(boolean cacheEnabled) {
+    private static ViewEngineAdapter createThymeleaf(boolean cacheEnabled) {
         try {
             return new ThymeleafEngine(cacheEnabled);
         } catch (NoClassDefFoundError e) {
diff --git a/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewExtension.java b/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewExtension.java
index 458a462..bd32d05 100644
--- a/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewExtension.java
+++ b/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewExtension.java
@@ -1,166 +1,81 @@
 package dev.relism.ext.view;
 
+import dev.relism.Flash;
 import dev.relism.extension.FlashContext;
 import dev.relism.extension.FlashExtension;
-import dev.relism.extension.FlashRegistrar;
 import dev.relism.http.ContentType;
 import dev.relism.routing.Middleware;
 
+import java.util.ArrayList;
 import java.util.List;
+import java.util.Map;
 import java.util.Objects;
 
-/**
- * Installs the view layer into a Flash application.
- *
- * <h3>Managed mode (recommended)</h3>
- * Pass a {@link ViewEngineType} — the extension auto-configures the engine,
- * detects dev mode for cache settings, and validates classpath dependencies at boot:
- * <pre>{@code
- * app.install(new ViewExtension(ViewEngineType.THYMELEAF));
- * }</pre>
- *
- * <h3>Manual mode (BYOE)</h3>
- * Supply your own {@link ViewEngine} implementation for full control:
- * <pre>{@code
- * ViewEngine myEngine = (template, model, fragment) -> { ... };
- * app.install(new ViewExtension(myEngine));
- * }</pre>
- *
- * <h3>What gets installed</h3>
- * <ol>
- *   <li>{@link ViewEngine} and {@link Renderer} are bound in the {@link FlashContext} —
- *       any handler can retrieve them via {@code require(Renderer.class)}.</li>
- *   <li>An {@link dev.relism.extension.AnnotationProcessor} is registered: class-based
- *       handlers carrying {@link View @View} receive an injected rendering middleware
- *       that intercepts the handler return value, resolves the template + model, and
- *       delegates to the engine. No boilerplate required in the handler itself.</li>
- * </ol>
- *
- * <h3>Handler patterns</h3>
- * <pre>{@code
- * // Declarative — annotation drives template selection
- * @Route(method = HttpMethod.GET, path = "/")
- * @View("home")
- * public class HomeHandler extends RequestHandler {
- *     public Object handle(Request req, Response res) {
- *         return Map.of("posts", service.findAll());  // model → home.html
- *     }
- * }
- *
- * // Dynamic override via Template signal
- * @View("list")
- * public class ListHandler extends RequestHandler {
- *     public Object handle(Request req, Response res) {
- *         if (error) return Template.of("error", Map.of("msg", "oops"));
- *         return data;                                // falls back to list.html
- *     }
- * }
- *
- * // Imperative — explicit render call (lambda-friendly)
- * Renderer renderer = app.ctx().require(Renderer.class);
- * app.get("/about", (req, res) -> renderer.view(res, "about"));
- * }</pre>
- *
- * <h3>Dev mode / cache</h3>
- * In managed mode, template caching is disabled when the JVM property
- * {@code flash.env=dev} or the environment variable {@code FLASH_ENV=dev} is set.
- *
- * <h3>Cross-extension integration</h3>
- * <pre>{@code
- * ctx.optional(ViewEngine.class).ifPresent(engine -> { ... });
- * }</pre>
- */
 public final class ViewExtension implements FlashExtension {
 
-    private final ViewEngine engine;
+    private final ViewEngineAdapter adapter;
+    private final ViewEngine legacyEngine;
+    private final List<ViewGlobals> globals = new ArrayList<>();
 
-    // ── Constructors ──────────────────────────────────────────────────────────
-
-    /**
-     * Managed mode — auto-configures the engine selected by {@code type}.
-     *
-     * <p>Template caching is enabled unless {@code flash.env=dev} (JVM property)
-     * or {@code FLASH_ENV=dev} (environment variable) is set.
-     *
-     * @param type the engine to use; must have its library on the runtime classpath
-     * @throws IllegalStateException at boot time if the library is missing
-     */
     public ViewExtension(ViewEngineType type) {
-        this(type.createEngine(!isDevMode()));
+        this(type.createAdapter(!Flash.DEV));
     }
 
-    /**
-     * Manual mode — use a pre-constructed {@link ViewEngine} implementation.
-     * Suitable for custom engines or engines that need non-default configuration.
-     *
-     * @param engine the engine implementation; must be thread-safe
-     */
     public ViewExtension(ViewEngine engine) {
-        this.engine = Objects.requireNonNull(engine, "ViewEngine must not be null");
+        this(new LegacyViewEngineAdapter(engine), engine);
     }
 
-    // ── FlashExtension ────────────────────────────────────────────────────────
+    public ViewExtension(ViewEngineAdapter adapter) {
+        this(adapter, null);
+    }
+
+    private ViewExtension(ViewEngineAdapter adapter, ViewEngine legacyEngine) {
+        this.adapter = Objects.requireNonNull(adapter, "ViewEngineAdapter must not be null");
+        this.legacyEngine = legacyEngine;
+    }
+
+    public ViewExtension addGlobals(ViewGlobals provider) {
+        globals.add(Objects.requireNonNull(provider, "ViewGlobals must not be null"));
+        return this;
+    }
 
     @Override
-    public void install(FlashRegistrar app, FlashContext ctx) {
-        Renderer renderer = new Renderer(engine);
-        ctx.provide(ViewEngine.class, engine);
-        ctx.provide(Renderer.class,   renderer);
+    public void provide(FlashContext ctx) {
+        ViewRuntime runtime = new ViewRuntime(adapter, List.copyOf(globals));
+        ctx.provide(ViewEngineAdapter.class, adapter);
+        ctx.provide(ViewRuntime.class, runtime);
+
+        if (legacyEngine != null) {
+            ctx.provide(ViewEngine.class, legacyEngine);
+            ctx.provide(Renderer.class, new Renderer(legacyEngine));
+        } else if (adapter instanceof ViewEngine engine) {
+            ctx.provide(ViewEngine.class, engine);
+            ctx.provide(Renderer.class, new Renderer(engine));
+        }
 
         ctx.addAnnotationProcessor(handlerClass -> {
-            View view = findView(handlerClass);
-            if (view == null) return List.of();
+            if (ViewHandler.class.isAssignableFrom(handlerClass)) return List.of();
 
-            String      defaultTemplate = view.value();
-            ContentType contentType     = view.contentType();
-            boolean     fragment        = view.fragment();
+            ViewTargetResolver.ResolvedView resolved = ViewTargetResolver.resolve(handlerClass, adapter.capabilities());
+            if (resolved == null) return List.of();
 
-            // Injected once per handler at boot — zero overhead on the hot-path.
-            // Intercepts the return value: Template signal overrides name+model;
-            // any other value becomes the model for the annotation's template.
             Middleware renderingMiddleware = next -> (req, res) -> {
                 Object result = next.handle(req, res);
-                String tpl;
-                Object model;
-                if (result instanceof Template t) {
-                    tpl   = t.name();
-                    model = t.model();
-                } else {
-                    tpl   = defaultTemplate;
-                    model = result;
+                ViewModel local = ViewRuntime.legacyLocalModel(result);
+                ViewModel merged = runtime.merge(req, local);
+                RenderOutput out = adapter.render(resolved.target(), merged.toMap(), req, res);
+
+                if (resolved.legacy()) {
+                    ContentType type = resolved.contentType();
+                    if (type != null) res.type(type);
+                    else if (out.contentType() != null) res.type(out.contentType());
+                } else if (out.contentType() != null) {
+                    res.type(out.contentType());
                 }
-                res.setContentType(contentType);
-                return engine.render(tpl, model, fragment);
+                return out.body();
             };
 
             return List.of(renderingMiddleware);
         });
     }
-
-    // ── Helpers ───────────────────────────────────────────────────────────────
-
-    /**
-     * Walks the superclass chain to find {@link View @View}.
-     * Supports inheritance: a base handler can declare the view template and
-     * concrete subclasses inherit it without re-annotating.
-     */
-    private static View findView(Class<?> cls) {
-        while (cls != null && !cls.equals(Object.class)) {
-            View v = cls.getAnnotation(View.class);
-            if (v != null) return v;
-            cls = cls.getSuperclass();
-        }
-        return null;
-    }
-
-    /**
-     * Returns {@code true} when running in dev mode.
-     * Checks JVM property {@code flash.env} first, then env var {@code FLASH_ENV}.
-     */
-    private static boolean isDevMode() {
-        String prop = System.getProperty("flash.env");
-        if (prop != null) return "dev".equalsIgnoreCase(prop);
-        String env  = System.getenv("FLASH_ENV");
-        return "dev".equalsIgnoreCase(env);
-    }
 }
diff --git a/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewGlobals.java b/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewGlobals.java
new file mode 100644
index 0000000..1098e03
--- /dev/null
+++ b/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewGlobals.java
@@ -0,0 +1,8 @@
+package dev.relism.ext.view;
+
+import dev.relism.models.Request;
+
+@FunctionalInterface
+public interface ViewGlobals {
+    ViewModel provide(Request req);
+}
diff --git a/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewHandler.java b/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewHandler.java
new file mode 100644
index 0000000..0c6bb7f
--- /dev/null
+++ b/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewHandler.java
@@ -0,0 +1,32 @@
+package dev.relism.ext.view;
+
+import dev.relism.models.Request;
+import dev.relism.models.RequestHandler;
+import dev.relism.models.Response;
+
+public abstract class ViewHandler extends RequestHandler {
+    private ViewRuntime runtime;
+    private ViewTargetResolver.ResolvedView resolved;
+
+    public ViewModel render(Request req) throws Exception {
+        throw new UnsupportedOperationException("Override render(Request) or render(Request, Response)");
+    }
+
+    public ViewModel render(Request req, Response res) throws Exception {
+        return render(req);
+    }
+
+    @Override
+    protected final void onInit() {
+        runtime = require(ViewRuntime.class);
+        resolved = runtime.resolve(getClass());
+        onViewInit();
+    }
+
+    protected void onViewInit() {}
+
+    @Override
+    public final Object handle(Request request, Response response) throws Exception {
+        return runtime.render(this, resolved, request, response);
+    }
+}
diff --git a/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewKind.java b/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewKind.java
new file mode 100644
index 0000000..78851ed
--- /dev/null
+++ b/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewKind.java
@@ -0,0 +1,6 @@
+package dev.relism.ext.view;
+
+public enum ViewKind {
+    PAGE,
+    PARTIAL
+}
diff --git a/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewModel.java b/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewModel.java
new file mode 100644
index 0000000..452e249
--- /dev/null
+++ b/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewModel.java
@@ -0,0 +1,71 @@
+package dev.relism.ext.view;
+
+import java.util.Collections;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+
+public final class ViewModel {
+    private final LinkedHashMap<String, Object> values;
+
+    private ViewModel(LinkedHashMap<String, Object> values) {
+        this.values = values;
+    }
+
+    public static ViewModel empty() {
+        return new ViewModel(new LinkedHashMap<>());
+    }
+
+    public static ViewModel of(String key, Object value) {
+        return empty().with(key, value);
+    }
+
+    public ViewModel with(String key, Object value) {
+        values.put(Objects.requireNonNull(key, "key"), unwrapValue(value));
+        return this;
+    }
+
+    public ViewModel withAll(Map<String, Object> values) {
+        if (values == null || values.isEmpty()) return this;
+        for (Map.Entry<String, Object> e : values.entrySet()) {
+            with(e.getKey(), e.getValue());
+        }
+        return this;
+    }
+
+    public ViewModel merge(ViewModel other) {
+        ViewModel merged = new ViewModel(new LinkedHashMap<>(this.values));
+        if (other != null && !other.values.isEmpty()) merged.values.putAll(other.values);
+        return merged;
+    }
+
+    public Map<String, Object> toMap() {
+        return Collections.unmodifiableMap(values);
+    }
+
+    static ViewModel copyOf(ViewModel source) {
+        if (source == null || source.values.isEmpty()) return empty();
+        return new ViewModel(new LinkedHashMap<>(source.values));
+    }
+
+    static Object unwrapValue(Object value) {
+        if (value instanceof ViewModel vm) {
+            return vm.toMap();
+        }
+        if (value instanceof Map<?, ?> map) {
+            LinkedHashMap<String, Object> out = new LinkedHashMap<>();
+            for (Map.Entry<?, ?> e : map.entrySet()) {
+                out.put(String.valueOf(e.getKey()), unwrapValue(e.getValue()));
+            }
+            return Collections.unmodifiableMap(out);
+        }
+        if (value instanceof List<?> list) {
+            ArrayList<Object> out = new ArrayList<>(list.size());
+            for (Object item : list) out.add(unwrapValue(item));
+            return Collections.unmodifiableList(out);
+        }
+        return value;
+    }
+}
diff --git a/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewRuntime.java b/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewRuntime.java
new file mode 100644
index 0000000..e5462b7
--- /dev/null
+++ b/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewRuntime.java
@@ -0,0 +1,79 @@
+package dev.relism.ext.view;
+
+import dev.relism.models.Request;
+import dev.relism.models.Response;
+
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.List;
+import java.util.Map;
+
+final class ViewRuntime {
+    private static final ViewModel EMPTY = ViewModel.empty();
+
+    private final ViewEngineAdapter adapter;
+    private final List<ViewGlobals> globals;
+    private final ConcurrentHashMap<Class<?>, ViewTargetResolver.ResolvedView> resolvedCache = new ConcurrentHashMap<>();
+
+    ViewRuntime(ViewEngineAdapter adapter, List<ViewGlobals> globals) {
+        this.adapter = adapter;
+        this.globals = globals;
+    }
+
+    ViewTargetResolver.ResolvedView resolve(Class<?> handlerClass) {
+        ViewTargetResolver.ResolvedView cached = resolvedCache.get(handlerClass);
+        if (cached != null) return cached;
+        ViewTargetResolver.ResolvedView resolved = ViewTargetResolver.resolve(handlerClass, adapter.capabilities());
+        if (resolved == null) {
+            throw new IllegalStateException("ViewHandler " + handlerClass.getName()
+                    + " must declare @Page, @Partial, or @View");
+        }
+        resolvedCache.put(handlerClass, resolved);
+        return resolved;
+    }
+
+    Object render(ViewHandler handler, ViewTargetResolver.ResolvedView resolved, Request req, Response res) throws Exception {
+        if (resolved == null) {
+            throw new IllegalStateException("ViewHandler " + handler.getClass().getName()
+                    + " must declare @Page, @Partial, or @View");
+        }
+
+        ViewModel local = handler.render(req, res);
+        ViewModel merged = merge(req, local);
+
+        RenderOutput out = adapter.render(resolved.target(), merged.toMap(), req, res);
+        if (out.contentType() != null) {
+            res.type(out.contentType());
+        } else {
+            res.type(resolved.contentType());
+        }
+        return out.body();
+    }
+
+    ViewModel merge(Request req, ViewModel local) {
+        ViewModel global = computeGlobals(req);
+        return global.merge(local == null ? EMPTY : local);
+    }
+
+    private ViewModel computeGlobals(Request req) {
+        if (globals.isEmpty()) return EMPTY;
+        ViewModel out = ViewModel.empty();
+        for (ViewGlobals provider : globals) {
+            ViewModel vm = provider.provide(req);
+            if (vm != null) out.withAll(vm.toMap());
+        }
+        return out;
+    }
+
+    static ViewModel legacyLocalModel(Object legacyModel) {
+        if (legacyModel == null) return ViewModel.empty();
+        if (legacyModel instanceof ViewModel vm) return ViewModel.copyOf(vm);
+        if (legacyModel instanceof Map<?, ?> map) {
+            ViewModel vm = ViewModel.empty();
+            for (Map.Entry<?, ?> e : map.entrySet()) {
+                vm.with(String.valueOf(e.getKey()), ViewModel.unwrapValue(e.getValue()));
+            }
+            return vm;
+        }
+        return ViewModel.of("it", legacyModel);
+    }
+}
diff --git a/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewTarget.java b/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewTarget.java
new file mode 100644
index 0000000..00318f8
--- /dev/null
+++ b/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewTarget.java
@@ -0,0 +1,7 @@
+package dev.relism.ext.view;
+
+public record ViewTarget(
+        ViewKind kind,
+        String template,
+        String slot
+) {}
diff --git a/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewTargetResolver.java b/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewTargetResolver.java
new file mode 100644
index 0000000..851dd43
--- /dev/null
+++ b/flash-extensions/flash-ext-view/src/main/java/dev/relism/ext/view/ViewTargetResolver.java
@@ -0,0 +1,62 @@
+package dev.relism.ext.view;
+
+import dev.relism.http.ContentType;
+import dev.relism.routing.Route;
+import dev.relism.routing.Routes;
+
+final class ViewTargetResolver {
+
+    private ViewTargetResolver() {}
+
+    static ResolvedView resolve(Class<?> handlerClass, EngineCapabilities capabilities) {
+        Page page = find(handlerClass, Page.class);
+        Partial partial = find(handlerClass, Partial.class);
+        View legacy = find(handlerClass, View.class);
+
+        int count = (page != null ? 1 : 0) + (partial != null ? 1 : 0) + (legacy != null ? 1 : 0);
+        if (count == 0) return null;
+
+        Route route = Routes.of(handlerClass);
+        if (route == null) {
+            throw new IllegalStateException("View handler " + handlerClass.getName()
+                    + " has view annotation but no route annotation (@Route/@GET/@POST/...)");
+        }
+
+        if (count > 1) {
+            throw new IllegalStateException("Handler " + handlerClass.getName()
+                    + " route " + route.method() + " " + route.path()
+                    + " declares multiple view annotations. Use exactly one of @Page, @Partial, @View");
+        }
+
+        if (page != null) {
+            return new ResolvedView(new ViewTarget(ViewKind.PAGE, page.value(), ""), ContentType.TEXT_HTML, false);
+        }
+
+        if (partial != null) {
+            String slot = partial.slot() == null ? "" : partial.slot().trim();
+            if (!slot.isEmpty() && !capabilities.supportsPartialSlot()) {
+                throw new IllegalStateException("Handler " + handlerClass.getName()
+                        + " route " + route.method() + " " + route.path()
+                        + " uses @Partial(slot=\"" + slot + "\") but current engine does not support partial slots");
+            }
+            return new ResolvedView(new ViewTarget(ViewKind.PARTIAL, partial.template(), slot), ContentType.TEXT_HTML, false);
+        }
+
+        return new ResolvedView(
+                new ViewTarget(legacy.fragment() ? ViewKind.PARTIAL : ViewKind.PAGE, legacy.value(), ""),
+                legacy.contentType(),
+                true
+        );
+    }
+
+    private static <A extends java.lang.annotation.Annotation> A find(Class<?> cls, Class<A> type) {
+        while (cls != null && !cls.equals(Object.class)) {
+            A a = cls.getAnnotation(type);
+            if (a != null) return a;
+            cls = cls.getSuperclass();
+        }
+        return null;
+    }
+
+    record ResolvedView(ViewTarget target, ContentType contentType, boolean legacy) {}
+}
diff --git a/flash-extensions/flash-ext-view/src/test/java/dev/relism/ext/view/ViewModelTest.java b/flash-extensions/flash-ext-view/src/test/java/dev/relism/ext/view/ViewModelTest.java
new file mode 100644
index 0000000..fdec2f4
--- /dev/null
+++ b/flash-extensions/flash-ext-view/src/test/java/dev/relism/ext/view/ViewModelTest.java
@@ -0,0 +1,56 @@
+package dev.relism.ext.view;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+class ViewModelTest {
+
+    @Test
+    void ofWithAndWithAll_populateModel() {
+        ViewModel model = ViewModel.of("a", 1)
+                .with("b", "x")
+                .withAll(Map.of("c", true));
+
+        assertEquals(1, model.toMap().get("a"));
+        assertEquals("x", model.toMap().get("b"));
+        assertEquals(true, model.toMap().get("c"));
+    }
+
+    @Test
+    void merge_otherWinsOnCollision() {
+        ViewModel global = ViewModel.of("nav", "global").with("app", "flash");
+        ViewModel local = ViewModel.of("nav", "local");
+
+        ViewModel merged = global.merge(local);
+
+        assertEquals("local", merged.toMap().get("nav"));
+        assertEquals("flash", merged.toMap().get("app"));
+    }
+
+    @Test
+    void toMap_isReadOnly() {
+        ViewModel model = ViewModel.of("k", "v");
+        Map<String, Object> map = model.toMap();
+
+        assertThrows(UnsupportedOperationException.class, () -> map.put("x", 1));
+    }
+
+    @Test
+    void nestedViewModel_isUnwrappedToMapRecursively() {
+        ViewModel nested = ViewModel.of("name", "Flash");
+        ViewModel root = ViewModel.of("app", nested)
+                .with("list", List.of(ViewModel.of("n", 1), ViewModel.of("n", 2)));
+
+        Object app = root.toMap().get("app");
+        Object list = root.toMap().get("list");
+
+        assertTrue(app instanceof Map<?, ?>);
+        assertEquals("Flash", ((Map<?, ?>) app).get("name"));
+        assertTrue(list instanceof List<?>);
+        assertTrue(((List<?>) list).getFirst() instanceof Map<?, ?>);
+    }
+}
diff --git a/flash-extensions/flash-ext-view/src/test/java/dev/relism/ext/view/ViewRuntimeGlobalsTest.java b/flash-extensions/flash-ext-view/src/test/java/dev/relism/ext/view/ViewRuntimeGlobalsTest.java
new file mode 100644
index 0000000..1e2fd1d
--- /dev/null
+++ b/flash-extensions/flash-ext-view/src/test/java/dev/relism/ext/view/ViewRuntimeGlobalsTest.java
@@ -0,0 +1,48 @@
+package dev.relism.ext.view;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+class ViewRuntimeGlobalsTest {
+
+    @Test
+    void merge_globalsThenLocal_localWins() {
+        ViewRuntime runtime = new ViewRuntime(new NoopAdapter(), List.of(
+                req -> ViewModel.of("nav", "global").with("app", "flash"),
+                req -> ViewModel.of("nav", "global-2")
+        ));
+
+        ViewModel merged = runtime.merge(null, ViewModel.of("nav", "local"));
+
+        assertEquals("local", merged.toMap().get("nav"));
+        assertEquals("flash", merged.toMap().get("app"));
+    }
+
+    @Test
+    void merge_nullLocal_keepsGlobals() {
+        ViewRuntime runtime = new ViewRuntime(new NoopAdapter(), List.of(
+                req -> ViewModel.of("signedIn", true)
+        ));
+
+        ViewModel merged = runtime.merge(null, null);
+
+        assertEquals(true, merged.toMap().get("signedIn"));
+    }
+
+    private static final class NoopAdapter implements ViewEngineAdapter {
+        @Override
+        public EngineCapabilities capabilities() {
+            return EngineCapabilities.NONE;
+        }
+
+        @Override
+        public RenderOutput render(ViewTarget target, java.util.Map<String, Object> model,
+                                   dev.relism.models.Request req,
+                                   dev.relism.models.Response res) {
+            return RenderOutput.html("");
+        }
+    }
+}
diff --git a/flash-extensions/flash-ext-view/src/test/java/dev/relism/ext/view/ViewTargetResolverTest.java b/flash-extensions/flash-ext-view/src/test/java/dev/relism/ext/view/ViewTargetResolverTest.java
new file mode 100644
index 0000000..0ff9e2b
--- /dev/null
+++ b/flash-extensions/flash-ext-view/src/test/java/dev/relism/ext/view/ViewTargetResolverTest.java
@@ -0,0 +1,95 @@
+package dev.relism.ext.view;
+
+import dev.relism.http.ContentType;
+import dev.relism.models.Request;
+import dev.relism.models.RequestHandler;
+import dev.relism.models.Response;
+import dev.relism.routing.GET;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+class ViewTargetResolverTest {
+
+    @GET("/home")
+    @Page("pages/home")
+    static class PageHandler extends RequestHandler {
+        @Override
+        public Object handle(Request request, Response response) {
+            return null;
+        }
+    }
+
+    @GET("/partial")
+    @Partial(template = "fragments/row", slot = "row")
+    static class SlotPartialHandler extends RequestHandler {
+        @Override
+        public Object handle(Request request, Response response) {
+            return null;
+        }
+    }
+
+    @GET("/legacy")
+    @View(value = "legacy/home", contentType = ContentType.TEXT_PLAIN, fragment = true)
+    static class LegacyHandler extends RequestHandler {
+        @Override
+        public Object handle(Request request, Response response) {
+            return null;
+        }
+    }
+
+    @GET("/bad")
+    @Page("a")
+    @Partial(template = "b")
+    static class ConflictingHandler extends RequestHandler {
+        @Override
+        public Object handle(Request request, Response response) {
+            return null;
+        }
+    }
+
+    @Page("pages/no-route")
+    static class NoRouteHandler extends RequestHandler {
+        @Override
+        public Object handle(Request request, Response response) {
+            return null;
+        }
+    }
+
+    @Test
+    void resolve_page_returnsPageTarget() {
+        ViewTargetResolver.ResolvedView resolved = ViewTargetResolver.resolve(PageHandler.class, new EngineCapabilities(true));
+
+        assertNotNull(resolved);
+        assertEquals(ViewKind.PAGE, resolved.target().kind());
+        assertEquals("pages/home", resolved.target().template());
+    }
+
+    @Test
+    void resolve_slotPartial_withoutCapability_failsFast() {
+        assertThrows(IllegalStateException.class,
+                () -> ViewTargetResolver.resolve(SlotPartialHandler.class, EngineCapabilities.NONE));
+    }
+
+    @Test
+    void resolve_legacyView_mapsToResolvedTarget() {
+        ViewTargetResolver.ResolvedView resolved = ViewTargetResolver.resolve(LegacyHandler.class, EngineCapabilities.NONE);
+
+        assertNotNull(resolved);
+        assertTrue(resolved.legacy());
+        assertEquals(ContentType.TEXT_PLAIN, resolved.contentType());
+        assertEquals(ViewKind.PARTIAL, resolved.target().kind());
+    }
+
+    @Test
+    void resolve_multipleViewAnnotations_fails() {
+        assertThrows(IllegalStateException.class,
+                () -> ViewTargetResolver.resolve(ConflictingHandler.class, new EngineCapabilities(true)));
+    }
+
+    @Test
+    void resolve_viewAnnotationWithoutRoute_fails() {
+        assertThrows(IllegalStateException.class,
+                () -> ViewTargetResolver.resolve(NoRouteHandler.class, new EngineCapabilities(true)));
+    }
+}
diff --git a/flash-extensions/flash-web-bundler/docs/README.md b/flash-extensions/flash-web-bundler/docs/README.md
new file mode 100644
index 0000000..9e3db83
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/docs/README.md
@@ -0,0 +1,24 @@
+# flash-web-bundler
+
+`flash-web-bundler` integrates frontend tooling lifecycle into Flash with explicit, policy-driven behavior.
+
+## Quick Start
+
+```java
+FlashApp.create(8080)
+    .install(new WebBundlerExtension(
+        WebBundlerConfig.builder()
+            .webRoot(Path.of("web"))
+            .basePath("/")
+            .build()
+    ))
+    .start();
+```
+
+## Operating Model
+
+- Dev: orchestrates frontend process lifecycle and health checks.
+- Prod: serves prebuilt assets from `assetsSource` with ETag/cache/compression support.
+- Route precedence: backend first, SPA fallback second (`GET`/`HEAD`).
+
+See also: `asset-sources.md`.
diff --git a/flash-extensions/flash-web-bundler/docs/asset-sources.md b/flash-extensions/flash-web-bundler/docs/asset-sources.md
new file mode 100644
index 0000000..216778e
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/docs/asset-sources.md
@@ -0,0 +1,22 @@
+# Asset Sources
+
+`flash-web-bundler` uses explicit source objects for production assets.
+
+Supported sources:
+
+- `FilesystemAssetsSource.of(Path)`
+- `ClasspathAssetsSource.of(String rootPrefix)`
+
+Builder shortcuts:
+
+- `.assetsFromFilesystem(Path.of("dist"))`
+- `.assetsFromClasspath("web/dist")`
+
+Classpath source requires `asset-manifest.json` generated at build time.
+The developer does not maintain this file manually.
+
+Production startup is fail-fast if:
+
+- manifest is missing
+- manifest is invalid
+- manifest points to missing resources
diff --git a/flash-extensions/flash-web-bundler/docs/configuration.md b/flash-extensions/flash-web-bundler/docs/configuration.md
new file mode 100644
index 0000000..60b1be8
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/docs/configuration.md
@@ -0,0 +1,30 @@
+# Configuration
+
+`WebBundlerConfig` is immutable and built with `WebBundlerConfig.builder()`.
+
+Key fields:
+
+- `runtimeMode`: `PROD`, `ENV`, `AUTODETECT`
+- `operationMode`: `ORCHESTRATE_ONLY`, `MANAGED`
+- `frontendType`: currently `VITE`
+- `packageManager`: `NPM`, `PNPM`, `YARN`, `BUN`
+- `installPolicy`: `AUTO_IF_LOCK_HASH_CHANGED`, `NEVER`
+- `loggingMode`: `MERGED`, `SEPARATE`, `QUIET`, `VERBOSE`
+- `commandSafetyMode`: `WARN`, `BLOCK`, `ALLOW`
+- `webRoot`, `assetsSource`, `basePath`, `devHost`, `devPort`, `watchList`
+
+Asset source is explicit and object-based:
+
+- `assetsFromFilesystem(Path.of("dist"))`
+- `assetsFromClasspath("web/dist")`
+
+Or by direct source object:
+
+- `assetsSource(FilesystemAssetsSource.of(Path.of("dist")))`
+- `assetsSource(ClasspathAssetsSource.of("web/dist"))`
+
+Validation is fail-fast:
+
+- invalid `devPort`
+- blank/invalid watch entries
+- invalid `basePath`
diff --git a/flash-extensions/flash-web-bundler/docs/dev-lifecycle.md b/flash-extensions/flash-web-bundler/docs/dev-lifecycle.md
new file mode 100644
index 0000000..c86aebf
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/docs/dev-lifecycle.md
@@ -0,0 +1,16 @@
+# Dev Lifecycle
+
+Boot flow in dev mode:
+
+1. Resolve runtime mode.
+2. Validate configuration and command safety.
+3. Optionally install dependencies (hash-based lockfile cache).
+4. Start dev server process.
+5. Run healthcheck.
+6. Start watchlist loop and restart dev process when tracked files change.
+
+Failure conditions are fail-fast:
+
+- occupied dev port
+- command launch failure
+- healthcheck timeout
diff --git a/flash-extensions/flash-web-bundler/docs/frontend-selection.md b/flash-extensions/flash-web-bundler/docs/frontend-selection.md
new file mode 100644
index 0000000..4712bce
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/docs/frontend-selection.md
@@ -0,0 +1,12 @@
+# Frontend Selection
+
+Frontend integration is explicit through `frontendType`.
+
+- No heuristic detection in v1.
+- Deterministic mapping: `FrontendType -> FrontendStrategy`.
+- Current built-in strategy: `VITE`.
+
+Extension points:
+
+- register custom `FrontendStrategy` implementations in the resolver.
+- override default commands per config.
diff --git a/flash-extensions/flash-web-bundler/docs/modes.md b/flash-extensions/flash-web-bundler/docs/modes.md
new file mode 100644
index 0000000..adeeebc
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/docs/modes.md
@@ -0,0 +1,12 @@
+# Modes
+
+## Runtime Mode
+
+- `PROD`: production static serving only.
+- `AUTODETECT`: uses `Flash.DEV`.
+- `ENV`: uses `FLASH_WEB_BUNDLER_MODE` (`dev` => dev mode, else prod).
+
+## Operation Mode
+
+- `ORCHESTRATE_ONLY`: only orchestrates dev tooling.
+- `MANAGED`: enables production serving + SPA fallback routes.
diff --git a/flash-extensions/flash-web-bundler/docs/package-managers.md b/flash-extensions/flash-web-bundler/docs/package-managers.md
new file mode 100644
index 0000000..de3a7e6
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/docs/package-managers.md
@@ -0,0 +1,19 @@
+# Package Managers
+
+Package manager selection is explicit via `packageManager`.
+
+- `NPM` -> `package-lock.json`
+- `PNPM` -> `pnpm-lock.yaml`
+- `YARN` -> `yarn.lock`
+- `BUN` -> `bun.lockb`
+
+Install policy:
+
+- `AUTO_IF_LOCK_HASH_CHANGED`: install only when lock hash changes.
+- `NEVER`: never auto-install.
+
+Custom commands can override defaults via:
+
+- `installCommand`
+- `devCommand`
+- `buildCommand`
diff --git a/flash-extensions/flash-web-bundler/docs/performance.md b/flash-extensions/flash-web-bundler/docs/performance.md
new file mode 100644
index 0000000..84ce194
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/docs/performance.md
@@ -0,0 +1,13 @@
+# Performance Notes
+
+Current v1 optimizations:
+
+- startup preloading of static assets
+- precomputed ETags and MIME lookup
+- compressed payload selection based on `Accept-Encoding`
+- lockfile-hash install gate to avoid redundant installs
+
+Future performance work:
+
+- streaming/sliced file serving for large assets
+- benchmark suite with p50/p95/p99 latency and allocation profiling
diff --git a/flash-extensions/flash-web-bundler/docs/prod-serving.md b/flash-extensions/flash-web-bundler/docs/prod-serving.md
new file mode 100644
index 0000000..71db8bc
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/docs/prod-serving.md
@@ -0,0 +1,17 @@
+# Production Serving
+
+In production mode, `flash-web-bundler` serves only prebuilt assets.
+
+Behavior:
+
+- preloads files from `assetsSource` (filesystem or classpath)
+- resolves MIME by extension
+- supports precompressed siblings (`.br`, `.gz`)
+- sets `Cache-Control` and `ETag`
+- responds `304 Not Modified` when `If-None-Match` matches
+
+Classpath mode details:
+
+- reads entries from `asset-manifest.json` in classpath root
+- validates referenced resources at startup
+- fails fast in production if manifest or resources are inconsistent
diff --git a/flash-extensions/flash-web-bundler/docs/routing-fallback.md b/flash-extensions/flash-web-bundler/docs/routing-fallback.md
new file mode 100644
index 0000000..943762e
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/docs/routing-fallback.md
@@ -0,0 +1,10 @@
+# Routing Fallback
+
+Fallback policy:
+
+- backend routes always have precedence
+- fallback route is wildcard under configured `basePath`
+- fallback applies to `GET` and `HEAD` only
+- if no static asset matches, serve SPA `indexFile`
+
+Namespace collisions should be avoided at app design level (for example, keep API under `/api`).
diff --git a/flash-extensions/flash-web-bundler/docs/security-policies.md b/flash-extensions/flash-web-bundler/docs/security-policies.md
new file mode 100644
index 0000000..5a06ccf
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/docs/security-policies.md
@@ -0,0 +1,11 @@
+# Security Policies
+
+Command safety is enforced before process execution.
+
+Modes:
+
+- `WARN`: allow unknown binary and log warning.
+- `BLOCK`: reject unknown binary.
+- `ALLOW`: skip safe-registry checks.
+
+Safe registry defaults include common package-manager executables and is configurable.
diff --git a/flash-extensions/flash-web-bundler/pom.xml b/flash-extensions/flash-web-bundler/pom.xml
new file mode 100644
index 0000000..4466a2e
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/pom.xml
@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>dev.relism</groupId>
+        <artifactId>flash-extensions</artifactId>
+        <version>1.0-SNAPSHOT</version>
+    </parent>
+
+    <artifactId>flash-web-bundler</artifactId>
+
+    <dependencies>
+        <dependency>
+            <groupId>dev.relism</groupId>
+            <artifactId>flash</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.projectlombok</groupId>
+            <artifactId>lombok</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.slf4j</groupId>
+            <artifactId>slf4j-api</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>com.fasterxml.jackson.core</groupId>
+            <artifactId>jackson-databind</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter</artifactId>
+        </dependency>
+    </dependencies>
+</project>
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/AssetCatalog.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/AssetCatalog.java
new file mode 100644
index 0000000..358eb6b
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/AssetCatalog.java
@@ -0,0 +1,33 @@
+package dev.relism.ext.webbundler;
+
+import java.util.Map;
+
+public final class AssetCatalog {
+    private final Map<String, AssetEntry> byRoutePath;
+    private final AssetEntry index;
+
+    AssetCatalog(Map<String, AssetEntry> byRoutePath, AssetEntry index) {
+        this.byRoutePath = Map.copyOf(byRoutePath);
+        this.index = index;
+    }
+
+    AssetEntry find(String routePath) {
+        return byRoutePath.get(routePath);
+    }
+
+    AssetEntry index() {
+        return index;
+    }
+
+    public AssetEntry asset(String routePath) {
+        return find(routePath);
+    }
+
+    public AssetEntry indexAsset() {
+        return index;
+    }
+
+    public int size() {
+        return byRoutePath.size();
+    }
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/AssetEntry.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/AssetEntry.java
new file mode 100644
index 0000000..30fa765
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/AssetEntry.java
@@ -0,0 +1,11 @@
+package dev.relism.ext.webbundler;
+
+public record AssetEntry(
+        byte[] raw,
+        byte[] br,
+        byte[] gz,
+        String etag,
+        String mimeType,
+        boolean immutable
+) {
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/AssetIo.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/AssetIo.java
new file mode 100644
index 0000000..b1d2fa6
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/AssetIo.java
@@ -0,0 +1,93 @@
+package dev.relism.ext.webbundler;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.security.MessageDigest;
+import java.security.NoSuchAlgorithmException;
+
+final class AssetIo {
+    private AssetIo() {
+    }
+
+    static byte[] read(Path path) {
+        try {
+            return Files.readAllBytes(path);
+        } catch (IOException e) {
+            throw new IllegalStateException("Failed reading asset " + path, e);
+        }
+    }
+
+    static byte[] readClasspath(String path) {
+        try (InputStream in = AssetIo.class.getClassLoader().getResourceAsStream(stripLeadingSlash(path))) {
+            if (in == null) throw new IllegalStateException("Missing classpath resource: " + path);
+            return in.readAllBytes();
+        } catch (IOException e) {
+            throw new IllegalStateException("Failed reading classpath resource: " + path, e);
+        }
+    }
+
+    static byte[] readClasspathOrNull(String path) {
+        try (InputStream in = AssetIo.class.getClassLoader().getResourceAsStream(stripLeadingSlash(path))) {
+            if (in == null) return null;
+            return in.readAllBytes();
+        } catch (IOException e) {
+            throw new IllegalStateException("Failed reading classpath resource: " + path, e);
+        }
+    }
+
+    static String quotedSha1(byte[] data) {
+        return "\"" + sha1Hex(data) + "\"";
+    }
+
+    private static String sha1Hex(byte[] data) {
+        try {
+            MessageDigest md = MessageDigest.getInstance("SHA-1");
+            byte[] hash = md.digest(data);
+            StringBuilder out = new StringBuilder(hash.length * 2);
+            for (byte b : hash) {
+                out.append(String.format("%02x", b));
+            }
+            return out.toString();
+        } catch (NoSuchAlgorithmException e) {
+            throw new IllegalStateException("SHA-1 unavailable", e);
+        }
+    }
+
+    static String stripLeadingSlash(String path) {
+        if (path == null || path.isBlank()) return path;
+        return path.startsWith("/") ? path.substring(1) : path;
+    }
+
+    static String normalizePath(String path) {
+        if (path == null || path.isBlank()) return "/";
+        String p = path.replace('\\', '/');
+        if (!p.startsWith("/")) p = "/" + p;
+        return p;
+    }
+
+    static String stripBrGzSuffix(String path) {
+        if (path.endsWith(".br")) return path.substring(0, path.length() - 3);
+        if (path.endsWith(".gz")) return path.substring(0, path.length() - 3);
+        return path;
+    }
+
+    static boolean isFingerprinted(String path) {
+        String file = path;
+        int slash = file.lastIndexOf('/');
+        if (slash >= 0) file = file.substring(slash + 1);
+        int dot = file.lastIndexOf('.');
+        if (dot <= 0) return false;
+        int prevDot = file.lastIndexOf('.', dot - 1);
+        if (prevDot <= 0) return false;
+        String token = file.substring(prevDot + 1, dot);
+        if (token.length() < 8) return false;
+        for (int i = 0; i < token.length(); i++) {
+            char c = token.charAt(i);
+            boolean hex = (c >= '0' && c <= '9') || (c >= 'a' && c <= 'f') || (c >= 'A' && c <= 'F');
+            if (!hex) return false;
+        }
+        return true;
+    }
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/AssetLoadRequest.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/AssetLoadRequest.java
new file mode 100644
index 0000000..939c1e6
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/AssetLoadRequest.java
@@ -0,0 +1,12 @@
+package dev.relism.ext.webbundler;
+
+import java.nio.file.Path;
+
+public record AssetLoadRequest(String basePath, String indexFile, RuntimeEnvironment environment, Path webRoot) {
+    public AssetLoadRequest {
+        if (basePath == null || basePath.isBlank()) throw new IllegalArgumentException("basePath is required");
+        if (indexFile == null || indexFile.isBlank()) throw new IllegalArgumentException("indexFile is required");
+        if (environment == null) throw new IllegalArgumentException("environment is required");
+        if (webRoot == null) throw new IllegalArgumentException("webRoot is required");
+    }
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/AssetMetadata.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/AssetMetadata.java
new file mode 100644
index 0000000..1628ad6
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/AssetMetadata.java
@@ -0,0 +1,16 @@
+package dev.relism.ext.webbundler;
+
+record AssetMetadata(
+        String routePath,
+        String logicalPath,
+        String mimeType,
+        String etag,
+        boolean immutable
+) {
+    AssetMetadata {
+        if (routePath == null || routePath.isBlank()) throw new IllegalArgumentException("routePath is required");
+        if (logicalPath == null || logicalPath.isBlank()) throw new IllegalArgumentException("logicalPath is required");
+        if (mimeType == null || mimeType.isBlank()) throw new IllegalArgumentException("mimeType is required");
+        if (etag == null || etag.isBlank()) throw new IllegalArgumentException("etag is required");
+    }
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/AssetPaths.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/AssetPaths.java
new file mode 100644
index 0000000..7f7b9cb
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/AssetPaths.java
@@ -0,0 +1,26 @@
+package dev.relism.ext.webbundler;
+
+final class AssetPaths {
+    private AssetPaths() {
+    }
+
+    static String joinBase(String basePath, String routePath) {
+        String base = "/".equals(basePath) ? "" : basePath;
+        String route = AssetIo.normalizePath(routePath);
+        return base + route;
+    }
+
+    static String normalizePrefix(String prefix) {
+        if (prefix == null || prefix.isBlank()) return "";
+        String p = prefix.replace('\\', '/');
+        if (p.startsWith("/")) p = p.substring(1);
+        while (p.endsWith("/")) p = p.substring(0, p.length() - 1);
+        return p;
+    }
+
+    static String classpathJoin(String prefix, String relative) {
+        String p = normalizePrefix(prefix);
+        String r = AssetIo.stripLeadingSlash(relative).replace('\\', '/');
+        return p.isEmpty() ? r : p + "/" + r;
+    }
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/AssetsSource.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/AssetsSource.java
new file mode 100644
index 0000000..1f107d0
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/AssetsSource.java
@@ -0,0 +1,5 @@
+package dev.relism.ext.webbundler;
+
+public interface AssetsSource {
+    AssetCatalog load(AssetLoadRequest request);
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/AssetsSources.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/AssetsSources.java
new file mode 100644
index 0000000..ad7712e
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/AssetsSources.java
@@ -0,0 +1,16 @@
+package dev.relism.ext.webbundler;
+
+import java.nio.file.Path;
+
+public final class AssetsSources {
+    private AssetsSources() {
+    }
+
+    public static AssetsSource filesystem(Path distDir) {
+        return FilesystemAssetsSource.of(distDir);
+    }
+
+    public static AssetsSource classpath(String rootPrefix) {
+        return ClasspathAssetsSource.of(rootPrefix);
+    }
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/BasePathEnforcementMode.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/BasePathEnforcementMode.java
new file mode 100644
index 0000000..6c9bb87
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/BasePathEnforcementMode.java
@@ -0,0 +1,6 @@
+package dev.relism.ext.webbundler;
+
+public enum BasePathEnforcementMode {
+    WARN_ONLY,
+    STRICT
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/ClasspathAssetManifest.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/ClasspathAssetManifest.java
new file mode 100644
index 0000000..64b1958
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/ClasspathAssetManifest.java
@@ -0,0 +1,16 @@
+package dev.relism.ext.webbundler;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+import java.util.List;
+
+record ClasspathAssetManifest(@JsonProperty("assets") List<Entry> assets) {
+    record Entry(
+            @JsonProperty("routePath") String routePath,
+            @JsonProperty("resourcePath") String resourcePath,
+            @JsonProperty("mimeType") String mimeType,
+            @JsonProperty("etag") String etag,
+            @JsonProperty("immutable") boolean immutable
+    ) {
+    }
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/ClasspathAssetsSource.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/ClasspathAssetsSource.java
new file mode 100644
index 0000000..992ab17
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/ClasspathAssetsSource.java
@@ -0,0 +1,91 @@
+package dev.relism.ext.webbundler;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
+import java.util.HashMap;
+import java.util.Map;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+public final class ClasspathAssetsSource implements AssetsSource {
+    private static final ObjectMapper JSON = new ObjectMapper();
+
+    private final String rootPrefix;
+    private final String manifestResource;
+
+    private ClasspathAssetsSource(String rootPrefix, String manifestResource) {
+        this.rootPrefix = AssetPaths.normalizePrefix(rootPrefix);
+        this.manifestResource = AssetIo.stripLeadingSlash(manifestResource);
+    }
+
+    public static ClasspathAssetsSource of(String rootPrefix) {
+        if (rootPrefix == null || rootPrefix.isBlank()) {
+            throw new IllegalArgumentException("rootPrefix cannot be blank");
+        }
+        String normalized = AssetPaths.normalizePrefix(rootPrefix);
+        return new ClasspathAssetsSource(normalized, normalized + "/asset-manifest.json");
+    }
+
+    public static ClasspathAssetsSource of(String rootPrefix, String manifestResource) {
+        if (rootPrefix == null || rootPrefix.isBlank()) {
+            throw new IllegalArgumentException("rootPrefix cannot be blank");
+        }
+        if (manifestResource == null || manifestResource.isBlank()) {
+            throw new IllegalArgumentException("manifestResource cannot be blank");
+        }
+        return new ClasspathAssetsSource(rootPrefix, manifestResource);
+    }
+
+    @Override
+    public AssetCatalog load(AssetLoadRequest request) {
+        ClasspathAssetManifest manifest = readManifest();
+        if (manifest.assets() == null || manifest.assets().isEmpty()) {
+            throw new IllegalStateException("Classpath asset manifest has no assets: " + manifestResource);
+        }
+
+        Map<String, AssetEntry> byRoute = new HashMap<>();
+        for (ClasspathAssetManifest.Entry entry : manifest.assets()) {
+            AssetMetadata meta = toMeta(entry);
+            byte[] raw = AssetIo.readClasspath(resourcePath(meta.logicalPath()));
+            byte[] br = AssetIo.readClasspathOrNull(resourcePath(meta.logicalPath() + ".br"));
+            byte[] gz = AssetIo.readClasspathOrNull(resourcePath(meta.logicalPath() + ".gz"));
+            String routePath = AssetPaths.joinBase(request.basePath(), meta.routePath());
+            byRoute.put(routePath, new AssetEntry(raw, br, gz, meta.etag(), meta.mimeType(), meta.immutable()));
+        }
+
+        String indexRoute = AssetPaths.joinBase(request.basePath(), "/" + request.indexFile());
+        AssetEntry index = byRoute.get(indexRoute);
+        if (index == null) {
+            throw new IllegalStateException("Missing SPA fallback file in classpath manifest: " + indexRoute);
+        }
+        return new AssetCatalog(byRoute, index);
+    }
+
+    private ClasspathAssetManifest readManifest() {
+        try (InputStream in = ClasspathAssetsSource.class.getClassLoader().getResourceAsStream(manifestResource)) {
+            if (in == null) throw new IllegalStateException("Missing classpath manifest: " + manifestResource);
+            String json = new String(in.readAllBytes(), StandardCharsets.UTF_8);
+            return JSON.readValue(json, ClasspathAssetManifest.class);
+        } catch (IOException e) {
+            throw new IllegalStateException("Invalid classpath manifest: " + manifestResource, e);
+        }
+    }
+
+    private AssetMetadata toMeta(ClasspathAssetManifest.Entry entry) {
+        if (entry == null) throw new IllegalStateException("Manifest entry cannot be null");
+        String routePath = AssetIo.normalizePath(entry.routePath());
+        String logicalPath = entry.resourcePath();
+        if (logicalPath == null || logicalPath.isBlank()) {
+            throw new IllegalStateException("Manifest entry resourcePath is required");
+        }
+        return new AssetMetadata(routePath, logicalPath.trim(), entry.mimeType(), entry.etag(), entry.immutable());
+    }
+
+    private String resourcePath(String logicalPath) {
+        if (logicalPath.startsWith("/")) {
+            return logicalPath.substring(1);
+        }
+        return AssetPaths.classpathJoin(rootPrefix, logicalPath);
+    }
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/CommandOrchestrator.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/CommandOrchestrator.java
new file mode 100644
index 0000000..e4412ea
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/CommandOrchestrator.java
@@ -0,0 +1,187 @@
+package dev.relism.ext.webbundler;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.io.BufferedReader;
+import java.io.IOException;
+import java.io.InputStreamReader;
+import java.net.HttpURLConnection;
+import java.net.InetSocketAddress;
+import java.net.Socket;
+import java.net.URL;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Path;
+import java.time.Duration;
+import java.util.List;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.ThreadFactory;
+import java.util.concurrent.TimeUnit;
+
+final class CommandOrchestrator implements AutoCloseable {
+    private static final Logger log = LoggerFactory.getLogger(CommandOrchestrator.class);
+
+    private final WebBundlerConfig config;
+    private final CommandSafetyPolicy safetyPolicy;
+    private final ExecutorService logPool = Executors.newCachedThreadPool(daemonThreadFactory("flash-web-bundler-log"));
+    private Process devProcess;
+
+    CommandOrchestrator(WebBundlerConfig config, CommandSafetyPolicy safetyPolicy) {
+        this.config = config;
+        this.safetyPolicy = safetyPolicy;
+    }
+
+    void runBlocking(List<String> command, Path cwd) {
+        safetyPolicy.check(command);
+        Process process = start(command, cwd);
+        try {
+            int code = process.waitFor();
+            if (code != 0) {
+                throw new IllegalStateException("Command failed (" + code + "): " + String.join(" ", command));
+            }
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            throw new IllegalStateException("Interrupted while waiting process", e);
+        }
+    }
+
+    void startDevServer(List<String> command, Path cwd) {
+        if (devProcess != null && devProcess.isAlive()) return;
+        if (isPortOccupied(config.devHost(), config.devPort())) {
+            throw new IllegalStateException("Dev server port already occupied: " + config.devHost() + ":" + config.devPort());
+        }
+        safetyPolicy.check(command);
+        devProcess = start(command, cwd);
+    }
+
+    void healthcheck(String healthPath, Duration timeout) {
+        long deadline = System.currentTimeMillis() + timeout.toMillis();
+        String url = "http://" + config.devHost() + ":" + config.devPort() + healthPath;
+        while (System.currentTimeMillis() < deadline) {
+            if (devProcess == null || !devProcess.isAlive()) {
+                throw new IllegalStateException("Dev process exited before becoming healthy");
+            }
+            if (ping(url)) return;
+            sleep(200L);
+        }
+        throw new IllegalStateException("Dev server healthcheck timeout for " + url);
+    }
+
+    void restartDevServer(List<String> command, Path cwd) {
+        stopDevServer();
+        startDevServer(command, cwd);
+    }
+
+    void stopDevServer() {
+        if (devProcess == null) return;
+        destroyProcessTree(devProcess, 5);
+        devProcess = null;
+    }
+
+    @Override
+    public void close() {
+        stopDevServer();
+        logPool.shutdownNow();
+    }
+
+    private Process start(List<String> command, Path cwd) {
+        ProcessBuilder pb = new ProcessBuilder(command);
+        pb.directory(cwd.toFile());
+        try {
+            Process process = pb.start();
+            attachLogs(process, command.get(0));
+            return process;
+        } catch (IOException e) {
+            throw new IllegalStateException("Failed to launch process: " + String.join(" ", command), e);
+        }
+    }
+
+    private void attachLogs(Process process, String name) {
+        if (config.loggingMode() == LoggingMode.QUIET) return;
+        boolean merge = config.loggingMode() == LoggingMode.MERGED || config.loggingMode() == LoggingMode.VERBOSE;
+        if (merge) {
+            logPool.submit(() -> readStream(process.getInputStream(), "[" + name + "] "));
+            logPool.submit(() -> readStream(process.getErrorStream(), "[" + name + "] "));
+        } else {
+            logPool.submit(() -> readStream(process.getInputStream(), "[" + name + ":out] "));
+            logPool.submit(() -> readStream(process.getErrorStream(), "[" + name + ":err] "));
+        }
+    }
+
+    private void readStream(java.io.InputStream in, String prefix) {
+        try (BufferedReader r = new BufferedReader(new InputStreamReader(in, StandardCharsets.UTF_8))) {
+            String line;
+            while ((line = r.readLine()) != null) {
+                if (config.loggingMode() == LoggingMode.VERBOSE) log.info("{}{}", prefix, line);
+                else log.debug("{}{}", prefix, line);
+            }
+        } catch (IOException ignored) {
+        }
+    }
+
+    private static boolean ping(String rawUrl) {
+        try {
+            HttpURLConnection conn = (HttpURLConnection) new URL(rawUrl).openConnection();
+            conn.setConnectTimeout(500);
+            conn.setReadTimeout(500);
+            conn.setRequestMethod("GET");
+            int code = conn.getResponseCode();
+            return code >= 200 && code < 500;
+        } catch (IOException e) {
+            return false;
+        }
+    }
+
+    private static boolean isPortOccupied(String host, int port) {
+        try (Socket socket = new Socket()) {
+            socket.connect(new InetSocketAddress(host, port), 250);
+            return true;
+        } catch (IOException e) {
+            return false;
+        }
+    }
+
+    private static void sleep(long millis) {
+        try {
+            Thread.sleep(millis);
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+        }
+    }
+
+    private static ThreadFactory daemonThreadFactory(String namePrefix) {
+        return runnable -> {
+            Thread thread = new Thread(runnable, namePrefix);
+            thread.setDaemon(true);
+            return thread;
+        };
+    }
+
+    private static void destroyProcessTree(Process process, int gracefulSeconds) {
+        ProcessHandle root = process.toHandle();
+        List<ProcessHandle> descendants = root.descendants().toList();
+
+        // First pass: graceful termination for wrapper + children.
+        for (ProcessHandle child : descendants) child.destroy();
+        root.destroy();
+
+        waitForExit(root, gracefulSeconds);
+
+        // Second pass: force-kill anything still alive (important on Windows cmd wrappers).
+        for (ProcessHandle child : descendants) {
+            if (child.isAlive()) child.destroyForcibly();
+        }
+        if (root.isAlive()) root.destroyForcibly();
+
+        waitForExit(root, 2);
+    }
+
+    private static void waitForExit(ProcessHandle handle, int timeoutSeconds) {
+        try {
+            handle.onExit().get(timeoutSeconds, TimeUnit.SECONDS);
+        } catch (Exception ignored) {
+            // Best-effort shutdown; callers handle remaining state.
+        }
+    }
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/CommandSafetyMode.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/CommandSafetyMode.java
new file mode 100644
index 0000000..e8addfc
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/CommandSafetyMode.java
@@ -0,0 +1,7 @@
+package dev.relism.ext.webbundler;
+
+public enum CommandSafetyMode {
+    WARN,
+    BLOCK,
+    ALLOW
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/CommandSafetyPolicy.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/CommandSafetyPolicy.java
new file mode 100644
index 0000000..120134a
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/CommandSafetyPolicy.java
@@ -0,0 +1,27 @@
+package dev.relism.ext.webbundler;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.List;
+
+final class CommandSafetyPolicy {
+    private static final Logger log = LoggerFactory.getLogger(CommandSafetyPolicy.class);
+
+    private final WebBundlerConfig config;
+
+    CommandSafetyPolicy(WebBundlerConfig config) {
+        this.config = config;
+    }
+
+    void check(List<String> command) {
+        if (command.isEmpty()) throw new IllegalArgumentException("Command cannot be empty");
+        String binary = command.get(0);
+        boolean safe = config.safeCommandRegistry().contains(binary);
+        if (safe || config.commandSafetyMode() == CommandSafetyMode.ALLOW) return;
+        if (config.commandSafetyMode() == CommandSafetyMode.BLOCK) {
+            throw new IllegalStateException("Blocked unsafe command: " + String.join(" ", command));
+        }
+        log.warn("Executing command outside safe registry: {}", String.join(" ", command));
+    }
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/CommandTokens.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/CommandTokens.java
new file mode 100644
index 0000000..dd04944
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/CommandTokens.java
@@ -0,0 +1,14 @@
+package dev.relism.ext.webbundler;
+
+import java.util.Arrays;
+import java.util.List;
+
+final class CommandTokens {
+    private CommandTokens() {}
+
+    static List<String> split(String command) {
+        return Arrays.stream(command.trim().split("\\s+"))
+                .filter(s -> !s.isBlank())
+                .toList();
+    }
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/FilesystemAssetsSource.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/FilesystemAssetsSource.java
new file mode 100644
index 0000000..6a7e0ec
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/FilesystemAssetsSource.java
@@ -0,0 +1,72 @@
+package dev.relism.ext.webbundler;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.HashMap;
+import java.util.Map;
+
+public final class FilesystemAssetsSource implements AssetsSource {
+    private final Path distDir;
+
+    private FilesystemAssetsSource(Path distDir) {
+        this.distDir = distDir.normalize();
+    }
+
+    public static FilesystemAssetsSource of(Path distDir) {
+        if (distDir == null) throw new IllegalArgumentException("distDir cannot be null");
+        return new FilesystemAssetsSource(distDir);
+    }
+
+    @Override
+    public AssetCatalog load(AssetLoadRequest request) {
+        Path root = request.webRoot().resolve(distDir).normalize();
+        if (!Files.exists(root)) {
+            throw new IllegalStateException("distDir does not exist: " + root);
+        }
+
+        Map<String, AssetEntryBuilder> builders = new HashMap<>();
+        try (var walk = Files.walk(root)) {
+            walk.filter(Files::isRegularFile).forEach(file -> {
+                String rel = "/" + root.relativize(file).toString().replace('\\', '/');
+                String canonical = AssetIo.stripBrGzSuffix(rel);
+                String routePath = AssetPaths.joinBase(request.basePath(), canonical);
+                AssetEntryBuilder b = builders.computeIfAbsent(routePath, k -> new AssetEntryBuilder(canonical));
+                byte[] bytes = AssetIo.read(file);
+                if (rel.endsWith(".br")) b.br = bytes;
+                else if (rel.endsWith(".gz")) b.gz = bytes;
+                else b.raw = bytes;
+            });
+        } catch (IOException e) {
+            throw new IllegalStateException("Failed to preload assets from " + root, e);
+        }
+
+        Map<String, AssetEntry> byRoute = new HashMap<>();
+        for (Map.Entry<String, AssetEntryBuilder> e : builders.entrySet()) {
+            AssetEntryBuilder b = e.getValue();
+            if (b.raw == null) continue;
+            String etag = AssetIo.quotedSha1(b.raw);
+            String mime = MimeTypes.byPath(b.canonicalPath);
+            boolean immutable = AssetIo.isFingerprinted(b.canonicalPath);
+            byRoute.put(e.getKey(), new AssetEntry(b.raw, b.br, b.gz, etag, mime, immutable));
+        }
+
+        String indexRoute = AssetPaths.joinBase(request.basePath(), "/" + request.indexFile());
+        AssetEntry index = byRoute.get(indexRoute);
+        if (index == null) {
+            throw new IllegalStateException("Missing SPA fallback file: " + indexRoute + " (from " + root + ")");
+        }
+        return new AssetCatalog(byRoute, index);
+    }
+
+    private static final class AssetEntryBuilder {
+        private final String canonicalPath;
+        private byte[] raw;
+        private byte[] br;
+        private byte[] gz;
+
+        private AssetEntryBuilder(String canonicalPath) {
+            this.canonicalPath = canonicalPath;
+        }
+    }
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/FrontendStrategy.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/FrontendStrategy.java
new file mode 100644
index 0000000..419d90b
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/FrontendStrategy.java
@@ -0,0 +1,12 @@
+package dev.relism.ext.webbundler;
+
+import java.util.List;
+
+interface FrontendStrategy {
+    FrontendType type();
+    List<String> devCommand(WebBundlerConfig config, PackageManagerAdapter adapter);
+    List<String> buildCommand(WebBundlerConfig config, PackageManagerAdapter adapter);
+    default String healthcheckPath() {
+        return "/";
+    }
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/FrontendType.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/FrontendType.java
new file mode 100644
index 0000000..8215e6f
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/FrontendType.java
@@ -0,0 +1,5 @@
+package dev.relism.ext.webbundler;
+
+public enum FrontendType {
+    VITE
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/FrontendTypeResolver.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/FrontendTypeResolver.java
new file mode 100644
index 0000000..0d04a8a
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/FrontendTypeResolver.java
@@ -0,0 +1,24 @@
+package dev.relism.ext.webbundler;
+
+import java.util.EnumMap;
+import java.util.Map;
+
+final class FrontendTypeResolver {
+    private final Map<FrontendType, FrontendStrategy> strategies = new EnumMap<>(FrontendType.class);
+
+    FrontendTypeResolver() {
+        register(new ViteFrontendStrategy());
+    }
+
+    void register(FrontendStrategy strategy) {
+        strategies.put(strategy.type(), strategy);
+    }
+
+    FrontendStrategy resolve(FrontendType type) {
+        FrontendStrategy strategy = strategies.get(type);
+        if (strategy == null) {
+            throw new IllegalArgumentException("Unsupported frontend type: " + type);
+        }
+        return strategy;
+    }
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/InstallCache.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/InstallCache.java
new file mode 100644
index 0000000..470a89f
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/InstallCache.java
@@ -0,0 +1,57 @@
+package dev.relism.ext.webbundler;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.security.MessageDigest;
+import java.security.NoSuchAlgorithmException;
+
+final class InstallCache {
+    private final Path cacheFile;
+
+    InstallCache(Path webRoot) {
+        this.cacheFile = webRoot.resolve(".flash-web-bundler/install.hash");
+    }
+
+    boolean lockChanged(Path lockfile) {
+        if (!Files.exists(lockfile)) return true;
+        String current = digest(lockfile);
+        String previous = readCached();
+        return !current.equals(previous);
+    }
+
+    void writeLockHash(Path lockfile) {
+        if (!Files.exists(lockfile)) return;
+        try {
+            Files.createDirectories(cacheFile.getParent());
+            Files.writeString(cacheFile, digest(lockfile), StandardCharsets.UTF_8);
+        } catch (IOException e) {
+            throw new IllegalStateException("Failed to write install cache hash", e);
+        }
+    }
+
+    private String readCached() {
+        if (!Files.exists(cacheFile)) return "";
+        try {
+            return Files.readString(cacheFile, StandardCharsets.UTF_8).trim();
+        } catch (IOException e) {
+            return "";
+        }
+    }
+
+    private static String digest(Path file) {
+        try {
+            MessageDigest md = MessageDigest.getInstance("SHA-256");
+            byte[] bytes = Files.readAllBytes(file);
+            byte[] hash = md.digest(bytes);
+            StringBuilder sb = new StringBuilder(hash.length * 2);
+            for (byte b : hash) {
+                sb.append(String.format("%02x", b));
+            }
+            return sb.toString();
+        } catch (NoSuchAlgorithmException | IOException e) {
+            throw new IllegalStateException("Unable to hash lockfile " + file, e);
+        }
+    }
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/InstallPolicy.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/InstallPolicy.java
new file mode 100644
index 0000000..d30d5d6
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/InstallPolicy.java
@@ -0,0 +1,6 @@
+package dev.relism.ext.webbundler;
+
+public enum InstallPolicy {
+    AUTO_IF_LOCK_HASH_CHANGED,
+    NEVER
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/LoggingMode.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/LoggingMode.java
new file mode 100644
index 0000000..cffb10e
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/LoggingMode.java
@@ -0,0 +1,8 @@
+package dev.relism.ext.webbundler;
+
+public enum LoggingMode {
+    MERGED,
+    SEPARATE,
+    QUIET,
+    VERBOSE
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/MimeTypes.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/MimeTypes.java
new file mode 100644
index 0000000..d94c9b3
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/MimeTypes.java
@@ -0,0 +1,30 @@
+package dev.relism.ext.webbundler;
+
+import java.util.Map;
+
+final class MimeTypes {
+    private static final Map<String, String> EXT = Map.ofEntries(
+            Map.entry("html", "text/html"),
+            Map.entry("js", "text/javascript"),
+            Map.entry("css", "text/css"),
+            Map.entry("json", "application/json"),
+            Map.entry("svg", "image/svg+xml"),
+            Map.entry("png", "image/png"),
+            Map.entry("jpg", "image/jpeg"),
+            Map.entry("jpeg", "image/jpeg"),
+            Map.entry("gif", "image/gif"),
+            Map.entry("ico", "image/x-icon"),
+            Map.entry("woff2", "font/woff2"),
+            Map.entry("ttf", "font/ttf"),
+            Map.entry("txt", "text/plain")
+    );
+
+    private MimeTypes() {}
+
+    static String byPath(String path) {
+        int idx = path.lastIndexOf('.');
+        if (idx < 0 || idx == path.length() - 1) return "application/octet-stream";
+        String ext = path.substring(idx + 1).toLowerCase();
+        return EXT.getOrDefault(ext, "application/octet-stream");
+    }
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/ModeResolver.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/ModeResolver.java
new file mode 100644
index 0000000..7e60c70
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/ModeResolver.java
@@ -0,0 +1,19 @@
+package dev.relism.ext.webbundler;
+
+import dev.relism.Flash;
+
+final class ModeResolver {
+    RuntimeEnvironment resolve(WebBundlerConfig config) {
+        return switch (config.runtimeMode()) {
+            case PROD -> RuntimeEnvironment.PROD;
+            case AUTODETECT -> Flash.DEV ? RuntimeEnvironment.DEV : RuntimeEnvironment.PROD;
+            case ENV -> fromEnvironment(config.envRuntimeVariable());
+        };
+    }
+
+    private RuntimeEnvironment fromEnvironment(String key) {
+        String value = System.getenv(key);
+        if (value == null || value.isBlank()) return RuntimeEnvironment.PROD;
+        return "dev".equalsIgnoreCase(value) ? RuntimeEnvironment.DEV : RuntimeEnvironment.PROD;
+    }
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/OperationMode.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/OperationMode.java
new file mode 100644
index 0000000..21bfb9e
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/OperationMode.java
@@ -0,0 +1,6 @@
+package dev.relism.ext.webbundler;
+
+public enum OperationMode {
+    ORCHESTRATE_ONLY,
+    MANAGED
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/PackageManager.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/PackageManager.java
new file mode 100644
index 0000000..92e9375
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/PackageManager.java
@@ -0,0 +1,24 @@
+package dev.relism.ext.webbundler;
+
+public enum PackageManager {
+    NPM("npm", "package-lock.json"),
+    PNPM("pnpm", "pnpm-lock.yaml"),
+    YARN("yarn", "yarn.lock"),
+    BUN("bun", "bun.lockb");
+
+    private final String binary;
+    private final String lockfileName;
+
+    PackageManager(String binary, String lockfileName) {
+        this.binary = binary;
+        this.lockfileName = lockfileName;
+    }
+
+    public String binary() {
+        return binary;
+    }
+
+    public String lockfileName() {
+        return lockfileName;
+    }
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/PackageManagerAdapter.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/PackageManagerAdapter.java
new file mode 100644
index 0000000..fabadf9
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/PackageManagerAdapter.java
@@ -0,0 +1,44 @@
+package dev.relism.ext.webbundler;
+
+import java.util.List;
+
+final class PackageManagerAdapter {
+    private final WebBundlerConfig config;
+    private final boolean windows = System.getProperty("os.name", "").toLowerCase().contains("win");
+
+    PackageManagerAdapter(WebBundlerConfig config) {
+        this.config = config;
+    }
+
+    List<String> installCommand() {
+        if (config.installCommand() != null) return CommandTokens.split(config.installCommand());
+        return switch (config.packageManager()) {
+            case NPM -> List.of(bin("npm"), "install");
+            case PNPM -> List.of(bin("pnpm"), "install", "--frozen-lockfile");
+            case YARN -> List.of(bin("yarn"), "install", "--frozen-lockfile");
+            case BUN -> List.of(bin("bun"), "install", "--frozen-lockfile");
+        };
+    }
+
+    List<String> devCommand(String host, int port) {
+        return switch (config.packageManager()) {
+            case NPM -> List.of(bin("npm"), "run", "dev", "--", "--host", host, "--port", String.valueOf(port));
+            case PNPM -> List.of(bin("pnpm"), "dev", "--host", host, "--port", String.valueOf(port));
+            case YARN -> List.of(bin("yarn"), "dev", "--host", host, "--port", String.valueOf(port));
+            case BUN -> List.of(bin("bun"), "run", "dev", "--host", host, "--port", String.valueOf(port));
+        };
+    }
+
+    List<String> buildCommand() {
+        return switch (config.packageManager()) {
+            case NPM -> List.of(bin("npm"), "run", "build");
+            case PNPM -> List.of(bin("pnpm"), "build");
+            case YARN -> List.of(bin("yarn"), "build");
+            case BUN -> List.of(bin("bun"), "run", "build");
+        };
+    }
+
+    private String bin(String name) {
+        return windows ? name + ".cmd" : name;
+    }
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/RuntimeEnvironment.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/RuntimeEnvironment.java
new file mode 100644
index 0000000..fd59822
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/RuntimeEnvironment.java
@@ -0,0 +1,6 @@
+package dev.relism.ext.webbundler;
+
+enum RuntimeEnvironment {
+    DEV,
+    PROD
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/RuntimeMode.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/RuntimeMode.java
new file mode 100644
index 0000000..ab2631c
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/RuntimeMode.java
@@ -0,0 +1,7 @@
+package dev.relism.ext.webbundler;
+
+public enum RuntimeMode {
+    PROD,
+    ENV,
+    AUTODETECT
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/SpaFallbackPolicy.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/SpaFallbackPolicy.java
new file mode 100644
index 0000000..c6def81
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/SpaFallbackPolicy.java
@@ -0,0 +1,17 @@
+package dev.relism.ext.webbundler;
+
+import dev.relism.models.Response;
+
+final class SpaFallbackPolicy {
+    private final byte[] html;
+
+    SpaFallbackPolicy(AssetCatalog catalog) {
+        this.html = catalog.index().raw();
+    }
+
+    void apply(Response response) {
+        response.type("text/html");
+        response.header("Cache-Control", "no-cache");
+        response.body(html);
+    }
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/StaticAssetServingPolicy.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/StaticAssetServingPolicy.java
new file mode 100644
index 0000000..bee76a7
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/StaticAssetServingPolicy.java
@@ -0,0 +1,46 @@
+package dev.relism.ext.webbundler;
+
+import dev.relism.http.HttpStatus;
+import dev.relism.models.Request;
+import dev.relism.models.Response;
+
+final class StaticAssetServingPolicy {
+    private final AssetCatalog catalog;
+
+    StaticAssetServingPolicy(AssetCatalog catalog) {
+        this.catalog = catalog;
+    }
+
+    boolean serve(Request req, Response res) {
+        AssetEntry entry = catalog.find(req.path());
+        if (entry == null) return false;
+        String inm = req.header("If-None-Match");
+        if (entry.etag().equals(inm)) {
+            res.status(HttpStatus.NOT_MODIFIED);
+            return true;
+        }
+        res.type(entry.mimeType());
+        if (entry.immutable()) {
+            res.header("Cache-Control", "public, max-age=31536000, immutable");
+        } else {
+            res.header("Cache-Control", "no-cache");
+        }
+        res.header("ETag", entry.etag());
+        res.header("Vary", "Accept-Encoding");
+        if (accepts(req, "br") && entry.br() != null) {
+            res.header("Content-Encoding", "br");
+            res.body(entry.br());
+        } else if (accepts(req, "gzip") && entry.gz() != null) {
+            res.header("Content-Encoding", "gzip");
+            res.body(entry.gz());
+        } else {
+            res.body(entry.raw());
+        }
+        return true;
+    }
+
+    private static boolean accepts(Request req, String encoding) {
+        String value = req.header("Accept-Encoding");
+        return value != null && value.contains(encoding);
+    }
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/ViteFrontendStrategy.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/ViteFrontendStrategy.java
new file mode 100644
index 0000000..492a468
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/ViteFrontendStrategy.java
@@ -0,0 +1,26 @@
+package dev.relism.ext.webbundler;
+
+import java.util.List;
+
+final class ViteFrontendStrategy implements FrontendStrategy {
+    @Override
+    public FrontendType type() {
+        return FrontendType.VITE;
+    }
+
+    @Override
+    public List<String> devCommand(WebBundlerConfig config, PackageManagerAdapter adapter) {
+        if (config.devCommand() != null) {
+            return CommandTokens.split(config.devCommand());
+        }
+        return adapter.devCommand(config.devHost(), config.devPort());
+    }
+
+    @Override
+    public List<String> buildCommand(WebBundlerConfig config, PackageManagerAdapter adapter) {
+        if (config.buildCommand() != null) {
+            return CommandTokens.split(config.buildCommand());
+        }
+        return adapter.buildCommand();
+    }
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/WatchList.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/WatchList.java
new file mode 100644
index 0000000..b206d24
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/WatchList.java
@@ -0,0 +1,43 @@
+package dev.relism.ext.webbundler;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.HashMap;
+import java.util.Map;
+
+final class WatchList {
+    private final Path webRoot;
+    private final Map<Path, Long> lastKnown = new HashMap<>();
+
+    WatchList(Path webRoot) {
+        this.webRoot = webRoot;
+    }
+
+    void initialize(Iterable<String> watchEntries) {
+        for (String entry : watchEntries) {
+            Path file = webRoot.resolve(entry).normalize();
+            lastKnown.put(file, lastModified(file));
+        }
+    }
+
+    boolean changed() {
+        for (Map.Entry<Path, Long> entry : lastKnown.entrySet()) {
+            long current = lastModified(entry.getKey());
+            if (current != entry.getValue()) {
+                entry.setValue(current);
+                return true;
+            }
+        }
+        return false;
+    }
+
+    private static long lastModified(Path path) {
+        try {
+            if (!Files.exists(path)) return -1L;
+            return Files.getLastModifiedTime(path).toMillis();
+        } catch (IOException e) {
+            return -1L;
+        }
+    }
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/WebBundlerConfig.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/WebBundlerConfig.java
new file mode 100644
index 0000000..a3b21c1
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/WebBundlerConfig.java
@@ -0,0 +1,210 @@
+package dev.relism.ext.webbundler;
+
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Objects;
+
+public final class WebBundlerConfig {
+    private final RuntimeMode runtimeMode;
+    private final OperationMode operationMode;
+    private final FrontendType frontendType;
+    private final PackageManager packageManager;
+    private final InstallPolicy installPolicy;
+    private final LoggingMode loggingMode;
+    private final CommandSafetyMode commandSafetyMode;
+    private final BasePathEnforcementMode basePathEnforcement;
+    private final Path webRoot;
+    private final String basePath;
+    private final String devHost;
+    private final int devPort;
+    private final AssetsSource assetsSource;
+    private final String indexFile;
+    private final List<String> watchList;
+    private final String devCommand;
+    private final String buildCommand;
+    private final String installCommand;
+    private final List<String> safeCommandRegistry;
+    private final String envRuntimeVariable;
+
+    private WebBundlerConfig(Builder b) {
+        this.runtimeMode = b.runtimeMode;
+        this.operationMode = b.operationMode;
+        this.frontendType = b.frontendType;
+        this.packageManager = b.packageManager;
+        this.installPolicy = b.installPolicy;
+        this.loggingMode = b.loggingMode;
+        this.commandSafetyMode = b.commandSafetyMode;
+        this.basePathEnforcement = b.basePathEnforcement;
+        this.webRoot = b.webRoot.normalize();
+        this.basePath = sanitizeBasePath(b.basePath);
+        this.devHost = b.devHost;
+        this.devPort = b.devPort;
+        this.assetsSource = b.assetsSource;
+        this.indexFile = b.indexFile;
+        this.watchList = List.copyOf(b.watchList);
+        this.devCommand = blankToNull(b.devCommand);
+        this.buildCommand = blankToNull(b.buildCommand);
+        this.installCommand = blankToNull(b.installCommand);
+        this.safeCommandRegistry = List.copyOf(b.safeCommandRegistry);
+        this.envRuntimeVariable = b.envRuntimeVariable;
+        validate();
+    }
+
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    public RuntimeMode runtimeMode() { return runtimeMode; }
+    public OperationMode operationMode() { return operationMode; }
+    public FrontendType frontendType() { return frontendType; }
+    public PackageManager packageManager() { return packageManager; }
+    public InstallPolicy installPolicy() { return installPolicy; }
+    public LoggingMode loggingMode() { return loggingMode; }
+    public CommandSafetyMode commandSafetyMode() { return commandSafetyMode; }
+    public BasePathEnforcementMode basePathEnforcement() { return basePathEnforcement; }
+    public Path webRoot() { return webRoot; }
+    public String basePath() { return basePath; }
+    public String devHost() { return devHost; }
+    public int devPort() { return devPort; }
+    public AssetsSource assetsSource() { return assetsSource; }
+    public String indexFile() { return indexFile; }
+    public List<String> watchList() { return watchList; }
+    public String devCommand() { return devCommand; }
+    public String buildCommand() { return buildCommand; }
+    public String installCommand() { return installCommand; }
+    public List<String> safeCommandRegistry() { return safeCommandRegistry; }
+    public String envRuntimeVariable() { return envRuntimeVariable; }
+
+    public Path expectedLockfile() {
+        return webRoot.resolve(packageManager.lockfileName());
+    }
+
+    private void validate() {
+        Objects.requireNonNull(runtimeMode, "runtimeMode");
+        Objects.requireNonNull(operationMode, "operationMode");
+        Objects.requireNonNull(frontendType, "frontendType");
+        Objects.requireNonNull(packageManager, "packageManager");
+        Objects.requireNonNull(installPolicy, "installPolicy");
+        Objects.requireNonNull(loggingMode, "loggingMode");
+        Objects.requireNonNull(commandSafetyMode, "commandSafetyMode");
+        Objects.requireNonNull(basePathEnforcement, "basePathEnforcement");
+        Objects.requireNonNull(webRoot, "webRoot");
+        Objects.requireNonNull(assetsSource, "assetsSource");
+        Objects.requireNonNull(indexFile, "indexFile");
+        if (devPort <= 0 || devPort > 65535) {
+            throw new IllegalArgumentException("WebBundlerConfig: devPort must be in range 1..65535");
+        }
+        if (watchList.isEmpty()) {
+            throw new IllegalArgumentException("WebBundlerConfig: watchList must not be empty");
+        }
+        for (String path : watchList) {
+            if (path == null || path.isBlank()) {
+                throw new IllegalArgumentException("WebBundlerConfig: watchList contains blank entries");
+            }
+        }
+        if (!basePath.startsWith("/")) {
+            throw new IllegalArgumentException("WebBundlerConfig: basePath must start with '/'");
+        }
+    }
+
+    private static String sanitizeBasePath(String raw) {
+        if (raw == null || raw.isBlank()) return "/";
+        String normalized = raw.trim();
+        if (!normalized.startsWith("/")) normalized = "/" + normalized;
+        if (normalized.length() > 1 && normalized.endsWith("/")) {
+            normalized = normalized.substring(0, normalized.length() - 1);
+        }
+        return normalized;
+    }
+
+    private static String blankToNull(String value) {
+        return value == null || value.isBlank() ? null : value.trim();
+    }
+
+    public static final class Builder {
+        private RuntimeMode runtimeMode = RuntimeMode.AUTODETECT;
+        private OperationMode operationMode = OperationMode.ORCHESTRATE_ONLY;
+        private FrontendType frontendType = FrontendType.VITE;
+        private PackageManager packageManager = PackageManager.NPM;
+        private InstallPolicy installPolicy = InstallPolicy.AUTO_IF_LOCK_HASH_CHANGED;
+        private LoggingMode loggingMode = LoggingMode.MERGED;
+        private CommandSafetyMode commandSafetyMode = CommandSafetyMode.WARN;
+        private BasePathEnforcementMode basePathEnforcement = BasePathEnforcementMode.WARN_ONLY;
+        private Path webRoot = Path.of("web");
+        private String basePath = "/";
+        private String devHost = "127.0.0.1";
+        private int devPort = 5173;
+        private AssetsSource assetsSource = FilesystemAssetsSource.of(Path.of("dist"));
+        private String indexFile = "index.html";
+        private List<String> watchList = defaultWatchList(PackageManager.NPM);
+        private String devCommand;
+        private String buildCommand;
+        private String installCommand;
+        private List<String> safeCommandRegistry = defaultSafeRegistry();
+        private String envRuntimeVariable = "FLASH_WEB_BUNDLER_MODE";
+
+        public Builder runtimeMode(RuntimeMode runtimeMode) { this.runtimeMode = runtimeMode; return this; }
+        public Builder operationMode(OperationMode operationMode) { this.operationMode = operationMode; return this; }
+        public Builder frontendType(FrontendType frontendType) { this.frontendType = frontendType; return this; }
+        public Builder packageManager(PackageManager packageManager) {
+            this.packageManager = packageManager;
+            this.watchList = defaultWatchList(packageManager);
+            return this;
+        }
+        public Builder installPolicy(InstallPolicy installPolicy) { this.installPolicy = installPolicy; return this; }
+        public Builder loggingMode(LoggingMode loggingMode) { this.loggingMode = loggingMode; return this; }
+        public Builder commandSafetyMode(CommandSafetyMode commandSafetyMode) { this.commandSafetyMode = commandSafetyMode; return this; }
+        public Builder basePathEnforcement(BasePathEnforcementMode basePathEnforcement) { this.basePathEnforcement = basePathEnforcement; return this; }
+        public Builder webRoot(Path webRoot) { this.webRoot = webRoot; return this; }
+        public Builder basePath(String basePath) { this.basePath = basePath; return this; }
+        public Builder devHost(String devHost) { this.devHost = devHost; return this; }
+        public Builder devPort(int devPort) { this.devPort = devPort; return this; }
+        public Builder assetsSource(AssetsSource assetsSource) { this.assetsSource = assetsSource; return this; }
+        public Builder assetsFromFilesystem(Path distDir) {
+            this.assetsSource = FilesystemAssetsSource.of(distDir);
+            return this;
+        }
+        public Builder assetsFromClasspath(String rootPrefix) {
+            this.assetsSource = ClasspathAssetsSource.of(rootPrefix);
+            return this;
+        }
+        public Builder assetsFromClasspath(String rootPrefix, String manifestResource) {
+            this.assetsSource = ClasspathAssetsSource.of(rootPrefix, manifestResource);
+            return this;
+        }
+        public Builder indexFile(String indexFile) { this.indexFile = indexFile; return this; }
+        public Builder watchList(List<String> watchList) { this.watchList = new ArrayList<>(watchList); return this; }
+        public Builder devCommand(String devCommand) { this.devCommand = devCommand; return this; }
+        public Builder buildCommand(String buildCommand) { this.buildCommand = buildCommand; return this; }
+        public Builder installCommand(String installCommand) { this.installCommand = installCommand; return this; }
+        public Builder safeCommandRegistry(List<String> safeCommandRegistry) {
+            this.safeCommandRegistry = new ArrayList<>(safeCommandRegistry);
+            return this;
+        }
+        public Builder envRuntimeVariable(String envRuntimeVariable) { this.envRuntimeVariable = envRuntimeVariable; return this; }
+
+        public WebBundlerConfig build() {
+            return new WebBundlerConfig(this);
+        }
+
+        private static List<String> defaultWatchList(PackageManager manager) {
+            return List.of(
+                    "package.json",
+                    manager.lockfileName(),
+                    "vite.config.ts",
+                    "vite.config.js",
+                    "tsconfig.json",
+                    ".env",
+                    ".env.local"
+            );
+        }
+
+        private static List<String> defaultSafeRegistry() {
+            return List.of(
+                    "npm", "pnpm", "yarn", "bun", "npx",
+                    "npm.cmd", "pnpm.cmd", "yarn.cmd", "bun.cmd", "npx.cmd"
+            );
+        }
+    }
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/WebBundlerExtension.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/WebBundlerExtension.java
new file mode 100644
index 0000000..12c4030
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/WebBundlerExtension.java
@@ -0,0 +1,163 @@
+package dev.relism.ext.webbundler;
+
+import dev.relism.extension.ExtensionPhase;
+import dev.relism.extension.FlashContext;
+import dev.relism.extension.FlashExtension;
+import dev.relism.extension.FlashRegistrar;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.nio.file.Path;
+import java.time.Duration;
+import java.util.List;
+import java.util.concurrent.Executors;
+import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.ThreadFactory;
+import java.util.concurrent.TimeUnit;
+
+public final class WebBundlerExtension implements FlashExtension {
+    private static final Logger log = LoggerFactory.getLogger(WebBundlerExtension.class);
+
+    private final WebBundlerConfig config;
+    private final ModeResolver modeResolver = new ModeResolver();
+    private final FrontendTypeResolver frontendTypeResolver = new FrontendTypeResolver();
+    private ScheduledExecutorService watchLoop;
+    private Thread shutdownHook;
+
+    @Override
+    public int priority() {
+        return ExtensionPhase.LATE.value;
+    }
+
+    public WebBundlerExtension() {
+        this(WebBundlerConfig.builder().build());
+    }
+
+    public WebBundlerExtension(WebBundlerConfig config) {
+        this.config = config;
+    }
+
+    @Override
+    public void provide(FlashContext ctx) {
+        RuntimeEnvironment environment = modeResolver.resolve(config);
+        PackageManagerAdapter pmAdapter = new PackageManagerAdapter(config);
+        FrontendStrategy strategy = frontendTypeResolver.resolve(config.frontendType());
+        CommandSafetyPolicy safetyPolicy = new CommandSafetyPolicy(config);
+        CommandOrchestrator orchestrator = new CommandOrchestrator(config, safetyPolicy);
+        WatchList watchList = new WatchList(config.webRoot());
+        watchList.initialize(config.watchList());
+
+        StaticAssetServingPolicy servingPolicy = null;
+        SpaFallbackPolicy fallbackPolicy = null;
+
+        try {
+            if (environment == RuntimeEnvironment.DEV) {
+                bootstrapDev(strategy, pmAdapter, orchestrator, watchList);
+            } else {
+                AssetCatalog catalog = config.assetsSource().load(new AssetLoadRequest(
+                        config.basePath(),
+                        config.indexFile(),
+                        environment,
+                        config.webRoot()
+                ));
+                servingPolicy = new StaticAssetServingPolicy(catalog);
+                fallbackPolicy = new SpaFallbackPolicy(catalog);
+                log.info("flash-web-bundler loaded {} assets for production serving", catalog.size());
+            }
+
+            WebBundlerRuntime runtime = new WebBundlerRuntime(
+                    environment, servingPolicy, fallbackPolicy, orchestrator, watchList
+            );
+            registerShutdownHook(runtime);
+            ctx.provide(WebBundlerRuntime.class, runtime);
+        } catch (RuntimeException ex) {
+            shutdownResources(orchestrator);
+            throw ex;
+        }
+    }
+
+    @Override
+    public void routes(FlashRegistrar<?> app, FlashContext ctx) {
+        WebBundlerRuntime runtime = ctx.require(WebBundlerRuntime.class);
+        if (runtime.environment() == RuntimeEnvironment.DEV || config.operationMode() == OperationMode.ORCHESTRATE_ONLY) {
+            return;
+        }
+
+        String basePath = config.basePath();
+        String wildcard = "/".equals(basePath) ? "/**" : basePath + "/**";
+
+        app.get(wildcard, (req, res) -> {
+            if (runtime.servingPolicy().serve(req, res)) return null;
+            runtime.fallbackPolicy().apply(res);
+            return null;
+        });
+        app.head(wildcard, (req, res) -> {
+            if (runtime.servingPolicy().serve(req, res)) {
+                res.body(new byte[0]);
+                return null;
+            }
+            runtime.fallbackPolicy().apply(res);
+            res.body(new byte[0]);
+            return null;
+        });
+    }
+
+    private void bootstrapDev(
+            FrontendStrategy strategy,
+            PackageManagerAdapter pmAdapter,
+            CommandOrchestrator orchestrator,
+            WatchList watchList
+    ) {
+        validateDevAssetsSource(config);
+        InstallCache installCache = new InstallCache(config.webRoot());
+        Path lock = config.expectedLockfile();
+        if (config.installPolicy() == InstallPolicy.AUTO_IF_LOCK_HASH_CHANGED && installCache.lockChanged(lock)) {
+            orchestrator.runBlocking(pmAdapter.installCommand(), config.webRoot());
+            installCache.writeLockHash(lock);
+        }
+
+        List<String> devCommand = strategy.devCommand(config, pmAdapter);
+        orchestrator.startDevServer(devCommand, config.webRoot());
+        orchestrator.healthcheck(strategy.healthcheckPath(), Duration.ofSeconds(25));
+        startWatchLoop(devCommand, orchestrator, watchList);
+        log.info("flash-web-bundler started dev server at http://{}:{}", config.devHost(), config.devPort());
+    }
+
+    static void validateDevAssetsSource(WebBundlerConfig config) {
+        if (config.assetsSource() instanceof ClasspathAssetsSource) {
+            throw new IllegalStateException("Classpath assets source is not supported in DEV mode. Use assetsFromFilesystem(...) for DEV.");
+        }
+    }
+
+    private void startWatchLoop(List<String> devCommand, CommandOrchestrator orchestrator, WatchList watchList) {
+        watchLoop = Executors.newSingleThreadScheduledExecutor(daemonThreadFactory("flash-web-bundler-watch"));
+        watchLoop.scheduleWithFixedDelay(() -> {
+            if (watchList.changed()) {
+                log.warn("Watchlist changed. Restarting frontend dev server.");
+                orchestrator.restartDevServer(devCommand, config.webRoot());
+            }
+        }, 1500L, 1500L, TimeUnit.MILLISECONDS);
+    }
+
+    private void registerShutdownHook(WebBundlerRuntime runtime) {
+        shutdownHook = new Thread(() -> shutdownResources(runtime.orchestrator()), "flash-web-bundler-shutdown");
+        shutdownHook.setDaemon(true);
+        Runtime.getRuntime().addShutdownHook(shutdownHook);
+    }
+
+    private void shutdownResources(CommandOrchestrator orchestrator) {
+        if (watchLoop != null) {
+            watchLoop.shutdownNow();
+            watchLoop = null;
+        }
+        orchestrator.close();
+    }
+
+    private static ThreadFactory daemonThreadFactory(String namePrefix) {
+        return runnable -> {
+            Thread thread = new Thread(runnable, namePrefix);
+            thread.setDaemon(true);
+            return thread;
+        };
+    }
+}
diff --git a/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/WebBundlerRuntime.java b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/WebBundlerRuntime.java
new file mode 100644
index 0000000..53aa9ee
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/main/java/dev/relism/ext/webbundler/WebBundlerRuntime.java
@@ -0,0 +1,29 @@
+package dev.relism.ext.webbundler;
+
+final class WebBundlerRuntime {
+    private final RuntimeEnvironment environment;
+    private final StaticAssetServingPolicy servingPolicy;
+    private final SpaFallbackPolicy fallbackPolicy;
+    private final CommandOrchestrator orchestrator;
+    private final WatchList watchList;
+
+    WebBundlerRuntime(
+            RuntimeEnvironment environment,
+            StaticAssetServingPolicy servingPolicy,
+            SpaFallbackPolicy fallbackPolicy,
+            CommandOrchestrator orchestrator,
+            WatchList watchList
+    ) {
+        this.environment = environment;
+        this.servingPolicy = servingPolicy;
+        this.fallbackPolicy = fallbackPolicy;
+        this.orchestrator = orchestrator;
+        this.watchList = watchList;
+    }
+
+    RuntimeEnvironment environment() { return environment; }
+    StaticAssetServingPolicy servingPolicy() { return servingPolicy; }
+    SpaFallbackPolicy fallbackPolicy() { return fallbackPolicy; }
+    CommandOrchestrator orchestrator() { return orchestrator; }
+    WatchList watchList() { return watchList; }
+}
diff --git a/flash-extensions/flash-web-bundler/src/test/java/dev/relism/ext/webbundler/AssetsSourceTest.java b/flash-extensions/flash-web-bundler/src/test/java/dev/relism/ext/webbundler/AssetsSourceTest.java
new file mode 100644
index 0000000..5f6eff7
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/test/java/dev/relism/ext/webbundler/AssetsSourceTest.java
@@ -0,0 +1,39 @@
+package dev.relism.ext.webbundler;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+class AssetsSourceTest {
+    @TempDir
+    Path tempDir;
+
+    @Test
+    void filesystemSource_loadsAssetsAndIndex() throws Exception {
+        Path webRoot = tempDir.resolve("web");
+        Path dist = webRoot.resolve("dist");
+        Files.createDirectories(dist);
+        Files.writeString(dist.resolve("index.html"), "<html>ok</html>");
+        Files.writeString(dist.resolve("app.abcd1234.js"), "console.log(1)");
+
+        AssetsSource source = FilesystemAssetsSource.of(Path.of("dist"));
+        AssetCatalog catalog = source.load(new AssetLoadRequest("/app", "index.html", RuntimeEnvironment.PROD, webRoot));
+
+        assertNotNull(catalog.index());
+        AssetEntry js = catalog.find("/app/app.abcd1234.js");
+        assertNotNull(js);
+        assertTrue(js.immutable());
+    }
+
+    @Test
+    void classpathSource_missingManifestFailsFast() {
+        AssetsSource source = ClasspathAssetsSource.of("missing-root");
+        IllegalStateException ex = assertThrows(IllegalStateException.class,
+                () -> source.load(new AssetLoadRequest("/", "index.html", RuntimeEnvironment.PROD, Path.of("."))));
+        assertTrue(ex.getMessage().contains("manifest"));
+    }
+}
diff --git a/flash-extensions/flash-web-bundler/src/test/java/dev/relism/ext/webbundler/CommandSafetyPolicyTest.java b/flash-extensions/flash-web-bundler/src/test/java/dev/relism/ext/webbundler/CommandSafetyPolicyTest.java
new file mode 100644
index 0000000..9f715aa
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/test/java/dev/relism/ext/webbundler/CommandSafetyPolicyTest.java
@@ -0,0 +1,30 @@
+package dev.relism.ext.webbundler;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+class CommandSafetyPolicyTest {
+    @Test
+    void block_mode_rejectsUnknownBinary() {
+        WebBundlerConfig cfg = WebBundlerConfig.builder()
+                .commandSafetyMode(CommandSafetyMode.BLOCK)
+                .safeCommandRegistry(List.of("npm"))
+                .build();
+        CommandSafetyPolicy policy = new CommandSafetyPolicy(cfg);
+        assertThrows(IllegalStateException.class, () -> policy.check(List.of("sh", "-c", "echo nope")));
+    }
+
+    @Test
+    void allow_mode_permitsUnknownBinary() {
+        WebBundlerConfig cfg = WebBundlerConfig.builder()
+                .commandSafetyMode(CommandSafetyMode.ALLOW)
+                .safeCommandRegistry(List.of("npm"))
+                .build();
+        CommandSafetyPolicy policy = new CommandSafetyPolicy(cfg);
+        assertDoesNotThrow(() -> policy.check(List.of("custom", "run")));
+    }
+}
diff --git a/flash-extensions/flash-web-bundler/src/test/java/dev/relism/ext/webbundler/InstallCacheTest.java b/flash-extensions/flash-web-bundler/src/test/java/dev/relism/ext/webbundler/InstallCacheTest.java
new file mode 100644
index 0000000..5c8885a
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/test/java/dev/relism/ext/webbundler/InstallCacheTest.java
@@ -0,0 +1,29 @@
+package dev.relism.ext.webbundler;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class InstallCacheTest {
+    @TempDir
+    Path tempDir;
+
+    @Test
+    void lockHashChanges_areDetected() throws Exception {
+        Path lockfile = tempDir.resolve("package-lock.json");
+        Files.writeString(lockfile, "{\"a\":1}");
+
+        InstallCache cache = new InstallCache(tempDir);
+        assertTrue(cache.lockChanged(lockfile));
+        cache.writeLockHash(lockfile);
+        assertFalse(cache.lockChanged(lockfile));
+
+        Files.writeString(lockfile, "{\"a\":2}");
+        assertTrue(cache.lockChanged(lockfile));
+    }
+}
diff --git a/flash-extensions/flash-web-bundler/src/test/java/dev/relism/ext/webbundler/ModeResolverTest.java b/flash-extensions/flash-web-bundler/src/test/java/dev/relism/ext/webbundler/ModeResolverTest.java
new file mode 100644
index 0000000..29bf54a
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/test/java/dev/relism/ext/webbundler/ModeResolverTest.java
@@ -0,0 +1,17 @@
+package dev.relism.ext.webbundler;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+class ModeResolverTest {
+    private final ModeResolver resolver = new ModeResolver();
+
+    @Test
+    void prod_mode_isAlwaysProd() {
+        WebBundlerConfig cfg = WebBundlerConfig.builder()
+                .runtimeMode(RuntimeMode.PROD)
+                .build();
+        assertEquals(RuntimeEnvironment.PROD, resolver.resolve(cfg));
+    }
+}
diff --git a/flash-extensions/flash-web-bundler/src/test/java/dev/relism/ext/webbundler/PackageManagerAdapterTest.java b/flash-extensions/flash-web-bundler/src/test/java/dev/relism/ext/webbundler/PackageManagerAdapterTest.java
new file mode 100644
index 0000000..236770b
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/test/java/dev/relism/ext/webbundler/PackageManagerAdapterTest.java
@@ -0,0 +1,18 @@
+package dev.relism.ext.webbundler;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class PackageManagerAdapterTest {
+    @Test
+    void pnpm_hasFrozenInstallCommand() {
+        WebBundlerConfig cfg = WebBundlerConfig.builder()
+                .packageManager(PackageManager.PNPM)
+                .build();
+        PackageManagerAdapter adapter = new PackageManagerAdapter(cfg);
+        assertTrue(adapter.installCommand().get(0).startsWith("pnpm"));
+        assertEquals("--frozen-lockfile", adapter.installCommand().get(2));
+    }
+}
diff --git a/flash-extensions/flash-web-bundler/src/test/java/dev/relism/ext/webbundler/WebBundlerConfigTest.java b/flash-extensions/flash-web-bundler/src/test/java/dev/relism/ext/webbundler/WebBundlerConfigTest.java
new file mode 100644
index 0000000..4f2776c
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/test/java/dev/relism/ext/webbundler/WebBundlerConfigTest.java
@@ -0,0 +1,58 @@
+package dev.relism.ext.webbundler;
+
+import org.junit.jupiter.api.Test;
+
+import java.nio.file.Path;
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+class WebBundlerConfigTest {
+    @Test
+    void defaults_areSane() {
+        WebBundlerConfig cfg = WebBundlerConfig.builder().build();
+        assertEquals(RuntimeMode.AUTODETECT, cfg.runtimeMode());
+        assertEquals(OperationMode.ORCHESTRATE_ONLY, cfg.operationMode());
+        assertEquals(InstallPolicy.AUTO_IF_LOCK_HASH_CHANGED, cfg.installPolicy());
+        assertEquals(LoggingMode.MERGED, cfg.loggingMode());
+        assertEquals(CommandSafetyMode.WARN, cfg.commandSafetyMode());
+    }
+
+    @Test
+    void packageManager_setsLockfileInWatchList() {
+        WebBundlerConfig cfg = WebBundlerConfig.builder()
+                .packageManager(PackageManager.PNPM)
+                .build();
+        assertTrue(cfg.watchList().contains("pnpm-lock.yaml"));
+    }
+
+    @Test
+    void basePath_isNormalized() {
+        WebBundlerConfig cfg = WebBundlerConfig.builder().basePath("app/").build();
+        assertEquals("/app", cfg.basePath());
+    }
+
+    @Test
+    void invalidPort_throws() {
+        assertThrows(IllegalArgumentException.class, () ->
+                WebBundlerConfig.builder().devPort(0).build());
+    }
+
+    @Test
+    void assetsFromFilesystem_setsFilesystemSource() {
+        WebBundlerConfig cfg = WebBundlerConfig.builder()
+                .webRoot(Path.of("frontend"))
+                .assetsFromFilesystem(Path.of("build"))
+                .watchList(List.of("package.json"))
+                .build();
+        assertTrue(cfg.assetsSource() instanceof FilesystemAssetsSource);
+    }
+
+    @Test
+    void assetsFromClasspath_setsClasspathSource() {
+        WebBundlerConfig cfg = WebBundlerConfig.builder()
+                .assetsFromClasspath("web/dist")
+                .build();
+        assertTrue(cfg.assetsSource() instanceof ClasspathAssetsSource);
+    }
+}
diff --git a/flash-extensions/flash-web-bundler/src/test/java/dev/relism/ext/webbundler/WebBundlerExtensionDevGuardTest.java b/flash-extensions/flash-web-bundler/src/test/java/dev/relism/ext/webbundler/WebBundlerExtensionDevGuardTest.java
new file mode 100644
index 0000000..a9a3f22
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/test/java/dev/relism/ext/webbundler/WebBundlerExtensionDevGuardTest.java
@@ -0,0 +1,16 @@
+package dev.relism.ext.webbundler;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+class WebBundlerExtensionDevGuardTest {
+    @Test
+    void classpathSourceInDev_isRejected() {
+        WebBundlerConfig cfg = WebBundlerConfig.builder()
+                .assetsFromClasspath("web/dist")
+                .build();
+
+        assertThrows(IllegalStateException.class, () -> WebBundlerExtension.validateDevAssetsSource(cfg));
+    }
+}
diff --git a/flash-extensions/flash-web-bundler/src/test/java/dev/relism/ext/webbundler/WebBundlerExtensionIntegrationTest.java b/flash-extensions/flash-web-bundler/src/test/java/dev/relism/ext/webbundler/WebBundlerExtensionIntegrationTest.java
new file mode 100644
index 0000000..d9465ce
--- /dev/null
+++ b/flash-extensions/flash-web-bundler/src/test/java/dev/relism/ext/webbundler/WebBundlerExtensionIntegrationTest.java
@@ -0,0 +1,80 @@
+package dev.relism.ext.webbundler;
+
+import dev.relism.extension.FlashApp;
+import dev.relism.extension.FlashConfiguration;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+import java.net.ServerSocket;
+import java.net.URI;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class WebBundlerExtensionIntegrationTest {
+    @TempDir
+    Path tempDir;
+
+    private FlashApp app;
+
+    @AfterEach
+    void tearDown() {
+        if (app != null) app.stop();
+    }
+
+    @Test
+    void prodMode_servesAssetsAndFallback_withoutBreakingBackendRoutes() throws Exception {
+        Path webRoot = tempDir.resolve("web");
+        Path dist = webRoot.resolve("dist");
+        Files.createDirectories(dist);
+        Files.writeString(dist.resolve("index.html"), "<html>spa</html>");
+        Files.writeString(dist.resolve("app.js"), "console.log('ok');");
+
+        int port;
+        try (ServerSocket s = new ServerSocket(0)) {
+            port = s.getLocalPort();
+        }
+
+        WebBundlerConfig config = WebBundlerConfig.builder()
+                .runtimeMode(RuntimeMode.PROD)
+                .operationMode(OperationMode.MANAGED)
+                .webRoot(webRoot)
+                .assetsFromFilesystem(Path.of("dist"))
+                .basePath("/app")
+                .build();
+
+        app = FlashApp.create(FlashConfiguration.builder().port(port).host("127.0.0.1").build());
+        app.install(new WebBundlerExtension(config));
+        app.get("/api/ping", (req, res) -> "pong");
+        app.start();
+
+        HttpClient client = HttpClient.newHttpClient();
+        HttpResponse<String> backend = client.send(
+                HttpRequest.newBuilder(URI.create("http://127.0.0.1:" + port + "/api/ping")).GET().build(),
+                HttpResponse.BodyHandlers.ofString()
+        );
+        assertEquals(200, backend.statusCode());
+        assertEquals("pong", backend.body());
+
+        HttpResponse<String> asset = client.send(
+                HttpRequest.newBuilder(URI.create("http://127.0.0.1:" + port + "/app/app.js")).GET().build(),
+                HttpResponse.BodyHandlers.ofString()
+        );
+        assertEquals(200, asset.statusCode());
+        assertTrue(asset.body().contains("console.log"));
+
+        HttpResponse<String> fallback = client.send(
+                HttpRequest.newBuilder(URI.create("http://127.0.0.1:" + port + "/app/some/client/route")).GET().build(),
+                HttpResponse.BodyHandlers.ofString()
+        );
+        assertEquals(200, fallback.statusCode());
+        assertTrue(fallback.body().contains("spa"));
+    }
+
+}
diff --git a/flash-extensions/pom.xml b/flash-extensions/pom.xml
index 018fb52..0a523f5 100644
--- a/flash-extensions/pom.xml
+++ b/flash-extensions/pom.xml
@@ -20,6 +20,7 @@
         <module>flash-ext-routeviewer</module>
         <module>flash-ext-view</module>
         <module>flash-ext-limiter</module>
+        <module>flash-web-bundler</module>
     </modules>
 
     <dependencyManagement>
@@ -49,6 +50,11 @@
                 <artifactId>json-smart</artifactId>
                 <version>2.5.1</version>
             </dependency>
+            <dependency>
+                <groupId>dev.relism</groupId>
+                <artifactId>flash-web-bundler</artifactId>
+                <version>${project.version}</version>
+            </dependency>
         </dependencies>
     </dependencyManagement>
 
diff --git a/flash/pom.xml b/flash/pom.xml
index 58faf47..a752f67 100644
--- a/flash/pom.xml
+++ b/flash/pom.xml
@@ -29,6 +29,7 @@
         <dependency>
             <groupId>org.slf4j</groupId>
             <artifactId>slf4j-simple</artifactId>
+            <optional>true</optional>
         </dependency>
         <dependency>
             <groupId>org.junit.jupiter</groupId>
diff --git a/flash/src/main/java/dev/relism/ChunkedInputStream.java b/flash/src/main/java/dev/relism/ChunkedInputStream.java
index 1bf459c..4d5b4c4 100644
--- a/flash/src/main/java/dev/relism/ChunkedInputStream.java
+++ b/flash/src/main/java/dev/relism/ChunkedInputStream.java
@@ -49,17 +49,16 @@ final class ChunkedInputStream extends InputStream {
     }
 
     private int readChunkSize() throws IOException {
-        int size = 0, b;
+        long size = 0;
+        int  b;
         while ((b = src.read()) != -1) {
-            if      (b >= '0' && b <= '9') size = size * 16 + (b - '0');
-            else if (b >= 'a' && b <= 'f') size = size * 16 + (b - 'a' + 10);
-            else if (b >= 'A' && b <= 'F') size = size * 16 + (b - 'A' + 10);
-            else { // ';' (extensions) or '\r' — skip to end of line
-                while ((b = src.read()) != -1 && b != '\n');
-                break;
-            }
+            if      (b >= '0' && b <= '9') size = (size << 4) | (b - '0');
+            else if (b >= 'a' && b <= 'f') size = (size << 4) | (b - 'a' + 10);
+            else if (b >= 'A' && b <= 'F') size = (size << 4) | (b - 'A' + 10);
+            else { while ((b = src.read()) != -1 && b != '\n'); break; } // ext or \r\n
+            if (size > Integer.MAX_VALUE) throw new IOException("Chunk size exceeds 2 GB limit");
         }
-        return size;
+        return (int) size;
     }
 
     // Reads and discards trailer headers until the empty line that terminates the chunked body.
diff --git a/flash/src/main/java/dev/relism/Flash.java b/flash/src/main/java/dev/relism/Flash.java
index 84832bf..c32c400 100644
--- a/flash/src/main/java/dev/relism/Flash.java
+++ b/flash/src/main/java/dev/relism/Flash.java
@@ -1,8 +1,38 @@
 package dev.relism;
 
-import lombok.NoArgsConstructor;
-
-@NoArgsConstructor
+/**
+ * Global Flash constants and runtime environment flags.
+ *
+ * <h3>Dev mode</h3>
+ * Set via JVM property {@code -Dflash.env=dev} or environment variable {@code FLASH_ENV=dev}.
+ * Checked once at class load — zero runtime overhead.
+ *
+ * <p>Dev mode enables:
+ * <ul>
+ *   <li>HTML error pages with full stack traces (default: JSON generic responses in prod)</li>
+ *   <li>Template cache disabled in {@code flash-ext-view}</li>
+ * </ul>
+ *
+ * <p>Extensions can read {@link #DEV} to branch behavior without re-implementing the detection:
+ * <pre>{@code
+ * if (Flash.DEV) log.debug("Verbose OIDC debug output enabled");
+ * }</pre>
+ */
 public final class Flash {
+
+    private Flash() {}
+
     public static final String VERSION = "5.0.0-dev";
+
+    /**
+     * {@code true} when running in dev mode.
+     * Set via {@code -Dflash.env=dev} (JVM property) or {@code FLASH_ENV=dev} (env var).
+     * JVM property takes precedence.
+     */
+    public static final boolean DEV;
+
+    static {
+        String prop = System.getProperty("flash.env");
+        DEV = "dev".equalsIgnoreCase(prop != null ? prop : System.getenv("FLASH_ENV"));
+    }
 }
diff --git a/flash/src/main/java/dev/relism/HttpServer.java b/flash/src/main/java/dev/relism/HttpServer.java
index 30709b8..34244eb 100644
--- a/flash/src/main/java/dev/relism/HttpServer.java
+++ b/flash/src/main/java/dev/relism/HttpServer.java
@@ -19,7 +19,9 @@ import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.ExecutorService;
 import java.util.concurrent.Executors;
+import java.util.concurrent.RejectedExecutionException;
 import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicReference;
 
 /**
  * Pure I/O transport layer. Owns the {@link ServerSocket}, the virtual-thread
@@ -38,7 +40,7 @@ class HttpServer implements ServerHandle {
     private final ExecutorService    executorService = Executors.newVirtualThreadPerTaskExecutor();
     private final Set<Socket>        activeSockets   = ConcurrentHashMap.newKeySet();
     private volatile boolean stopped = false;
-    private final CompletableFuture<Void> readyFuture = new CompletableFuture<>();
+    private final AtomicReference<Thread> acceptThread = new AtomicReference<>();
 
     private static final byte[] HTTP_1_1             = "HTTP/1.1 ".getBytes(StandardCharsets.UTF_8);
     private static final byte[] CRLF                 = "\r\n".getBytes(StandardCharsets.UTF_8);
@@ -50,11 +52,9 @@ class HttpServer implements ServerHandle {
     private static final byte[] FINAL_CHUNK          = "0\r\n\r\n".getBytes(StandardCharsets.UTF_8);
     private static final byte[] UNKNOWN_STATUS_SUFFIX = " Unknown".getBytes(StandardCharsets.UTF_8);
 
-    private static final byte[][] DIGITS = new byte[10][1];
-    static {
-        for (int i = 0; i < 10; i++)
-            DIGITS[i] = String.valueOf(i).getBytes(StandardCharsets.UTF_8);
-    }
+    // Per-thread scratch buffers — allocated once per VT, reused for every request.
+    private static final ThreadLocal<byte[]> LONG_BUF  = ThreadLocal.withInitial(() -> new byte[20]);
+    private static final ThreadLocal<byte[]> CHUNK_BUF = ThreadLocal.withInitial(() -> new byte[8192]);
 
     HttpServer(FlashConfiguration configuration, AbstractRouter router) throws IOException {
         this.configuration = configuration;
@@ -63,88 +63,95 @@ class HttpServer implements ServerHandle {
     }
 
     @Override
-    public CompletableFuture<Void> start() {
-        Thread.ofPlatform().name("flash-accept-loop").daemon(false).start(this::run);
-        return readyFuture;
+    public void start() {
+        acceptThread.set(Thread.ofPlatform().name("flash-accept-loop").daemon(false).start(this::run));
+    }
+
+    @Override
+    public void startAndBlock() {
+        start();
+        try { acceptThread.get().join(); }
+        catch (InterruptedException e) { Thread.currentThread().interrupt(); }
     }
 
     private void run() {
-        try (executorService) {
-            readyFuture.complete(null);
-            while (!stopped) {
-                Socket clientSocket = serverSocket.accept();
-                process(clientSocket);
-            }
-        } catch (IOException e) {
-            if (!stopped) {
-                readyFuture.completeExceptionally(e);
-                log.error("Accept loop error", e);
+        while (!stopped) {
+            try {
+                process(serverSocket.accept());
+            } catch (IOException e) {
+                if (!stopped) log.error("Accept loop error", e);
             }
         }
     }
 
     @Override
     public CompletableFuture<Void> stop() {
-        stopped = true;
-        try { serverSocket.close(); } catch (IOException e) { log.error("Error closing server socket", e); }
-        activeSockets.forEach(s -> { try { s.close(); } catch (IOException ignored) {} });
-        executorService.shutdown();
-        try {
-            if (!executorService.awaitTermination(30, TimeUnit.SECONDS))
+        return CompletableFuture.runAsync(() -> {
+            stopped = true;
+            try { serverSocket.close(); } catch (IOException e) { log.error("Error closing server socket", e); }
+            activeSockets.forEach(s -> { try { s.close(); } catch (IOException ignored) {} });
+            executorService.shutdown();
+            try {
+                if (!executorService.awaitTermination(30, TimeUnit.SECONDS))
+                    executorService.shutdownNow();
+            } catch (InterruptedException e) {
                 executorService.shutdownNow();
-        } catch (InterruptedException e) {
-            executorService.shutdownNow();
-            Thread.currentThread().interrupt();
-        }
-        return CompletableFuture.completedFuture(null);
+                Thread.currentThread().interrupt();
+            }
+        });
     }
 
     // ── Hot-path ─────────────────────────────────────────────────────────────
 
     private void process(Socket socket) {
-        activeSockets.add(socket);
-        executorService.submit(() -> {
-            try (socket;
-                    InputStream in = socket.getInputStream();
-                    OutputStream out = new BufferedOutputStream(socket.getOutputStream())) {
-                RequestParser parser = new RequestParser(
-                        configuration.getMaxHeaderBufferSize(),
-                        (InetSocketAddress) socket.getRemoteSocketAddress());
-                while (!stopped) {
-                    Request request = parser.parse(in);
-                    if (request == null) break;
+        try {
+            executorService.submit(() -> {
+                activeSockets.add(socket);
+                try (socket;
+                        InputStream  in  = socket.getInputStream();
+                        OutputStream out = new BufferedOutputStream(socket.getOutputStream())) {
+                    RequestParser parser = new RequestParser(
+                            configuration.getMaxHeaderBufferSize(),
+                            (InetSocketAddress) socket.getRemoteSocketAddress());
+                    while (!stopped) {
+                        Request request = parser.parse(in);
+                        if (request == null) break;
 
-                    boolean keepAlive = isKeepAlive(request);
-                    Response response = new Response(200, ContentType.TEXT_PLAIN);
+                        boolean  keepAlive = isKeepAlive(request);
+                        Response response  = new Response(200, ContentType.TEXT_PLAIN);
 
-                    RequestHandler handler = router.route(request);
-                    if (handler == null) handler = router.getNotFoundHandler();
+                        RequestHandler handler = router.route(request);
+                        if (handler == null) handler = router.getNotFoundHandler();
 
-                    try {
-                        Object result = handler.handle(request, response);
-                        if (result instanceof Response r) response = r;
-                        else if (result != null) response.setBody(result);
-                    } catch (Exception ex) {
-                        Object result = router.getExceptionHandler().handle(ex, request, response);
-                        if (result instanceof Response r) response = r;
-                        else if (result != null) response.setBody(result);
+                        try {
+                            Object result = handler.handle(request, response);
+                            if (result instanceof Response r) response = r;
+                            else if (result != null) response.setBody(result);
+                        } catch (Exception ex) {
+                            Object result = router.getExceptionHandler().handle(ex, request, response);
+                            if (result instanceof Response r) response = r;
+                            else if (result != null) response.setBody(result);
+                        }
+
+                        writeResponse(out, response, keepAlive);
+                        request.drain();
+                        if (!keepAlive) break;
                     }
-
-                    writeResponse(out, response, keepAlive);
-                    request.drain();
-                    if (!keepAlive) break;
+                } catch (IOException e) {
+                    if (!stopped) {
+                        if (e instanceof java.net.SocketException)
+                            log.debug("Connection closed: {}", e.getMessage());
+                        else
+                            log.error("I/O error handling request", e);
+                    }
+                } finally {
+                    activeSockets.remove(socket);
                 }
-            } catch (IOException e) {
-                if (!stopped) {
-                    if (e instanceof java.net.SocketException)
-                        log.debug("Connection closed: {}", e.getMessage());
-                    else
-                        log.error("I/O error handling request", e);
-                }
-            } finally {
-                activeSockets.remove(socket);
-            }
-        });
+            });
+        } catch (RejectedExecutionException ignored) {
+            // Executor already shut down — close the socket so the client isn't left hanging.
+            try { socket.close(); } catch (IOException e) { log.debug("Error closing socket on shutdown", e); }
+        }
     }
 
     private static boolean isKeepAlive(Request request) {
@@ -202,15 +209,18 @@ class HttpServer implements ServerHandle {
     }
 
     private static void writeLong(OutputStream out, long value) throws IOException {
-        if (value == 0) { out.write(DIGITS[0]); return; }
-        if (value < 0)  { out.write('-'); value = -value; }
-        long divisor = 1;
-        while (value / divisor >= 10) divisor *= 10;
-        while (divisor > 0) { out.write(DIGITS[(int) ((value / divisor) % 10)]); divisor /= 10; }
+        if (value == 0) { out.write('0'); return; }
+        byte[] buf = LONG_BUF.get();
+        int pos = buf.length;
+        boolean neg = value < 0;
+        if (neg) value = -value;
+        do { buf[--pos] = (byte) ('0' + value % 10); value /= 10; } while (value > 0);
+        if (neg) buf[--pos] = '-';
+        out.write(buf, pos, buf.length - pos);
     }
 
     private static void writeChunked(OutputStream out, InputStream stream) throws IOException {
-        byte[] buf = new byte[8192];
+        byte[] buf = CHUNK_BUF.get();
         int n;
         while ((n = stream.read(buf)) > 0) {
             writeHex(out, n);
diff --git a/flash/src/main/java/dev/relism/ServerHandle.java b/flash/src/main/java/dev/relism/ServerHandle.java
index fa72622..6a24e1a 100644
--- a/flash/src/main/java/dev/relism/ServerHandle.java
+++ b/flash/src/main/java/dev/relism/ServerHandle.java
@@ -13,7 +13,16 @@ import java.util.concurrent.CompletableFuture;
  */
 public interface ServerHandle {
 
-    CompletableFuture<Void> start();
+    /** Starts the accept loop on a background platform thread. Returns immediately. */
+    void start();
+
+    /**
+     * Starts the accept loop and blocks the calling thread until the server is stopped.
+     * Suitable for use in {@code main()} when no other work is needed after startup.
+     */
+    void startAndBlock();
+
+    /** Gracefully stops the server, draining active connections. */
     CompletableFuture<Void> stop();
 
     static ServerHandle create(FlashConfiguration config, AbstractRouter router) throws IOException {
diff --git a/flash/src/main/java/dev/relism/extension/AnnotationProcessor.java b/flash/src/main/java/dev/relism/extension/AnnotationProcessor.java
index 7f0c81d..4946222 100644
--- a/flash/src/main/java/dev/relism/extension/AnnotationProcessor.java
+++ b/flash/src/main/java/dev/relism/extension/AnnotationProcessor.java
@@ -9,9 +9,9 @@ import java.util.List;
  * Inspects a handler class at registration time and returns zero or more
  * {@link Middleware middlewares} to inject automatically.
  *
- * <p>Processors are called once per {@link FlashApp#register} call, before
+ * <p>Processors are called once per register call, before
  * the handler is compiled into the router. Returning an empty list is always
- * valid — processors may also use the call purely for side effects
+ * valid: processors may also use the call purely for side effects
  * (e.g. collecting OpenAPI metadata).
  *
  * <p>Register processors via {@link FlashContext#addAnnotationProcessor}.
diff --git a/flash/src/main/java/dev/relism/extension/ExtensionPhase.java b/flash/src/main/java/dev/relism/extension/ExtensionPhase.java
new file mode 100644
index 0000000..2ccdcf1
--- /dev/null
+++ b/flash/src/main/java/dev/relism/extension/ExtensionPhase.java
@@ -0,0 +1,32 @@
+package dev.relism.extension;
+
+/**
+ * Semantic execution phases for {@link FlashExtension#priority()}.
+ *
+ * <p>Phase determines the order in which annotation-processor middlewares are injected into
+ * the chain. Lower value = runs earlier (outermost wrapper = first at request time).
+ *
+ * <pre>
+ * Request ──► EARLY middlewares ──► DEFAULT middlewares ──► LATE middlewares ──► handler
+ * </pre>
+ *
+ * <p>Within the same phase, extensions execute in install order (sort is stable).
+ * Raw integers are valid for fine-grained ordering within a phase
+ * (e.g. {@code ExtensionPhase.EARLY.value + 10}).
+ */
+public enum ExtensionPhase {
+
+    /** Security guards, rate limiting — must short-circuit before expensive processing. */
+    EARLY(100),
+
+    /** Normal application extensions. Default when {@link FlashExtension#priority()} is not overridden. */
+    DEFAULT(500),
+
+    /** Observability, logging, diagnostics — must observe after all business logic. */
+    LATE(900);
+
+    /** The integer priority value used for sorting. */
+    public final int value;
+
+    ExtensionPhase(int value) { this.value = value; }
+}
diff --git a/flash/src/main/java/dev/relism/extension/FlashApp.java b/flash/src/main/java/dev/relism/extension/FlashApp.java
index 9276c66..ffc5534 100644
--- a/flash/src/main/java/dev/relism/extension/FlashApp.java
+++ b/flash/src/main/java/dev/relism/extension/FlashApp.java
@@ -1,5 +1,6 @@
 package dev.relism.extension;
 
+import dev.relism.Flash;
 import dev.relism.ServerHandle;
 import dev.relism.exceptions.InitializationException;
 import dev.relism.http.HttpMethod;
@@ -7,155 +8,80 @@ import dev.relism.models.RequestHandler;
 import dev.relism.models.SimpleHandler;
 import dev.relism.routing.AbstractRouter;
 import dev.relism.routing.Middleware;
-import dev.relism.routing.Route;
-import dev.relism.routing.RouteHandle;
 import dev.relism.routing.routers.fastpathrouter.FastPathRouterImpl;
+import lombok.extern.slf4j.Slf4j;
 
 import java.io.IOException;
 import java.util.ArrayList;
-import java.util.Arrays;
+import java.util.Comparator;
 import java.util.List;
 import java.util.concurrent.CompletableFuture;
 import java.util.function.Consumer;
 
 /**
  * Single entry point for Flash. Owns one flat {@link FastPathRouterImpl} —
- * all routes (app-level and scoped) compile into a single FSM at {@link #start()}.
- *
- * <h3>Deferred routing</h3>
- * Routes accumulate during the builder phase. At {@code start()}:
- * <ol>
- *   <li>Global middlewares are prepended to every route</li>
- *   <li>Annotation processors run for class-based handlers</li>
- *   <li>Handlers are bound to the {@link FlashContext}</li>
- *   <li>All routes compile into one FSM — zero prefix scanning at runtime</li>
- * </ol>
+ * all routes (app-level and scoped) compile into a single FSM at startup.
  *
  * <pre>{@code
  * FlashApp.create(8080)
  *     .install(new JacksonExtension())
  *     .use(cors)
- *     .get("/ping", (req, res) -> "pong")
+ *     .get("/ping",    (req, res) -> "pong")
+ *     .get("/secured", (req, res) -> user(), oidc.protect())
  *     .scan("dev.example.handlers")
  *     .mount("/api", scope -> scope.get("/health", (req, res) -> "ok"))
- *     .start();
+ *     .startAndBlock();   // blocks main thread
  * }</pre>
+ *
+ * <h3>Startup sequence (both {@link #start()} and {@link #startAndBlock()})</h3>
+ * <ol>
+ *   <li>Extensions sorted by {@link FlashExtension#priority()} — lower first.</li>
+ *   <li>All {@link FlashExtension#provide} — register services, processors, listeners.</li>
+ *   <li>{@link FlashContext#resolveAll()} — topo-sort, cycle detection.</li>
+ *   <li>All {@link FlashExtension#routes} — routes registered, services available.</li>
+ *   <li>Compile all routes into one flat FSM — zero prefix scanning at runtime.</li>
+ *   <li>Accept loop started.</li>
+ * </ol>
+ *
+ * <h3>Default error handlers</h3>
+ * Dev mode ({@code -Dflash.env=dev}): rich HTML with stack traces.
+ * Prod mode (default): generic JSON — no internal details leaked.
+ * Override via {@link #onException} / {@link #onNotFound}.
  */
-public final class FlashApp implements FlashRegistrar {
+@Slf4j
+public final class FlashApp extends FlashRegistrar<FlashApp> {
 
-    private final AbstractRouter          router = new FastPathRouterImpl();
-    private final ServerHandle            server;
-    private final FlashContext         ctx    = new FlashContext();
-    private final List<Middleware>         globalMiddlewares = new ArrayList<>();
-    private final List<RouteDefinition>   deferredRoutes    = new ArrayList<>();
-
-    private RouteHandle<?> pending;
+    private final AbstractRouter        router     = new FastPathRouterImpl();
+    private final ServerHandle          server;
+    private final FlashContext          ctx        = new FlashContext();
+    private final List<FlashExtension>  extensions        = new ArrayList<>();
+    private final List<Middleware>      globalMiddlewares = new ArrayList<>();
+    private final List<RouteDefinition> deferredRoutes    = new ArrayList<>();
+    private int port;
 
     private FlashApp(FlashConfiguration config) {
         try {
             this.server = ServerHandle.create(config, router);
-        } catch (IOException e) {
-            throw new InitializationException("Failed to bind on port " + config.getPort(), e);
+            this.port   = config.getPort();
         }
+        catch (IOException e) { throw new InitializationException("Failed to bind on port " + config.getPort(), e); }
     }
 
     // ── Factories ─────────────────────────────────────────────────────────────
 
-    public static FlashApp create(int port) {
-        return create(FlashConfiguration.builder().port(port).build());
-    }
+    public static FlashApp create(int port)               { return create(FlashConfiguration.builder().port(port).build()); }
+    public static FlashApp create(FlashConfiguration cfg) { return new FlashApp(cfg); }
 
-    public static FlashApp create(FlashConfiguration config) {
-        return new FlashApp(config);
-    }
-
-    // ── Pending flush ─────────────────────────────────────────────────────────
-
-    private void flushPending() {
-        if (pending != null) { pending.ensureRegistered(); pending = null; }
-    }
-
-    private <P> RouteHandle<P> track(RouteHandle<P> handle) {
-        flushPending();
-        pending = handle;
-        return handle;
-    }
-
-    // ── Extension installation ────────────────────────────────────────────────
-
-    @Override
-    public FlashApp install(FlashExtension ext) {
-        flushPending();
-        ext.install(this, ctx);
-        return this;
-    }
-
-    // ── Global middleware ─────────────────────────────────────────────────────
+    // ── Namespace mounting ────────────────────────────────────────────────────
 
     /**
-     * Registers global middlewares applied to <em>every</em> route — including
-     * routes registered before this call and routes inside mounted scopes.
-     * Order-independent: resolved at {@link #start()}.
-     */
-    public FlashApp use(Middleware... middlewares) {
-        flushPending();
-        globalMiddlewares.addAll(Arrays.asList(middlewares));
-        return this;
-    }
-
-    // ── Route registration (deferred) ─────────────────────────────────────────
-
-    @Override public RouteHandle<FlashApp> get    (String path, SimpleHandler.FunctionalHandler h) { return lambda(HttpMethod.GET,     path, h); }
-    @Override public RouteHandle<FlashApp> post   (String path, SimpleHandler.FunctionalHandler h) { return lambda(HttpMethod.POST,    path, h); }
-    @Override public RouteHandle<FlashApp> put    (String path, SimpleHandler.FunctionalHandler h) { return lambda(HttpMethod.PUT,     path, h); }
-    @Override public RouteHandle<FlashApp> delete (String path, SimpleHandler.FunctionalHandler h) { return lambda(HttpMethod.DELETE,  path, h); }
-    @Override public RouteHandle<FlashApp> patch  (String path, SimpleHandler.FunctionalHandler h) { return lambda(HttpMethod.PATCH,   path, h); }
-    @Override public RouteHandle<FlashApp> options(String path, SimpleHandler.FunctionalHandler h) { return lambda(HttpMethod.OPTIONS, path, h); }
-    @Override public RouteHandle<FlashApp> head   (String path, SimpleHandler.FunctionalHandler h) { return lambda(HttpMethod.HEAD,    path, h); }
-    @Override public RouteHandle<FlashApp> trace  (String path, SimpleHandler.FunctionalHandler h) { return lambda(HttpMethod.TRACE,   path, h); }
-    @Override public RouteHandle<FlashApp> connect(String path, SimpleHandler.FunctionalHandler h) { return lambda(HttpMethod.CONNECT, path, h); }
-    @Override public RouteHandle<FlashApp> purge  (String path, SimpleHandler.FunctionalHandler h) { return lambda(HttpMethod.PURGE,   path, h); }
-
-    private static final Middleware[] NO_MW = new Middleware[0];
-
-    private RouteHandle<FlashApp> lambda(HttpMethod method, String path, SimpleHandler.FunctionalHandler h) {
-        return track(new RouteHandle<>(this, mw ->
-                deferredRoutes.add(new RouteDefinition(method, path, new SimpleHandler(h), NO_MW, mw, false, ctx, "/"))));
-    }
-
-    /**
-     * Registers a class-based handler annotated with {@link Route @Route}.
-     * App-level only — not part of {@link FlashRegistrar}.
-     */
-    public RouteHandle<FlashApp> register(RequestHandler handler) {
-        Route ann = handler.getClass().getAnnotation(Route.class);
-        if (ann == null)
-            throw new InitializationException(
-                    handler.getClass().getName() + " is missing @Route");
-        return track(new RouteHandle<>(this, mw ->
-                deferredRoutes.add(new RouteDefinition(ann.method(), ann.path(), handler, NO_MW, mw, true, ctx, "/"))));
-    }
-
-    @Override
-    public FlashApp scan(String packageName) {
-        flushPending();
-        PackageScanner.findHandlers(packageName).forEach(cls ->
-                register(instantiate(cls)).ensureRegistered());
-        return this;
-    }
-
-    // ── Namespace mounting (syntactic sugar — routes go into same flat router) ─
-
-    /**
-     * Mounts a scoped group of routes under {@code namespace}. The scope is a
-     * pure builder — it prepends the namespace to each path and collects
-     * {@link RouteDefinition}s that merge into this app's single flat router.
+     * Mounts a scoped group of routes under {@code namespace}. Routes accumulate in a
+     * {@link FlashScope} builder and merge into this app's single flat router at startup —
+     * pure syntactic sugar, no extra router involved.
      */
     public FlashApp mount(String namespace, Consumer<FlashScope> configure) {
-        flushPending();
         FlashScope scope = new FlashScope(namespace, ctx);
         configure.accept(scope);
-        scope.flush();
         deferredRoutes.addAll(scope.routes());
         return this;
     }
@@ -163,40 +89,87 @@ public final class FlashApp implements FlashRegistrar {
     // ── Error handlers ────────────────────────────────────────────────────────
 
     public FlashApp onException(AbstractRouter.ExceptionHandler handler) {
-        flushPending();
         router.onException(handler);
         return this;
     }
 
     public FlashApp onNotFound(SimpleHandler.FunctionalHandler handler) {
-        flushPending();
         router.onNotFound(handler);
         return this;
     }
 
-    @Override
-    public FlashContext ctx() { return ctx; }
+    @Override public FlashContext ctx() { return ctx; }
+
+    // ── Extensions ────────────────────────────────────────────────────────────
+
+    /**
+     * Registers an extension for two-phase installation at startup.
+     * Install order is irrelevant — all {@link FlashExtension#provide} calls complete
+     * before any {@link FlashExtension#routes} call begins.
+     * Extensions are sorted by {@link FlashExtension#priority()} before execution.
+     */
+    public FlashApp install(FlashExtension ext) {
+        extensions.add(ext);
+        return this;
+    }
 
     // ── Lifecycle ─────────────────────────────────────────────────────────────
 
     /**
-     * Compiles all deferred routes into the flat FSM router, then starts
-     * the HTTP transport. One pass, one router, zero prefix scanning.
+     * Boots the server and starts accepting connections. Returns immediately — the
+     * accept loop runs on a background platform thread.
+     *
+     * <p>Use {@link #startAndBlock()} in {@code main()} if you have no other work to do
+     * after startup.
+     *
+     * @return {@code this} for storing or chaining (e.g. {@code .start().ctx().require(...)})
      */
-    public CompletableFuture<Void> start() {
-        flushPending();
-        compile();
-        return server.start();
+    public FlashApp start() {
+        boot();
+        server.start();
+        if (Flash.DEV) log.info("[Flash] Started (dev mode): listening on port " + port);
+        return this;
+    }
+
+    /**
+     * Boots the server and blocks the calling thread until the server is stopped.
+     * Suitable for the end of {@code main()} — no need to keep the JVM alive manually.
+     */
+    public void startAndBlock() {
+        boot();
+        if (Flash.DEV) log.info("[Flash] Started (dev mode): listening on port " + port);
+        server.startAndBlock();
     }
 
     public CompletableFuture<Void> stop() { return server.stop(); }
 
+    // ── FlashRegistrar impl ───────────────────────────────────────────────────
+
+    @Override
+    protected void addRoute(HttpMethod method, String path, RequestHandler handler, List<Middleware> mw) {
+        deferredRoutes.add(new RouteDefinition(
+                method, path, handler, List.of(), mw,
+                !(handler instanceof SimpleHandler), ctx, "/"));
+    }
+
+    @Override
+    protected void addMiddleware(Middleware mw) { globalMiddlewares.add(mw); }
+
+    // ── Boot ─────────────────────────────────────────────────────────────────
+
+    private void boot() {
+        extensions.sort(Comparator.comparingInt(FlashExtension::priority));
+        extensions.forEach(e -> e.provide(ctx));
+        ctx.resolveAll();
+        extensions.forEach(e -> e.routes(this, ctx));
+        compile();
+    }
+
     // ── Compilation ──────────────────────────────────────────────────────────
 
-    /**
-     * Compiles all deferred routes. Middleware chain order:
-     * Global → Scope → Annotation (class-based only) → Explicit (.with).
-     */
+    private static final Middleware[] EMPTY_MW = new Middleware[0];
+
+    /** Middleware chain order per route: Global → Scope → Annotation → Explicit. */
     private void compile() {
         for (RouteDefinition def : deferredRoutes) {
             List<Middleware> injected;
@@ -208,52 +181,33 @@ public final class FlashApp implements FlashRegistrar {
             } else {
                 injected = List.of();
             }
-
-            Middleware[] all = concat(globalMiddlewares, def.scopeMiddlewares(),
-                    injected, def.explicitMiddlewares());
+            Middleware[] all = concat(globalMiddlewares, def.scopeMiddlewares(), injected, def.explicitMiddlewares());
             emitEvent(def, all);
             router.doRegister(def.method(), def.path(), def.handler(), all);
         }
     }
 
     @SuppressWarnings("unchecked")
-    private void emitEvent(RouteDefinition def, Middleware[] allMiddlewares) {
+    private void emitEvent(RouteDefinition def, Middleware[] chain) {
         List<RouteListener> listeners = def.ctx().routeListeners();
         if (listeners.isEmpty()) return;
-
-        List<Class<? extends Middleware>> chain = new ArrayList<>(allMiddlewares.length);
-        for (Middleware m : allMiddlewares)
-            chain.add((Class<? extends Middleware>) m.getClass());
-
+        List<Class<? extends Middleware>> mwClasses = new ArrayList<>(chain.length);
+        for (Middleware m : chain) mwClasses.add((Class<? extends Middleware>) m.getClass());
         Class<?> handlerClass = def.classBasedHandler() ? def.handler().getClass() : null;
-        RouteEvent event = new RouteEvent(def.method(), def.path(), def.namespace(),
-                "FlashApp", handlerClass, List.copyOf(chain));
+        RouteEvent event = new RouteEvent(def.method(), def.path(), def.namespace(), "FlashApp", handlerClass, List.copyOf(mwClasses));
         listeners.forEach(l -> l.onRoute(event));
     }
 
-    // ── Internals ─────────────────────────────────────────────────────────────
-
-    private static Middleware[] concat(List<Middleware> global, Middleware[] scope,
-                                       List<Middleware> injected, Middleware[] explicit) {
-        int total = global.size() + scope.length + injected.size() + explicit.length;
-        if (total == 0) return NO_MW;
-        if (total == explicit.length && scope.length == 0) return explicit;
+    private static Middleware[] concat(List<Middleware> global, List<Middleware> scope,
+                                       List<Middleware> injected, List<Middleware> explicit) {
+        int total = global.size() + scope.size() + injected.size() + explicit.size();
+        if (total == 0) return EMPTY_MW;
         Middleware[] all = new Middleware[total];
         int i = 0;
         for (Middleware m : global)   all[i++] = m;
         for (Middleware m : scope)    all[i++] = m;
         for (Middleware m : injected) all[i++] = m;
-        System.arraycopy(explicit, 0, all, i, explicit.length);
+        for (Middleware m : explicit) all[i++] = m;
         return all;
     }
-
-    private static RequestHandler instantiate(Class<?> cls) {
-        try {
-            return (RequestHandler) cls.getDeclaredConstructor().newInstance();
-        } catch (Exception e) {
-            throw new InitializationException(
-                    "Failed to instantiate " + cls.getName() +
-                    " — ensure it has a public no-arg constructor", e);
-        }
-    }
 }
diff --git a/flash/src/main/java/dev/relism/extension/FlashContext.java b/flash/src/main/java/dev/relism/extension/FlashContext.java
index 0be26fd..25ae4e3 100644
--- a/flash/src/main/java/dev/relism/extension/FlashContext.java
+++ b/flash/src/main/java/dev/relism/extension/FlashContext.java
@@ -1,84 +1,137 @@
 package dev.relism.extension;
 
 import java.util.*;
-import java.util.stream.Stream;
+import java.util.function.Supplier;
 
 /**
  * Central service registry and boot-time hook coordinator.
  *
  * <p>Every handler, extension, and scope shares one (or a child of one) {@code FlashContext}.
- * It provides three capabilities:
+ * Three capabilities:
  * <ol>
- *   <li><b>Service registry</b> — typed {@link #provide}/{@link #require}/{@link #find}.</li>
- *   <li><b>Annotation processors</b> — middleware injection from handler annotations.</li>
+ *   <li><b>Service registry</b> — {@link #provide}/{@link #supply}/{@link #require}/{@link #find}.</li>
+ *   <li><b>Annotation processors</b> — middleware injection from handler annotations at boot.</li>
  *   <li><b>Route listeners</b> — boot-time observation of the route graph.</li>
  * </ol>
  *
+ * <h3>Eager vs lazy registration</h3>
+ * <ul>
+ *   <li>{@link #provide(Class, Object)} — instance is already constructed, registered immediately.</li>
+ *   <li>{@link #supply(Class, Supplier)} — factory is registered; it runs once, at
+ *       {@link #resolveAll()} time (called by {@link FlashApp#start()}) after all
+ *       {@link FlashExtension#provide} phases complete. The factory may call
+ *       {@link #require} for its own dependencies — the runtime resolves in topological
+ *       order automatically and reports circular dependencies with the full cycle path.</li>
+ * </ul>
+ *
  * <p>A child context (via {@link #child()}) inherits parent services and processors.
  * Services provided on the child are scoped and invisible to the parent.
  */
 public class FlashContext {
 
     private final FlashContext parent;
-    private final Map<Class<?>, Object>     registry       = new LinkedHashMap<>();
-    private final List<AnnotationProcessor> processors     = new ArrayList<>();
-    private final List<RouteListener>       routeListeners = new ArrayList<>();
+    private final Map<Class<?>, Object>      registry  = new LinkedHashMap<>();
+    private final Map<Class<?>, Supplier<?>> pending   = new LinkedHashMap<>();
+    private final List<AnnotationProcessor>  processors     = new ArrayList<>();
+    private final List<RouteListener>        routeListeners = new ArrayList<>();
 
-    public FlashContext() {
-        this.parent = null;
-    }
+    // Lazy caches — nulled whenever the corresponding list is mutated.
+    private List<AnnotationProcessor> cachedProcessors;
+    private List<RouteListener>       cachedListeners;
 
-    private FlashContext(FlashContext parent) {
-        this.parent = parent;
-    }
+    // DFS stack — tracks in-progress resolutions to detect circular dependencies.
+    private final LinkedHashSet<Class<?>> resolutionStack = new LinkedHashSet<>();
+
+    public FlashContext() { this.parent = null; }
+    private FlashContext(FlashContext parent) { this.parent = parent; }
 
     /** Creates a child context that inherits this context's services and processors. */
-    public FlashContext child() {
-        return new FlashContext(this);
-    }
+    public FlashContext child() { return new FlashContext(this); }
 
     // ── Service registry ─────────────────────────────────────────────────────
 
-    /** Stores {@code instance} under {@code type} for retrieval via {@link #require} or {@link #find}. */
+    /** Registers an already-constructed {@code instance} under {@code type}. */
     public <T> void provide(Class<T> type, T instance) {
         registry.put(type, instance);
     }
 
     /**
-     * Retrieves the service registered under {@code type}.
-     * Checks own scope first, then the parent chain.
+     * Registers a lazy factory for {@code type}. The factory runs once at
+     * {@link #resolveAll()} time (or on the first {@link #require} call for this type)
+     * and may call {@link #require} for its own dependencies — topological order
+     * is resolved automatically.
      *
-     * @throws IllegalStateException if not found
+     * <pre>{@code
+     * ctx.supply(JwtValidator.class, () ->
+     *     new JwtValidator(ctx.require(OidcProviderMetadata.class).jwksUri()));
+     * }</pre>
      */
-    @SuppressWarnings("unchecked")
-    public <T> T require(Class<T> type) {
-        T val = (T) registry.get(type);
-        if (val == null && parent != null) val = parent.find(type).orElse(null);
-        if (val == null)
-            throw new IllegalStateException(
-                    "Service not found: " + type.getSimpleName() +
-                    " — provide it via FlashContext.provide() or install the required extension");
-        return val;
-    }
-
-    /** Returns the service under {@code type}, or empty if not provided in this scope or any parent. */
-    @SuppressWarnings("unchecked")
-    public <T> Optional<T> find(Class<T> type) {
-        T val = (T) registry.get(type);
-        if (val != null) return Optional.of(val);
-        return parent != null ? parent.find(type) : Optional.empty();
+    public <T> void supply(Class<T> type, Supplier<T> factory) {
+        pending.put(type, factory);
     }
 
     /**
-     * Returns the service registered under {@code type} as an {@link Optional},
-     * or {@link Optional#empty()} if not present in this scope or any parent.
+     * Returns the service for {@code type}. Checks own scope first, then parent chain.
+     * Lazy-registered types are resolved on first access. Circular dependencies throw
+     * {@link IllegalStateException} with the full cycle path.
      *
-     * <p>Semantically identical to {@link #find} — prefer this name for expressive call sites
-     * ({@code ctx.optional(ViewEngine.class).ifPresent(...)}). Respects the parent-first
-     * scope hierarchy: own registry is checked first, then the parent chain.
+     * @throws IllegalStateException if the service is not found anywhere in the context chain
      */
-    public <T> Optional<T> optional(Class<T> type) {
-        return find(type);
+    @SuppressWarnings("unchecked")
+    public <T> T require(Class<T> type) {
+        Object val = registry.get(type);
+        if (val != null) return (T) val;
+        if (pending.containsKey(type)) return resolve(type);
+        if (parent != null) return parent.require(type);
+        throw new IllegalStateException(
+                "Service not found: " + type.getSimpleName() +
+                " — register it via FlashContext.provide()/supply() or install the required extension");
+    }
+
+    /** Returns the service for {@code type}, or empty if not found in this scope or any parent. */
+    @SuppressWarnings("unchecked")
+    public <T> Optional<T> find(Class<T> type) {
+        Object val = registry.get(type);
+        if (val != null) return Optional.of((T) val);
+        if (pending.containsKey(type)) return Optional.of(resolve(type));
+        return parent != null ? parent.find(type) : Optional.empty();
+    }
+
+    /** Alias for {@link #find} — prefer when semantics are "this may or may not exist". */
+    public <T> Optional<T> optional(Class<T> type) { return find(type); }
+
+    /**
+     * Eagerly resolves all pending lazy suppliers in topological order.
+     * Called once by {@link FlashApp#start()} after all {@link FlashExtension#provide}
+     * phases complete. Any circular dependency is reported with the full cycle path.
+     */
+    void resolveAll() {
+        new ArrayList<>(pending.keySet()).forEach(this::resolve);
+    }
+
+    @SuppressWarnings("unchecked")
+    private <T> T resolve(Class<?> type) {
+        Object already = registry.get(type);
+        if (already != null) return (T) already;  // resolved during an earlier DFS branch
+
+        if (!resolutionStack.add(type)) {
+            // type is already on the current DFS path → circular dependency
+            List<Class<?>> cycle = new ArrayList<>(resolutionStack);
+            cycle.add(type);
+            StringBuilder msg = new StringBuilder("Circular dependency: ");
+            for (int i = 0; i < cycle.size(); i++) {
+                if (i > 0) msg.append(" → ");
+                msg.append(cycle.get(i).getSimpleName());
+            }
+            throw new IllegalStateException(msg.toString());
+        }
+
+        Supplier<?> factory = pending.get(type);
+        Object instance = factory.get();   // recursive require() calls happen here
+        registry.put(type, instance);
+        pending.remove(type);
+        resolutionStack.remove(type);
+        return (T) instance;
     }
 
     // ── Annotation processors ────────────────────────────────────────────────
@@ -86,14 +139,19 @@ public class FlashContext {
     /** Registers an {@link AnnotationProcessor}. Processors run once per class-based handler at boot. */
     public void addAnnotationProcessor(AnnotationProcessor processor) {
         processors.add(processor);
+        cachedProcessors = null;
     }
 
-    /** All processors visible from this context: parent-first, then own. */
+    /** All processors visible from this context: parent-first, then own. Cached after first call. */
     List<AnnotationProcessor> processors() {
-        if (parent == null) return Collections.unmodifiableList(processors);
-        List<AnnotationProcessor> parentProcessors = parent.processors();
-        if (processors.isEmpty()) return parentProcessors;
-        return Stream.concat(parentProcessors.stream(), processors.stream()).toList();
+        if (cachedProcessors != null) return cachedProcessors;
+        if (parent == null) return cachedProcessors = List.copyOf(processors);
+        List<AnnotationProcessor> p = parent.processors();
+        if (processors.isEmpty()) return cachedProcessors = p;
+        List<AnnotationProcessor> merged = new ArrayList<>(p.size() + processors.size());
+        merged.addAll(p);
+        merged.addAll(processors);
+        return cachedProcessors = List.copyOf(merged);
     }
 
     // ── Route listeners ──────────────────────────────────────────────────────
@@ -101,13 +159,18 @@ public class FlashContext {
     /** Registers a boot-time {@link RouteListener}. Zero overhead on the request hot-path. */
     public void addRouteListener(RouteListener listener) {
         routeListeners.add(listener);
+        cachedListeners = null;
     }
 
-    /** All route listeners visible from this context: parent-first, then own. */
+    /** All route listeners visible from this context: parent-first, then own. Cached after first call. */
     List<RouteListener> routeListeners() {
-        if (parent == null) return Collections.unmodifiableList(routeListeners);
-        List<RouteListener> parentListeners = parent.routeListeners();
-        if (routeListeners.isEmpty()) return parentListeners;
-        return Stream.concat(parentListeners.stream(), routeListeners.stream()).toList();
+        if (cachedListeners != null) return cachedListeners;
+        if (parent == null) return cachedListeners = List.copyOf(routeListeners);
+        List<RouteListener> p = parent.routeListeners();
+        if (routeListeners.isEmpty()) return cachedListeners = p;
+        List<RouteListener> merged = new ArrayList<>(p.size() + routeListeners.size());
+        merged.addAll(p);
+        merged.addAll(routeListeners);
+        return cachedListeners = List.copyOf(merged);
     }
 }
diff --git a/flash/src/main/java/dev/relism/extension/FlashExtension.java b/flash/src/main/java/dev/relism/extension/FlashExtension.java
index d2535ef..fd0580d 100644
--- a/flash/src/main/java/dev/relism/extension/FlashExtension.java
+++ b/flash/src/main/java/dev/relism/extension/FlashExtension.java
@@ -1,32 +1,70 @@
 package dev.relism.extension;
 
 /**
- * Contract for all Flash extensions. An extension receives a {@link FlashRegistrar}
- * (either a {@link FlashApp} or a {@link FlashScope}) so it can register routes and
- * expose shared services via {@link FlashContext}.
+ * Two-phase contract for all Flash extensions.
  *
- * <p>Extensions work identically whether installed at the top-level app or inside a
- * mounted scope:
+ * <p>Extension lifecycle inside {@link FlashApp#start()}:
+ * <ol>
+ *   <li>Extensions are sorted by {@link #priority()} — lower value runs first.</li>
+ *   <li><b>Provide phase</b> — {@link #provide(FlashContext)} is called for <em>all</em>
+ *       installed extensions. Use this phase to register services, annotation processors,
+ *       and route listeners. Never call {@link FlashContext#require} here.</li>
+ *   <li>Context resolution — {@link FlashContext#resolveAll()} performs topological
+ *       resolution of lazy suppliers. Circular or missing dependencies fail here with
+ *       a clear message before any request is served.</li>
+ *   <li><b>Routes phase</b> — {@link #routes(FlashRegistrar, FlashContext)} is called for
+ *       all extensions. All services are resolved; {@link FlashContext#require} is safe.</li>
+ * </ol>
  *
+ * <h3>Priority and middleware ordering</h3>
+ * {@link #priority()} controls the order annotation processors are registered, which
+ * determines the annotation-layer middleware chain position:
+ * <pre>
+ * Request ──► EARLY processors' mw ──► DEFAULT processors' mw ──► LATE processors' mw ──► handler
+ * </pre>
+ * Use {@link ExtensionPhase} constants for semantic ordering:
  * <pre>{@code
- * public class RateLimitExtension implements FlashExtension {
- *     public void install(FlashRegistrar app, FlashContext ctx) {
- *         RateLimiter limiter = new RateLimiter(100);
- *         ctx.provide(RateLimiter.class, limiter);
- *         app.get("/rate-info", (req, res) -> limiter.info());
+ * @Override public int priority() { return ExtensionPhase.EARLY.value; }
+ * }</pre>
+ *
+ * <h3>Example</h3>
+ * <pre>{@code
+ * public class MetricsExtension implements FlashExtension {
+ *
+ *     @Override public int priority() { return ExtensionPhase.LATE.value; }
+ *
+ *     @Override
+ *     public void provide(FlashContext ctx) {
+ *         ctx.provide(MetricsRegistry.class, new PromMetricsRegistry());
+ *     }
+ *
+ *     @Override
+ *     public void routes(FlashRegistrar<?> app, FlashContext ctx) {
+ *         app.get("/metrics", (req, res) -> ctx.require(MetricsRegistry.class).scrape());
  *     }
  * }
- *
- * // Top-level app
- * FlashApp.create(8080)
- *     .install(new JacksonExtension())
- *     .install(new OidcExtension(OidcConfig.fromEnv()));
- *
- * // Scoped
- * app.mount("/api", scope -> scope.install(new RateLimitExtension()));
  * }</pre>
  */
-@FunctionalInterface
 public interface FlashExtension {
-    void install(FlashRegistrar app, FlashContext ctx);
+
+    /**
+     * Phase 1 — register services and processors.
+     * Safe: {@link FlashContext#provide}, {@link FlashContext#supply},
+     * {@link FlashContext#addAnnotationProcessor}, {@link FlashContext#addRouteListener}.
+     * Unsafe: {@link FlashContext#require} (services not yet resolved).
+     */
+    default void provide(FlashContext ctx) {}
+
+    /**
+     * Phase 2 — register routes. All services are fully resolved.
+     * {@link FlashContext#require} is safe here.
+     */
+    default void routes(FlashRegistrar<?> app, FlashContext ctx) {}
+
+    /**
+     * Execution priority. Lower = earlier in the annotation middleware chain.
+     * Tie-breaking: same value → install order (sort is stable).
+     * Default: {@link ExtensionPhase#DEFAULT} (500).
+     */
+    default int priority() { return ExtensionPhase.DEFAULT.value; }
 }
diff --git a/flash/src/main/java/dev/relism/extension/FlashRegistrar.java b/flash/src/main/java/dev/relism/extension/FlashRegistrar.java
index 7943a0c..9442f9c 100644
--- a/flash/src/main/java/dev/relism/extension/FlashRegistrar.java
+++ b/flash/src/main/java/dev/relism/extension/FlashRegistrar.java
@@ -1,47 +1,106 @@
 package dev.relism.extension;
 
+import dev.relism.exceptions.InitializationException;
+import dev.relism.http.HttpMethod;
+import dev.relism.models.RequestHandler;
 import dev.relism.models.SimpleHandler;
-import dev.relism.routing.RouteHandle;
+import dev.relism.routing.Middleware;
+import dev.relism.routing.Route;
+import dev.relism.routing.Routes;
+
+import java.util.List;
 
 /**
- * Common registration surface shared by {@link FlashApp} and {@link FlashScope}.
+ * Common route-registration surface shared by {@link FlashApp} and {@link FlashScope}.
  *
- * <p>{@link FlashExtension#install} receives a {@code FlashRegistrar} so extensions
- * work identically whether installed at the top-level app or inside a mounted scope.
+ * <p>All route methods register <em>immediately</em> — no deferred {@code .with()} call.
+ * Middleware is passed as a varargs third argument:
  *
  * <pre>{@code
- * // In an extension:
- * public void install(FlashRegistrar app, FlashContext ctx) {
- *     app.get("/health", (req, res) -> "ok");
- *     app.get("/secured", (req, res) -> user()).with(oidc.protect());
- * }
+ * app.get("/ping",    (req, res) -> "pong")
+ * app.get("/secured", (req, res) -> user(), oidc.protect())
+ * app.get("/admin",   handler, oidc.requireRole("admin"), rateLimiter)
  * }</pre>
+ *
+ * <p>{@link FlashExtension#routes} receives a {@code FlashRegistrar<?>} for route
+ * registration. Extension installation ({@code install()}) is only available on
+ * {@link FlashApp} — scoped install is intentionally unsupported.
+ *
+ * @param <SELF> concrete registrar type — enables fluent chaining without casting
  */
-public interface FlashRegistrar {
+@SuppressWarnings("unchecked")
+public abstract class FlashRegistrar<SELF extends FlashRegistrar<SELF>> {
 
-    FlashRegistrar install(FlashExtension ext);
+    // ── HTTP method registration ──────────────────────────────────────────────
 
-    // ── Lambda route registration ────────────────────────────────────────────
+    public final SELF get    (String path, SimpleHandler.FunctionalHandler h, Middleware... mw) { return route(HttpMethod.GET,     path, h, mw); }
+    public final SELF post   (String path, SimpleHandler.FunctionalHandler h, Middleware... mw) { return route(HttpMethod.POST,    path, h, mw); }
+    public final SELF put    (String path, SimpleHandler.FunctionalHandler h, Middleware... mw) { return route(HttpMethod.PUT,     path, h, mw); }
+    public final SELF delete (String path, SimpleHandler.FunctionalHandler h, Middleware... mw) { return route(HttpMethod.DELETE,  path, h, mw); }
+    public final SELF patch  (String path, SimpleHandler.FunctionalHandler h, Middleware... mw) { return route(HttpMethod.PATCH,   path, h, mw); }
+    public final SELF options(String path, SimpleHandler.FunctionalHandler h, Middleware... mw) { return route(HttpMethod.OPTIONS, path, h, mw); }
+    public final SELF head   (String path, SimpleHandler.FunctionalHandler h, Middleware... mw) { return route(HttpMethod.HEAD,    path, h, mw); }
+    public final SELF trace  (String path, SimpleHandler.FunctionalHandler h, Middleware... mw) { return route(HttpMethod.TRACE,   path, h, mw); }
+    public final SELF connect(String path, SimpleHandler.FunctionalHandler h, Middleware... mw) { return route(HttpMethod.CONNECT, path, h, mw); }
+    public final SELF purge  (String path, SimpleHandler.FunctionalHandler h, Middleware... mw) { return route(HttpMethod.PURGE,   path, h, mw); }
 
-    RouteHandle<?> get    (String path, SimpleHandler.FunctionalHandler h);
-    RouteHandle<?> post   (String path, SimpleHandler.FunctionalHandler h);
-    RouteHandle<?> put    (String path, SimpleHandler.FunctionalHandler h);
-    RouteHandle<?> delete (String path, SimpleHandler.FunctionalHandler h);
-    RouteHandle<?> patch  (String path, SimpleHandler.FunctionalHandler h);
-    RouteHandle<?> options(String path, SimpleHandler.FunctionalHandler h);
-    RouteHandle<?> head   (String path, SimpleHandler.FunctionalHandler h);
-    RouteHandle<?> trace  (String path, SimpleHandler.FunctionalHandler h);
-    RouteHandle<?> connect(String path, SimpleHandler.FunctionalHandler h);
-    RouteHandle<?> purge  (String path, SimpleHandler.FunctionalHandler h);
+    // ── Middleware ────────────────────────────────────────────────────────────
 
     /**
-     * Scans {@code packageName} for classes that extend
-     * {@link dev.relism.models.RequestHandler} and carry
-     * {@link dev.relism.routing.Route @Route}. Each is instantiated via its
-     * no-arg constructor, run through annotation processors, and registered.
+     * Adds middlewares to this registrar's own scope.
+     * On {@link FlashApp}: applied to every route on the app.
+     * On {@link FlashScope}: applied to every route in this scope only.
+     * Order-independent: middleware is resolved at {@link FlashApp#start()}.
      */
-    FlashRegistrar scan(String packageName);
+    public final SELF use(Middleware... middlewares) {
+        for (Middleware m : middlewares) addMiddleware(m);
+        return (SELF) this;
+    }
+
+    // ── Scan ─────────────────────────────────────────────────────────────────
+
+    /**
+     * Scans {@code packageName} for {@link RequestHandler} subclasses with a routing
+     * annotation ({@link Route @Route} or {@code @GET}, {@code @POST}, …).
+     * Each match is constructed with its public no-arg constructor and registered immediately.
+     *
+     * @throws InitializationException if the package is empty, not found, or any handler
+     *         class fails to load or instantiate
+     */
+    public final SELF scan(String packageName) {
+        PackageScanner.findHandlers(packageName).forEach(cls -> {
+            Route ann = Routes.of(cls);
+            addRoute(ann.method(), ann.path(), instantiate(cls), List.of());
+        });
+        return (SELF) this;
+    }
 
     /** Returns the {@link FlashContext} for this registrar. */
-    FlashContext ctx();
+    public abstract FlashContext ctx();
+
+    // ── Infrastructure ────────────────────────────────────────────────────────
+
+    /**
+     * Adds a route immediately to this registrar's deferred compilation list.
+     * Subclasses may prepend a namespace prefix and inject scope middlewares before storing.
+     */
+    protected abstract void addRoute(HttpMethod method, String path,
+                                     RequestHandler handler, List<Middleware> mw);
+
+    /** Registers a middleware in this registrar's own scope (global or scope-level). */
+    protected abstract void addMiddleware(Middleware mw);
+
+    private SELF route(HttpMethod method, String path, SimpleHandler.FunctionalHandler h, Middleware[] mw) {
+        addRoute(method, path, new SimpleHandler(h), mw.length == 0 ? List.of() : List.of(mw));
+        return (SELF) this;
+    }
+
+    protected static RequestHandler instantiate(Class<?> cls) {
+        try { return (RequestHandler) cls.getDeclaredConstructor().newInstance(); }
+        catch (Exception e) {
+            throw new InitializationException(
+                    "Failed to instantiate " + cls.getName() +
+                    " — ensure it has a public no-arg constructor", e);
+        }
+    }
 }
diff --git a/flash/src/main/java/dev/relism/extension/FlashScope.java b/flash/src/main/java/dev/relism/extension/FlashScope.java
index ed36729..892733f 100644
--- a/flash/src/main/java/dev/relism/extension/FlashScope.java
+++ b/flash/src/main/java/dev/relism/extension/FlashScope.java
@@ -1,147 +1,58 @@
 package dev.relism.extension;
 
-import dev.relism.exceptions.InitializationException;
 import dev.relism.http.HttpMethod;
 import dev.relism.models.RequestHandler;
 import dev.relism.models.SimpleHandler;
 import dev.relism.routing.Middleware;
 import dev.relism.routing.PathUtils;
-import dev.relism.routing.Route;
-import dev.relism.routing.RouteHandle;
 
 import java.util.ArrayList;
-import java.util.Arrays;
 import java.util.List;
 
 /**
  * Scoped builder for namespace-prefixed routes. Pure syntactic sugar —
- * does not own a router. Collected routes merge into {@link FlashApp}'s
- * single flat router at {@link FlashApp#start()}.
+ * does not own a router. Routes merge into {@link FlashApp}'s single flat router
+ * at {@link FlashApp#start()}.
  *
  * <pre>{@code
  * app.mount("/api", scope -> {
  *     scope.use(authMiddleware);
- *     scope.get("/health", (req, res) -> "ok");   // → GET /api/health
+ *     scope.get("/health", (req, res) -> "ok");                    // → GET /api/health
+ *     scope.get("/users",  (req, res) -> "...", rateLimiter);      // → GET /api/users
  *     scope.scan("dev.example.api.handlers");
  * });
  * }</pre>
  */
-public final class FlashScope implements FlashRegistrar {
+public final class FlashScope extends FlashRegistrar<FlashScope> {
 
     private final String                namespace;
-    private final FlashContext      ctx;
+    private final FlashContext          ctx;
     private final List<Middleware>      scopeMiddlewares = new ArrayList<>();
     private final List<RouteDefinition> deferredRoutes   = new ArrayList<>();
 
-    private static final Middleware[] NO_MW = new Middleware[0];
-
-    private RouteHandle<?> pending;
-
     FlashScope(String namespace, FlashContext parentCtx) {
         this.namespace = namespace;
         this.ctx       = parentCtx.child();
     }
 
-    // ── Pending flush ─────────────────────────────────────────────────────────
+    @Override public FlashContext ctx() { return ctx; }
 
-    private void flushPending() {
-        if (pending != null) { pending.ensureRegistered(); pending = null; }
-    }
-
-    private <P> RouteHandle<P> track(RouteHandle<P> handle) {
-        flushPending();
-        pending = handle;
-        return handle;
-    }
-
-    // ── Scope middleware ──────────────────────────────────────────────────────
-
-    /**
-     * Adds middlewares applied to every route in this scope.
-     * Combined at compile time in order: Global → Scope → Annotation → Explicit.
-     */
-    public FlashScope use(Middleware... middlewares) {
-        flushPending();
-        scopeMiddlewares.addAll(Arrays.asList(middlewares));
-        return this;
-    }
-
-    // ── Extension installation ────────────────────────────────────────────────
+    // ── FlashRegistrar impl ───────────────────────────────────────────────────
 
     @Override
-    public FlashScope install(FlashExtension ext) {
-        flushPending();
-        ext.install(this, ctx);
-        return this;
-    }
-
-    // ── Route registration (deferred) ─────────────────────────────────────────
-
-    @Override public RouteHandle<FlashScope> get    (String path, SimpleHandler.FunctionalHandler h) { return lambda(HttpMethod.GET,     path, h); }
-    @Override public RouteHandle<FlashScope> post   (String path, SimpleHandler.FunctionalHandler h) { return lambda(HttpMethod.POST,    path, h); }
-    @Override public RouteHandle<FlashScope> put    (String path, SimpleHandler.FunctionalHandler h) { return lambda(HttpMethod.PUT,     path, h); }
-    @Override public RouteHandle<FlashScope> delete (String path, SimpleHandler.FunctionalHandler h) { return lambda(HttpMethod.DELETE,  path, h); }
-    @Override public RouteHandle<FlashScope> patch  (String path, SimpleHandler.FunctionalHandler h) { return lambda(HttpMethod.PATCH,   path, h); }
-    @Override public RouteHandle<FlashScope> options(String path, SimpleHandler.FunctionalHandler h) { return lambda(HttpMethod.OPTIONS, path, h); }
-    @Override public RouteHandle<FlashScope> head   (String path, SimpleHandler.FunctionalHandler h) { return lambda(HttpMethod.HEAD,    path, h); }
-    @Override public RouteHandle<FlashScope> trace  (String path, SimpleHandler.FunctionalHandler h) { return lambda(HttpMethod.TRACE,   path, h); }
-    @Override public RouteHandle<FlashScope> connect(String path, SimpleHandler.FunctionalHandler h) { return lambda(HttpMethod.CONNECT, path, h); }
-    @Override public RouteHandle<FlashScope> purge  (String path, SimpleHandler.FunctionalHandler h) { return lambda(HttpMethod.PURGE,   path, h); }
-
-    private RouteHandle<FlashScope> lambda(HttpMethod method, String path, SimpleHandler.FunctionalHandler h) {
-        String full = ns(path);
-        Middleware[] scopeMw = snapshotScopeMiddlewares();
-        return track(new RouteHandle<>(this, mw ->
-                deferredRoutes.add(new RouteDefinition(method, full, new SimpleHandler(h), scopeMw, mw, false, ctx, namespace))));
-    }
-
-    /**
-     * Registers a class-based handler annotated with {@link Route @Route}.
-     * Not part of {@link FlashRegistrar} — scope-only convenience.
-     */
-    RouteHandle<FlashScope> register(RequestHandler handler) {
-        Route ann = handler.getClass().getAnnotation(Route.class);
-        if (ann == null)
-            throw new InitializationException(
-                    handler.getClass().getName() + " is missing @Route");
-        String full = ns(ann.path());
-        Middleware[] scopeMw = snapshotScopeMiddlewares();
-        return track(new RouteHandle<>(this, mw ->
-                deferredRoutes.add(new RouteDefinition(ann.method(), full, handler, scopeMw, mw, true, ctx, namespace))));
+    protected void addRoute(HttpMethod method, String path, RequestHandler handler, List<Middleware> mw) {
+        List<Middleware> scopeMw = scopeMiddlewares.isEmpty() ? List.of() : List.copyOf(scopeMiddlewares);
+        deferredRoutes.add(new RouteDefinition(
+                method, ns(path), handler, scopeMw, mw,
+                !(handler instanceof SimpleHandler), ctx, namespace));
     }
 
     @Override
-    public FlashScope scan(String packageName) {
-        flushPending();
-        PackageScanner.findHandlers(packageName).forEach(cls ->
-                register(instantiate(cls)).ensureRegistered());
-        return this;
-    }
+    protected void addMiddleware(Middleware mw) { scopeMiddlewares.add(mw); }
 
-    @Override
-    public FlashContext ctx() { return ctx; }
-
-    // ── Internals (called by FlashApp.mount) ──────────────────────────────────
-
-    void flush() { flushPending(); }
+    // ── Internal (called by FlashApp.mount) ───────────────────────────────────
 
     List<RouteDefinition> routes() { return deferredRoutes; }
 
-    private String ns(String path) {
-        return namespace + PathUtils.sanitize(path);
-    }
-
-    private Middleware[] snapshotScopeMiddlewares() {
-        return scopeMiddlewares.isEmpty() ? NO_MW : scopeMiddlewares.toArray(NO_MW);
-    }
-
-    private static RequestHandler instantiate(Class<?> cls) {
-        try {
-            return (RequestHandler) cls.getDeclaredConstructor().newInstance();
-        } catch (Exception e) {
-            throw new InitializationException(
-                    "Failed to instantiate " + cls.getName() +
-                    " — ensure it has a public no-arg constructor", e);
-        }
-    }
+    private String ns(String path) { return namespace + PathUtils.sanitize(path); }
 }
diff --git a/flash/src/main/java/dev/relism/extension/PackageScanner.java b/flash/src/main/java/dev/relism/extension/PackageScanner.java
index fb6126c..bd98e69 100644
--- a/flash/src/main/java/dev/relism/extension/PackageScanner.java
+++ b/flash/src/main/java/dev/relism/extension/PackageScanner.java
@@ -2,7 +2,7 @@ package dev.relism.extension;
 
 import dev.relism.exceptions.InitializationException;
 import dev.relism.models.RequestHandler;
-import dev.relism.routing.Route;
+import dev.relism.routing.Routes;
 
 import java.io.File;
 import java.net.URL;
@@ -14,7 +14,8 @@ import java.util.jar.JarFile;
 
 /**
  * Minimal classpath scanner used by {@link FlashApp#scan} and {@link FlashScope#scan}.
- * Finds all classes in a package that extend {@link RequestHandler} and carry {@link Route @Route}.
+ * Finds {@link RequestHandler} subclasses in a package that carry a routing annotation
+ * ({@link Route @Route} or shorthand {@code @GET}, {@code @POST}, …).
  * Supports both exploded directories (development) and fat JARs (deployment).
  *
  * <p><b>Fail-fast:</b> if the package does not exist, contains no handlers, or a handler
@@ -26,8 +27,7 @@ final class PackageScanner {
     private PackageScanner() {}
 
     /**
-     * Returns all {@link RequestHandler} subclasses in {@code packageName} that carry
-     * {@link Route @Route}.
+     * Handlers in {@code packageName} that have {@link Routes#of(Class) resolvable} route metadata.
      *
      * @throws InitializationException if the package is empty, does not exist, or a
      *                                  handler class fails to load
@@ -76,8 +76,8 @@ final class PackageScanner {
 
         if (result.isEmpty())
             throw new InitializationException(
-                    "scan(\"" + packageName + "\") — no @Route handlers found. " +
-                    "Ensure handler classes extend RequestHandler, carry @Route, are not abstract, " +
+                    "scan(\"" + packageName + "\") — no routable handlers found. " +
+                    "Ensure classes extend RequestHandler, declare @Route or @GET/@POST/…, are not abstract, " +
                     "and have a public no-arg constructor.");
 
         return result;
@@ -99,10 +99,11 @@ final class PackageScanner {
 
     private static void scanJar(JarFile jar, String resourcePath, String packageName,
                                   ClassLoader cl, List<Class<?>> result, List<String> errors) {
+        String prefix = resourcePath + "/";
         Enumeration<JarEntry> entries = jar.entries();
         while (entries.hasMoreElements()) {
             String name = entries.nextElement().getName();
-            if (name.startsWith(resourcePath) && name.endsWith(".class") && !isAnonymous(name)) {
+            if (name.startsWith(prefix) && name.endsWith(".class") && !isAnonymous(name)) {
                 String className = name.replace('/', '.').replace(".class", "");
                 tryLoad(className, cl, result, errors);
             }
@@ -129,7 +130,7 @@ final class PackageScanner {
             Class<?> cls = cl.loadClass(className);
             if (!RequestHandler.class.isAssignableFrom(cls)) return;
             if (java.lang.reflect.Modifier.isAbstract(cls.getModifiers())) return;
-            if (!cls.isAnnotationPresent(Route.class)) return;
+            if (Routes.of(cls) == null) return;
 
             // Verify no-arg constructor exists — fail-fast if missing
             try {
diff --git a/flash/src/main/java/dev/relism/extension/RouteDefinition.java b/flash/src/main/java/dev/relism/extension/RouteDefinition.java
index 813b6fb..8306de9 100644
--- a/flash/src/main/java/dev/relism/extension/RouteDefinition.java
+++ b/flash/src/main/java/dev/relism/extension/RouteDefinition.java
@@ -4,6 +4,8 @@ import dev.relism.http.HttpMethod;
 import dev.relism.models.RequestHandler;
 import dev.relism.routing.Middleware;
 
+import java.util.List;
+
 /**
  * Immutable snapshot of a route captured during the builder phase.
  *
@@ -15,7 +17,7 @@ import dev.relism.routing.Middleware;
  * @param path                fully resolved path (namespace already prepended for scope routes)
  * @param handler             SimpleHandler for lambdas, user handler for class-based
  * @param scopeMiddlewares    middlewares from {@link FlashScope#use} (empty for app-level routes)
- * @param explicitMiddlewares middlewares from {@link dev.relism.routing.RouteHandle#with}
+ * @param explicitMiddlewares middlewares passed inline at registration ({@code app.get(path, handler, mw...)})
  * @param classBasedHandler   true → needs annotation processing + context binding
  * @param ctx                 the FlashContext for this route's binding and processors
  * @param namespace           logical namespace for route events ("/" for app, "/api" for scope, etc.)
@@ -24,8 +26,8 @@ record RouteDefinition(
         HttpMethod method,
         String path,
         RequestHandler handler,
-        Middleware[] scopeMiddlewares,
-        Middleware[] explicitMiddlewares,
+        List<Middleware> scopeMiddlewares,
+        List<Middleware> explicitMiddlewares,
         boolean classBasedHandler,
         FlashContext ctx,
         String namespace
diff --git a/flash/src/main/java/dev/relism/extension/RouteEvent.java b/flash/src/main/java/dev/relism/extension/RouteEvent.java
index df98c98..721467b 100644
--- a/flash/src/main/java/dev/relism/extension/RouteEvent.java
+++ b/flash/src/main/java/dev/relism/extension/RouteEvent.java
@@ -18,14 +18,14 @@ import java.util.List;
  * <ol>
  *   <li>Router-level middlewares (set on the router constructor)</li>
  *   <li>Annotation-injected middlewares (e.g. from {@code @Authenticated})</li>
- *   <li>Handler-level explicit middlewares (passed via {@code .with(...)})</li>
+ *   <li>Handler-level explicit middlewares (passed inline: {@code app.get(path, h, mw...)})</li>
  * </ol>
  *
  * <h3>Handler abstraction chain</h3>
  * Walk {@link #handlerClass} upward via {@link Class#getSuperclass()} to reconstruct
  * the full inheritance chain (e.g. {@code EditPostPageHandler → HtmlHandler → RequestHandler}).
  * Read {@link Class#getAnnotations()} on each level to discover declared pointcuts
- * ({@code @Authenticated}, {@code @RolesAllowed}, {@code @Route}, etc.).
+ * ({@code @Authenticated}, {@code @RolesAllowed}, {@code @Route}/{@code @GET}, etc.).
  *
  * @param method          HTTP method for this route
  * @param path            full path as declared (including namespace prefix for scoped routes)
diff --git a/flash/src/main/java/dev/relism/models/HeaderMap.java b/flash/src/main/java/dev/relism/models/HeaderMap.java
index bbe95b4..e530631 100644
--- a/flash/src/main/java/dev/relism/models/HeaderMap.java
+++ b/flash/src/main/java/dev/relism/models/HeaderMap.java
@@ -8,9 +8,27 @@ import java.util.ArrayList;
 import java.util.List;
 
 /**
- * Lazy header access backed by a raw byte slice of the request buffer.
- * No allocations at parse time; Strings are created only when {@link #first} / {@link #all} is called.
- * One instance per connection; reused across keep-alive requests via {@link #reset}.
+ * Lazy, zero-copy header access backed directly by the request parser's byte buffer.
+ * Strings are allocated only when {@link #first} / {@link #all} / {@link #view} is called;
+ * the raw bytes are never copied at parse time.
+ *
+ * <h3>Lifetime contract — read carefully</h3>
+ * One {@code HeaderMap} instance lives on the connection (not per-request). On every
+ * keep-alive request {@link #reset} is called to slide the window over the new header
+ * section of the <em>same reused buffer</em>. This has two critical implications:
+ *
+ * <ol>
+ *   <li><b>Do not retain the {@code HeaderMap} beyond the handler.</b> After the handler
+ *       returns, the next request reuses and overwrites the buffer. Any {@code String}
+ *       values retrieved via {@link #first}/{@link #all} are safe (they are independent
+ *       heap copies); the {@code HeaderMap} object itself is not.</li>
+ *   <li><b>{@link #view} returns a zero-copy {@link dev.relism.fpr.core.ByteView} slice
+ *       into the live buffer.</b> Storing this view and reading it after the handler
+ *       returns (e.g. in an async callback, a {@link java.util.concurrent.CompletableFuture}
+ *       continuation, or a virtual-thread handoff) is a <em>data race</em> — the bytes
+ *       may have been overwritten by the next request. Copy to a {@code String} or
+ *       {@code byte[]} before leaving the synchronous handler scope.</li>
+ * </ol>
  */
 @NoArgsConstructor
 public class HeaderMap {
diff --git a/flash/src/main/java/dev/relism/models/PathParams.java b/flash/src/main/java/dev/relism/models/PathParams.java
index 24e9b68..c9989c2 100644
--- a/flash/src/main/java/dev/relism/models/PathParams.java
+++ b/flash/src/main/java/dev/relism/models/PathParams.java
@@ -21,6 +21,15 @@ public class PathParams {
         this.lens   = lens;
     }
 
+    /**
+     * Injects path parameters into a request. The cross-package bridge from
+     * {@link dev.relism.routing.AbstractRouter} — keeps {@link Request#setPathParams}
+     * package-private while allowing the router to set params without a public setter.
+     */
+    public static void inject(Request request, PathParams params) {
+        request.setPathParams(params);
+    }
+
     public String get(String name) {
         int i = indexOf(name);
         if (i < 0) return null;
diff --git a/flash/src/main/java/dev/relism/models/Request.java b/flash/src/main/java/dev/relism/models/Request.java
index eac3462..004b75c 100644
--- a/flash/src/main/java/dev/relism/models/Request.java
+++ b/flash/src/main/java/dev/relism/models/Request.java
@@ -4,7 +4,6 @@ import dev.relism.fpr.core.ByteView;
 import dev.relism.http.HttpMethod;
 import lombok.EqualsAndHashCode;
 import lombok.Getter;
-import lombok.Setter;
 import lombok.ToString;
 import lombok.Value;
 import lombok.experimental.NonFinal;
@@ -16,7 +15,7 @@ import java.util.List;
 
 /**
  * Immutable view of an incoming HTTP/1.1 request. Constructed by {@link dev.relism.RequestParser}
- * and passed directly to route handlers — never modified after creation (path/query params are
+ * and passed directly to route handlers; never modified after creation (path/query params are
  * injected once by the router before the handler runs).
  *
  * <pre>{@code
@@ -41,17 +40,18 @@ public class Request {
     /** Internal: the parsed request line (method, path, query, protocol, headers). */
     RequestLine requestLine;
 
-    @NonFinal @Setter PathParams  pathParams;
-    @NonFinal @Setter QueryParams queryParams;
+    @NonFinal PathParams  pathParams;
+    @NonFinal QueryParams queryParams;
+    @NonFinal String cachedPath;
 
     /**
      * Remote socket address of the connected client. Set once at connection time from
-     * {@link java.net.Socket#getRemoteSocketAddress()} — the {@link InetSocketAddress}
+     * {@link java.net.Socket#getRemoteSocketAddress()} : the {@link InetSocketAddress}
      * object already exists in the JDK and is passed by reference: zero allocation,
      * zero copy. {@code null} only in test-constructed requests.
      *
      * <p>Use {@link #remoteAddress()} to access it. String conversion
-     * ({@code .getAddress().getHostAddress()}) is deferred to the caller — lazy and
+     * ({@code .getAddress().getHostAddress()}) is deferred to the caller, lazy and
      * only paid when actually needed.
      */
     @Getter(lombok.AccessLevel.NONE)
@@ -67,6 +67,13 @@ public class Request {
         this.remoteAddress = remoteAddress;
     }
 
+    /**
+     * Internal: injects path parameters after routing. Package-private so only
+     * {@link PathParams#inject} (same package) can call it — not user code.
+     * Use {@link PathParams#inject(Request, PathParams)} from routing code.
+     */
+    void setPathParams(PathParams p) { this.pathParams = p; }
+
     /** Test / manual constructor — {@code remoteAddress()} returns {@code null}. */
     public Request(RequestLine requestLine, byte[] body) {
         this(requestLine, RequestBody.of(body), null);
@@ -92,10 +99,11 @@ public class Request {
      * Example: a request for {@code /users/42?page=1} returns {@code "/users/42"}.
      */
     public String path() {
+        if (cachedPath != null) return cachedPath;
         ByteView v = requestLine.getPath();
         byte[] buf = new byte[v.length()];
         for (int i = 0; i < v.length(); i++) buf[i] = v.byteAt(i);
-        return new String(buf, StandardCharsets.UTF_8);
+        return cachedPath = new String(buf, StandardCharsets.UTF_8);
     }
 
     // ── Headers ───────────────────────────────────────────────────────────────
diff --git a/flash/src/main/java/dev/relism/models/RequestBody.java b/flash/src/main/java/dev/relism/models/RequestBody.java
index c57a21d..8f913a1 100644
--- a/flash/src/main/java/dev/relism/models/RequestBody.java
+++ b/flash/src/main/java/dev/relism/models/RequestBody.java
@@ -41,19 +41,16 @@ public final class RequestBody {
         this.preBufLen     = preBufLen;
     }
 
-    static RequestBody of(byte[] bytes) {
-        RequestBody b = new RequestBody(null, bytes.length, null, 0, 0);
-        b.resolved = bytes;
-        return b;
+    /** Pre-resolved body: test payloads and empty body — skips all I/O. */
+    private RequestBody(byte[] preResolved) {
+        this(null, preResolved.length, null, 0, 0);
+        this.resolved = preResolved;
     }
 
-    private static final RequestBody EMPTY_INSTANCE;
-    static {
-        EMPTY_INSTANCE = new RequestBody(null, 0, null, 0, 0);
-        EMPTY_INSTANCE.resolved = EMPTY_BYTES;
-    }
+    private static final RequestBody EMPTY = new RequestBody(EMPTY_BYTES);
 
-    static RequestBody empty() { return EMPTY_INSTANCE; }
+    static RequestBody of(byte[] bytes) { return new RequestBody(bytes); }
+    static RequestBody empty()          { return EMPTY; }
 
     /** {@code true} if the body has zero bytes ({@code Content-Length: 0} or no body). */
     public boolean isEmpty() { return contentLength == 0; }
diff --git a/flash/src/main/java/dev/relism/models/RequestHandler.java b/flash/src/main/java/dev/relism/models/RequestHandler.java
index fa29cc4..73b0608 100644
--- a/flash/src/main/java/dev/relism/models/RequestHandler.java
+++ b/flash/src/main/java/dev/relism/models/RequestHandler.java
@@ -7,9 +7,9 @@ import java.util.Optional;
 /**
  * Base class for class-based route handlers.
  *
- * <p>Annotate the subclass with {@link dev.relism.routing.Route @Route} and register it
- * via {@link dev.relism.extension.FlashApp#register} or {@link dev.relism.extension.FlashApp#scan}.
- * For one-off routes, prefer the lambda DSL ({@code app.get(path, handler)}).
+ * <p>Declare the route with {@link dev.relism.routing.Route @Route} or a shorthand such as
+ * {@code @GET("/path")}, then register via {@link dev.relism.extension.FlashApp#scan}.
+ * For ad-hoc routes use the fluent API ({@code app.get(path, handler)} or with middleware).
  *
  * <h3>Lifecycle</h3>
  * <ol>
@@ -24,7 +24,7 @@ import java.util.Optional;
  * into private fields. This keeps the hot-path ({@code handle}) free of map lookups.
  *
  * <pre>{@code
- * @Route(method = HttpMethod.GET, path = "/users")
+ * @GET("/users")
  * public class UserHandler extends RequestHandler {
  *     private UserService users;
  *
@@ -47,8 +47,7 @@ public abstract class RequestHandler {
      * Injects the {@link FlashContext} and triggers {@link #onInit()}.
      *
      * <p><b>Infrastructure method</b> — do not call from user code.
-     * Use {@link dev.relism.extension.FlashApp#register} or
-     * {@link dev.relism.extension.FlashApp#scan} instead.
+     * Use {@link dev.relism.extension.FlashApp#scan} instead.
      */
     public final void bind(FlashContext ctx) {
         this.ctx = ctx;
@@ -122,7 +121,7 @@ public abstract class RequestHandler {
         if (ctx == null)
             throw new IllegalStateException(
                     getClass().getSimpleName() + " has not been bound to a FlashContext — " +
-                    "register via FlashApp.register() or FlashApp.scan(), not directly on the router");
+                    "register via FlashApp.scan(), not directly on the router");
     }
 
     /**
diff --git a/flash/src/main/java/dev/relism/models/Response.java b/flash/src/main/java/dev/relism/models/Response.java
index 7769889..b494943 100644
--- a/flash/src/main/java/dev/relism/models/Response.java
+++ b/flash/src/main/java/dev/relism/models/Response.java
@@ -137,6 +137,16 @@ public class Response {
         return this;
     }
 
+    /**
+     * Adds a pre-encoded header (e.g. a static {@code "X-RateLimit-Limit: 100\r\n"} byte array
+     * pre-built at boot time). Zero-alloc on both the call path and the write path.
+     */
+    public Response header(byte[] preEncoded) {
+        if (headers == null) headers = new ArrayList<>();
+        headers.add(preEncoded);
+        return this;
+    }
+
     // -------------------------------------------------------------------------
     // State queries
     // -------------------------------------------------------------------------
@@ -147,21 +157,28 @@ public class Response {
     // Internal setters used by HttpServer for handler return values
     // -------------------------------------------------------------------------
 
-    /** Sets the body from an arbitrary handler return value. */
+    /**
+     * Sets the body from a handler return value. Accepted types: {@code byte[]},
+     * {@link String}, {@link CharSequence}. Any other non-null type throws
+     * {@link IllegalArgumentException} — return a {@code Response} directly, or
+     * serialize to {@code String}/{@code byte[]} before returning.
+     */
     public Response setBody(Object body) {
-        if (body instanceof byte[] bytes) this.body = bytes;
-        else if (body != null)            this.body = body.toString().getBytes(StandardCharsets.UTF_8);
+        if (body instanceof byte[] bytes)   { this.body = bytes; return this; }
+        if (body instanceof String s)       { this.body = s.getBytes(StandardCharsets.UTF_8); return this; }
+        if (body instanceof CharSequence s) { this.body = s.toString().getBytes(StandardCharsets.UTF_8); return this; }
+        if (body != null) throw new IllegalArgumentException(
+                "Handler returned unsupported type: " + body.getClass().getName()
+                + " — return String, byte[], Response, or null");
         return this;
     }
 
-    public void setContentType(ContentType ct) { this.contentType = ct.getBytes(); }
-
     /** Returns custom headers, or an empty list if none were added. */
     public List<byte[]> getHeaders() { return headers != null ? headers : List.of(); }
 
     /** Writes pre-encoded custom headers directly to {@code out}. Zero-alloc when no headers are set. */
     public void writeHeaders(OutputStream out) throws IOException {
         if (headers == null) return;
-        for (int i = 0, n = headers.size(); i < n; i++) out.write(headers.get(i));
+        for (byte[] header : headers) out.write(header);
     }
 }
diff --git a/flash/src/main/java/dev/relism/models/SimpleHandler.java b/flash/src/main/java/dev/relism/models/SimpleHandler.java
index 409ff01..d064c1e 100644
--- a/flash/src/main/java/dev/relism/models/SimpleHandler.java
+++ b/flash/src/main/java/dev/relism/models/SimpleHandler.java
@@ -1,16 +1,17 @@
 package dev.relism.models;
 
-import lombok.RequiredArgsConstructor;
-
 /**
- * A concrete implementation of {@link RequestHandler} that delegates to a functional interface.
- * This allows the use of lambdas while keeping the base {@link RequestHandler} as an abstract class.
+ * Delegates {@link #handle} to a {@link FunctionalHandler} so lambdas can be used without
+ * relying on Lombok-generated constructors (IDE-safe, annotation-processing independent).
  */
-@RequiredArgsConstructor
 public class SimpleHandler extends RequestHandler {
 
     private final FunctionalHandler delegate;
 
+    public SimpleHandler(FunctionalHandler delegate) {
+        this.delegate = delegate;
+    }
+
     @Override
     public Object handle(Request request, Response response) throws Exception {
         return delegate.handle(request, response);
diff --git a/flash/src/main/java/dev/relism/routing/AbstractRouter.java b/flash/src/main/java/dev/relism/routing/AbstractRouter.java
index f906bbf..0029994 100644
--- a/flash/src/main/java/dev/relism/routing/AbstractRouter.java
+++ b/flash/src/main/java/dev/relism/routing/AbstractRouter.java
@@ -1,11 +1,14 @@
 package dev.relism.routing;
 
+import dev.relism.Flash;
 import dev.relism.http.ContentType;
 import dev.relism.http.HttpMethod;
 import dev.relism.fpr.core.ByteView;
 import dev.relism.models.*;
 import dev.relism.template.ErrorPages;
 
+import java.nio.charset.StandardCharsets;
+
 /**
  * Base router contract. Owns error handlers and the compile-time middleware
  * wrapping logic. The only concrete implementation is
@@ -14,22 +17,48 @@ import dev.relism.template.ErrorPages;
  * <p>All middleware composition happens once at boot time; the hot-path sees
  * only a plain {@link RequestHandler} call with zero allocation overhead.
  *
+ * <h3>Default error handlers</h3>
+ * <ul>
+ *   <li><b>Dev mode</b> ({@code -Dflash.env=dev}): rich HTML pages with full stack traces.</li>
+ *   <li><b>Prod mode</b> (default): generic JSON — no internal detail leaked to clients.</li>
+ * </ul>
+ * Override via {@link dev.relism.extension.FlashApp#onNotFound} /
+ * {@link dev.relism.extension.FlashApp#onException}.
+ *
  * <p><b>Registration</b>: use {@link dev.relism.extension.FlashApp} — the single
  * public registration API. {@link #doRegister} is an infrastructure method.
  */
 public abstract class AbstractRouter {
 
-    protected SimpleHandler notFoundHandler = new SimpleHandler((req, res) -> {
-        res.setStatusCode(404);
-        res.setContentType(ContentType.TEXT_HTML);
-        return ErrorPages.renderNotFound(req);
-    });
+    // Pre-encoded prod JSON error bodies — zero allocation on error paths.
+    private static final byte[] JSON_404 = "{\"error\":\"Not Found\",\"status\":404}"
+            .getBytes(StandardCharsets.UTF_8);
+    private static final byte[] JSON_500 = "{\"error\":\"Internal Server Error\",\"status\":500}"
+            .getBytes(StandardCharsets.UTF_8);
 
-    protected ExceptionHandler exceptionHandler = (ex, req, res) -> {
-        res.setStatusCode(500);
-        res.setContentType(ContentType.TEXT_HTML);
-        return ErrorPages.renderException(req, ex);
-    };
+    protected SimpleHandler notFoundHandler = Flash.DEV
+            ? new SimpleHandler((req, res) -> {
+                res.status(404);
+                res.type(ContentType.TEXT_HTML);
+                return ErrorPages.renderNotFound(req);
+            })
+            : new SimpleHandler((req, res) -> {
+                res.status(404);
+                res.type(ContentType.JSON);
+                return JSON_404;
+            });
+
+    protected ExceptionHandler exceptionHandler = Flash.DEV
+            ? (ex, req, res) -> {
+                res.status(500);
+                res.type(ContentType.TEXT_HTML);
+                return ErrorPages.renderException(req, ex);
+            }
+            : (ex, req, res) -> {
+                res.status(500);
+                res.type(ContentType.JSON);
+                return JSON_500;
+            };
 
     public SimpleHandler    getNotFoundHandler()  { return notFoundHandler; }
     public ExceptionHandler getExceptionHandler() { return exceptionHandler; }
@@ -72,7 +101,7 @@ public abstract class AbstractRouter {
     protected abstract AbstractRouter addRoute(HttpMethod method, String path, RequestHandler handler);
 
     protected static void setPathParams(Request request, String[] names, ByteView source, int[] starts, int[] lens) {
-        request.setPathParams(new PathParams(source, names, starts, lens));
+        PathParams.inject(request, new PathParams(source, names, starts, lens));
     }
 
     @FunctionalInterface
diff --git a/flash/src/main/java/dev/relism/routing/CONNECT.java b/flash/src/main/java/dev/relism/routing/CONNECT.java
new file mode 100644
index 0000000..26ca9af
--- /dev/null
+++ b/flash/src/main/java/dev/relism/routing/CONNECT.java
@@ -0,0 +1,16 @@
+package dev.relism.routing;
+
+import dev.relism.http.HttpMethod;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/** Shorthand for {@code @Route(method = HttpMethod.CONNECT, path = "…")}. */
+@Route(method = HttpMethod.CONNECT, path = "")
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+public @interface CONNECT {
+    String value();
+}
diff --git a/flash/src/main/java/dev/relism/routing/DELETE.java b/flash/src/main/java/dev/relism/routing/DELETE.java
new file mode 100644
index 0000000..fa7e2ef
--- /dev/null
+++ b/flash/src/main/java/dev/relism/routing/DELETE.java
@@ -0,0 +1,16 @@
+package dev.relism.routing;
+
+import dev.relism.http.HttpMethod;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/** Shorthand for {@code @Route(method = HttpMethod.DELETE, path = "…")}. */
+@Route(method = HttpMethod.DELETE, path = "")
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+public @interface DELETE {
+    String value();
+}
diff --git a/flash/src/main/java/dev/relism/routing/GET.java b/flash/src/main/java/dev/relism/routing/GET.java
new file mode 100644
index 0000000..0131b33
--- /dev/null
+++ b/flash/src/main/java/dev/relism/routing/GET.java
@@ -0,0 +1,16 @@
+package dev.relism.routing;
+
+import dev.relism.http.HttpMethod;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/** Shorthand for {@code @Route(method = HttpMethod.GET, path = "…")}. */
+@Route(method = HttpMethod.GET, path = "")
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+public @interface GET {
+    String value();
+}
diff --git a/flash/src/main/java/dev/relism/routing/HEAD.java b/flash/src/main/java/dev/relism/routing/HEAD.java
new file mode 100644
index 0000000..9aeab1a
--- /dev/null
+++ b/flash/src/main/java/dev/relism/routing/HEAD.java
@@ -0,0 +1,16 @@
+package dev.relism.routing;
+
+import dev.relism.http.HttpMethod;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/** Shorthand for {@code @Route(method = HttpMethod.HEAD, path = "…")}. */
+@Route(method = HttpMethod.HEAD, path = "")
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+public @interface HEAD {
+    String value();
+}
diff --git a/flash/src/main/java/dev/relism/routing/Middleware.java b/flash/src/main/java/dev/relism/routing/Middleware.java
index f925880..fadc11d 100644
--- a/flash/src/main/java/dev/relism/routing/Middleware.java
+++ b/flash/src/main/java/dev/relism/routing/Middleware.java
@@ -28,8 +28,8 @@ import dev.relism.models.SimpleHandler;
  * AbstractRouter api = new MyRouter(cors, auth);
  *
  * // Handler-level: applied only to this route
- * router.get("/admin", (req, res) -> "secret", auth);
- * router.register(new AdminHandler(), auth, logging);
+ * app.get("/admin", (req, res) -> "secret", auth);
+ * app.get("/log",   handler, logging, auth);
  * }</pre>
  */
 @FunctionalInterface
@@ -68,15 +68,4 @@ public interface Middleware {
         };
     }
 
-    /**
-     * Returns a composed middleware that applies {@code this} first, then {@code after}.
-     * Prefer {@link #of} for three or more middlewares.
-     *
-     * <pre>{@code
-     * Middleware secured = cors.andThen(auth);
-     * }</pre>
-     */
-    default Middleware andThen(Middleware after) {
-        return next -> this.wrap(new SimpleHandler(after.wrap(next)));
-    }
 }
diff --git a/flash/src/main/java/dev/relism/routing/OPTIONS.java b/flash/src/main/java/dev/relism/routing/OPTIONS.java
new file mode 100644
index 0000000..7417c77
--- /dev/null
+++ b/flash/src/main/java/dev/relism/routing/OPTIONS.java
@@ -0,0 +1,16 @@
+package dev.relism.routing;
+
+import dev.relism.http.HttpMethod;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/** Shorthand for {@code @Route(method = HttpMethod.OPTIONS, path = "…")}. */
+@Route(method = HttpMethod.OPTIONS, path = "")
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+public @interface OPTIONS {
+    String value();
+}
diff --git a/flash/src/main/java/dev/relism/routing/PATCH.java b/flash/src/main/java/dev/relism/routing/PATCH.java
new file mode 100644
index 0000000..259708e
--- /dev/null
+++ b/flash/src/main/java/dev/relism/routing/PATCH.java
@@ -0,0 +1,16 @@
+package dev.relism.routing;
+
+import dev.relism.http.HttpMethod;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/** Shorthand for {@code @Route(method = HttpMethod.PATCH, path = "…")}. */
+@Route(method = HttpMethod.PATCH, path = "")
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+public @interface PATCH {
+    String value();
+}
diff --git a/flash/src/main/java/dev/relism/routing/POST.java b/flash/src/main/java/dev/relism/routing/POST.java
new file mode 100644
index 0000000..303495d
--- /dev/null
+++ b/flash/src/main/java/dev/relism/routing/POST.java
@@ -0,0 +1,16 @@
+package dev.relism.routing;
+
+import dev.relism.http.HttpMethod;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/** Shorthand for {@code @Route(method = HttpMethod.POST, path = "…")}. */
+@Route(method = HttpMethod.POST, path = "")
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+public @interface POST {
+    String value();
+}
diff --git a/flash/src/main/java/dev/relism/routing/PURGE.java b/flash/src/main/java/dev/relism/routing/PURGE.java
new file mode 100644
index 0000000..08a30c6
--- /dev/null
+++ b/flash/src/main/java/dev/relism/routing/PURGE.java
@@ -0,0 +1,16 @@
+package dev.relism.routing;
+
+import dev.relism.http.HttpMethod;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/** Shorthand for {@code @Route(method = HttpMethod.PURGE, path = "…")}. */
+@Route(method = HttpMethod.PURGE, path = "")
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+public @interface PURGE {
+    String value();
+}
diff --git a/flash/src/main/java/dev/relism/routing/PUT.java b/flash/src/main/java/dev/relism/routing/PUT.java
new file mode 100644
index 0000000..007c8f9
--- /dev/null
+++ b/flash/src/main/java/dev/relism/routing/PUT.java
@@ -0,0 +1,16 @@
+package dev.relism.routing;
+
+import dev.relism.http.HttpMethod;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/** Shorthand for {@code @Route(method = HttpMethod.PUT, path = "…")}. */
+@Route(method = HttpMethod.PUT, path = "")
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+public @interface PUT {
+    String value();
+}
diff --git a/flash/src/main/java/dev/relism/routing/Route.java b/flash/src/main/java/dev/relism/routing/Route.java
index efdfd1e..abbe730 100644
--- a/flash/src/main/java/dev/relism/routing/Route.java
+++ b/flash/src/main/java/dev/relism/routing/Route.java
@@ -8,16 +8,16 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Declares the HTTP method and path for a class-based {@link dev.relism.models.RequestHandler}.
+ * HTTP method and path for a class-based {@link dev.relism.models.RequestHandler}.
+ * Path is relative to the mount namespace (e.g. {@code path = "/profile"} under {@code /api}
+ * → {@code /api/profile}).
  *
- * <p>The path is relative to the namespace of the router the handler is registered on.
- * For example, registering a handler with {@code path = "/profile"} on a router mounted
- * at {@code /api} results in the effective route {@code /api/profile}.
- *
- * <p>Used by {@link dev.relism.routing.AbstractRouter#register}.
+ * <p>Prefer shorthand ({@code @GET("/x")}, {@code @POST("/x")}, …); they are meta-annotated
+ * with {@code @Route} and resolve to the same metadata as an explicit {@code @Route(method=…, path=…)}
+ * via {@link Routes#of(Class)}.
  */
 @Retention(RetentionPolicy.RUNTIME)
-@Target(ElementType.TYPE)
+@Target({ElementType.TYPE, ElementType.ANNOTATION_TYPE})
 public @interface Route {
     HttpMethod method() default HttpMethod.GET;
     String path();
diff --git a/flash/src/main/java/dev/relism/routing/RouteHandle.java b/flash/src/main/java/dev/relism/routing/RouteHandle.java
deleted file mode 100644
index 20a1ffd..0000000
--- a/flash/src/main/java/dev/relism/routing/RouteHandle.java
+++ /dev/null
@@ -1,70 +0,0 @@
-package dev.relism.routing;
-
-import java.util.function.Consumer;
-
-/**
- * Deferred route registration handle returned by {@code router.get()},
- * {@code router.post()}, {@code app.get()}, {@code app.register()}, etc.
- *
- * <p>The route is <em>not</em> registered until {@link #with} is called.
- * This separates the handler declaration from the middleware declaration,
- * keeping the registration methods clean.
- *
- * <pre>{@code
- * // No middleware
- * app.get("/ping", (req, res) -> "pong").with();
- *
- * // With middleware
- * app.get("/me",    (req, res) -> ClaimsHolder.user().email()).with(oidc.protect());
- * app.get("/admin", (req, res) -> "admin").with(oidc.requireRole("admin"));
- *
- * // Class-based handler — annotations (@Authenticated, @RolesAllowed) are
- * // processed automatically; .with() can add extra middleware on top.
- * app.register(new MyHandler()).with();
- * app.register(new SecuredHandler()).with(logging);
- * }</pre>
- *
- * @param <P> the parent type returned by {@link #with} for further chaining
- *            ({@link dev.relism.extension.FlashApp} or {@link AbstractRouter})
- */
-public final class RouteHandle<P> {
-
-    private final P parent;
-    private final Consumer<Middleware[]> registerFn;
-    private boolean registered = false;
-
-    public RouteHandle(P parent, Consumer<Middleware[]> registerFn) {
-        this.parent = parent;
-        this.registerFn = registerFn;
-    }
-
-    /**
-     * Registers the route with the given middlewares and returns the parent
-     * for further chaining.
-     *
-     * <p>Calling without arguments is equivalent to registering with no middleware.
-     * When using {@link dev.relism.extension.FlashApp}, calling {@code .with()} is
-     * optional for routes that need no middleware — the route is registered
-     * automatically before the next operation or at {@code start()}.
-     *
-     * @param middlewares zero or more middlewares; first element executes outermost
-     * @return the parent ({@link dev.relism.extension.FlashApp} or
-     *         {@link AbstractRouter}) for further method chaining
-     */
-    public P with(Middleware... middlewares) {
-        if (!registered) {
-            registerFn.accept(middlewares);
-            registered = true;
-        }
-        return parent;
-    }
-
-    /**
-     * Registers the route with no middleware if it has not been registered yet.
-     * Called automatically by {@link dev.relism.extension.FlashApp} before each
-     * new route registration and at {@code start()}.
-     */
-    public void ensureRegistered() {
-        with();
-    }
-}
diff --git a/flash/src/main/java/dev/relism/routing/Routes.java b/flash/src/main/java/dev/relism/routing/Routes.java
new file mode 100644
index 0000000..117b06e
--- /dev/null
+++ b/flash/src/main/java/dev/relism/routing/Routes.java
@@ -0,0 +1,34 @@
+package dev.relism.routing;
+
+import dev.relism.http.HttpMethod;
+
+import java.lang.annotation.Annotation;
+
+/** Boot-time resolution of {@link Route} from a handler class (direct {@code @Route} or shorthand). */
+public final class Routes {
+    private Routes() {}
+
+    /**
+     * Effective route for {@code cls}, or {@code null}. Prefers {@code @Route} on the class;
+     * otherwise the first annotation type meta-annotated with {@code @Route} (e.g. {@code @GET}).
+     * If several routing annotations are present, behaviour is undefined — use one.
+     */
+    public static Route of(Class<?> cls) {
+        Route direct = cls.getAnnotation(Route.class);
+        if (direct != null) return direct;
+        for (Annotation ann : cls.getAnnotations()) {
+            Route meta = ann.annotationType().getAnnotation(Route.class);
+            if (meta == null) continue;
+            try {
+                String path = (String) ann.annotationType().getMethod("value").invoke(ann);
+                final HttpMethod method = meta.method();
+                return new Route() {
+                    public HttpMethod method()                           { return method; }
+                    public String path()                                { return path;   }
+                    public Class<? extends Annotation> annotationType() { return Route.class; }
+                };
+            } catch (ReflectiveOperationException ignored) {}
+        }
+        return null;
+    }
+}
diff --git a/flash/src/main/java/dev/relism/routing/TRACE.java b/flash/src/main/java/dev/relism/routing/TRACE.java
new file mode 100644
index 0000000..dedabf8
--- /dev/null
+++ b/flash/src/main/java/dev/relism/routing/TRACE.java
@@ -0,0 +1,16 @@
+package dev.relism.routing;
+
+import dev.relism.http.HttpMethod;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/** Shorthand for {@code @Route(method = HttpMethod.TRACE, path = "…")}. */
+@Route(method = HttpMethod.TRACE, path = "")
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+public @interface TRACE {
+    String value();
+}
diff --git a/flash/src/test/java/dev/relism/HttpServerConcurrencyTest.java b/flash/src/test/java/dev/relism/HttpServerConcurrencyTest.java
index f76c7fb..f121037 100644
--- a/flash/src/test/java/dev/relism/HttpServerConcurrencyTest.java
+++ b/flash/src/test/java/dev/relism/HttpServerConcurrencyTest.java
@@ -46,7 +46,7 @@ class HttpServerConcurrencyTest {
             return new Response(200, body, ContentType.TEXT_PLAIN);
         });
 
-        app.start().get(5, TimeUnit.SECONDS);
+        app.start();
 
         httpClient = HttpClient.newBuilder()
                 .version(HttpClient.Version.HTTP_1_1)
@@ -188,7 +188,7 @@ class HttpServerConcurrencyTest {
             freshApp.get("/route" + idx, (req, res) -> "handler" + idx);
         }
 
-        freshApp.start().get(5, TimeUnit.SECONDS);
+        freshApp.start();
 
         int count = 20;
         ExecutorService pool = Executors.newFixedThreadPool(count);
diff --git a/flash/src/test/java/dev/relism/HttpServerTest.java b/flash/src/test/java/dev/relism/HttpServerTest.java
index 427e503..4e1e7b4 100644
--- a/flash/src/test/java/dev/relism/HttpServerTest.java
+++ b/flash/src/test/java/dev/relism/HttpServerTest.java
@@ -61,7 +61,7 @@ class HttpServerTest {
             return res.body(body);
         });
 
-        app.start().get(5, TimeUnit.SECONDS);
+        app.start();
     }
 
     @AfterEach
@@ -148,29 +148,31 @@ class HttpServerTest {
     }
 
     @Test
-    void testNotFound_returns404Html() throws Exception {
+    void testNotFound_returns404() throws Exception {
         String req = "GET /api/unknown HTTP/1.1\r\nHost: localhost\r\n\r\n";
         String res = sendRawRequest(req);
         assertTrue(res.startsWith("HTTP/1.1 404 Not Found"));
-        assertTrue(res.contains("404"));
-        assertTrue(res.contains("No route matched this request"));
+        // Prod default: JSON body — no internal details leaked
+        assertTrue(res.contains("\"status\":404"));
+        assertTrue(res.contains("application/json"));
     }
 
     @Test
-    void testException_returns500Html() throws Exception {
+    void testException_returns500() throws Exception {
         String req = "GET /api/crash HTTP/1.1\r\nHost: localhost\r\n\r\n";
         String res = sendRawRequest(req);
         assertTrue(res.startsWith("HTTP/1.1 500 Internal Server Error"));
-        assertTrue(res.contains("500"));
-        assertTrue(res.contains("Simulated Crash"));
+        // Prod default: generic JSON — stack trace not leaked
+        assertTrue(res.contains("\"status\":500"));
+        assertTrue(res.contains("application/json"));
     }
 
     @Test
-    void testRoot_returns404_noExceptionTossed() throws Exception {
+    void testRoot_returns404() throws Exception {
         String req = "GET / HTTP/1.1\r\nHost: localhost\r\n\r\n";
         String res = sendRawRequest(req);
         assertTrue(res.startsWith("HTTP/1.1 404 Not Found"));
-        assertTrue(res.contains("No route matched this request."));
+        assertTrue(res.contains("\"status\":404"));
     }
 
     @Test
diff --git a/flash/src/test/java/dev/relism/models/ResponseTest.java b/flash/src/test/java/dev/relism/models/ResponseTest.java
index e12515f..0b14648 100644
--- a/flash/src/test/java/dev/relism/models/ResponseTest.java
+++ b/flash/src/test/java/dev/relism/models/ResponseTest.java
@@ -58,10 +58,23 @@ class ResponseTest {
     }
 
     @Test
-    void setBody_withObjectConvertedToString() {
+    void setBody_withString() {
         Response r = new Response(200, new byte[0], ContentType.TEXT_PLAIN);
-        r.setBody(12345);
-        assertArrayEquals("12345".getBytes(StandardCharsets.UTF_8), r.getBody());
+        r.setBody("hello");
+        assertArrayEquals("hello".getBytes(StandardCharsets.UTF_8), r.getBody());
+    }
+
+    @Test
+    void setBody_withCharSequence() {
+        Response r = new Response(200, new byte[0], ContentType.TEXT_PLAIN);
+        r.setBody(new StringBuilder("hi"));
+        assertArrayEquals("hi".getBytes(StandardCharsets.UTF_8), r.getBody());
+    }
+
+    @Test
+    void setBody_withUnsupportedType_throws() {
+        Response r = new Response(200, new byte[0], ContentType.TEXT_PLAIN);
+        assertThrows(IllegalArgumentException.class, () -> r.setBody(12345));
     }
 
     @Test
diff --git a/flash/src/test/java/dev/relism/routing/AbstractRouterTest.java b/flash/src/test/java/dev/relism/routing/AbstractRouterTest.java
index b2de622..ffdaccc 100644
--- a/flash/src/test/java/dev/relism/routing/AbstractRouterTest.java
+++ b/flash/src/test/java/dev/relism/routing/AbstractRouterTest.java
@@ -1,6 +1,5 @@
 package dev.relism.routing;
 
-import dev.relism.http.ContentType;
 import dev.relism.http.HttpMethod;
 import dev.relism.models.Request;
 import dev.relism.models.RequestHandler;
@@ -52,7 +51,7 @@ class AbstractRouterTest {
     void doRegister_classBasedHandler_addsRoute() {
         DummyRouter router = new DummyRouter();
         ProfileHandler handler = new ProfileHandler();
-        Route ann = ProfileHandler.class.getAnnotation(Route.class);
+        Route ann = Routes.of(ProfileHandler.class);
 
         router.doRegister(ann.method(), ann.path(), handler, new Middleware[0]);
 
diff --git a/pom.xml b/pom.xml
index 206d0a4..e5e605b 100644
--- a/pom.xml
+++ b/pom.xml
@@ -15,6 +15,13 @@
         <module>flash-bench</module>
     </modules>
 
+    <distributionManagement>
+        <repository>
+            <id>Personal</id>
+            <url>https://maven.relism.dev/releases</url>
+        </repository>
+    </distributionManagement>
+
     <properties>
         <maven.compiler.source>21</maven.compiler.source>
         <maven.compiler.target>21</maven.compiler.target>
@@ -68,6 +75,11 @@
                 <artifactId>flash-ext-limiter</artifactId>
                 <version>${project.version}</version>
             </dependency>
+            <dependency>
+                <groupId>dev.relism</groupId>
+                <artifactId>flash-web-bundler</artifactId>
+                <version>${project.version}</version>
+            </dependency>
             <dependency>
                 <groupId>dev.relism</groupId>
                 <artifactId>fpr-core</artifactId>