feat(docs): add static asset mounting section for Express and H3 runtimes

Author: 3m1n3nc3

docs/guide/express-runtime.md

@@ -88,9 +88,43 @@ await app.boot(3000);
 await app.shutdown();
 ```
 
+## Static Assets
+
+Express mounts the `public` directory automatically during `app.boot(port)` through the runtime driver.
+
+Default behavior:
+
+- serves files from `path.join(process.cwd(), 'public')`
+- applies `Cache-Control: public, max-age=31536000, immutable`
+- adds permissive CORS headers for static responses
+
+If you need different static asset behavior, override `mountPublicAssets` in `src/core/app.ts` when constructing `ExpressDriver`.
+
+```ts
+import express from 'express';
+import path from 'path';
+import { ExpressDriver } from '@arkstack/driver-express';
+
+this.driver = new ExpressDriver({
+  bindRouter: async (runtime) => {
+    runtime.use(await Router.bind());
+  },
+  mountPublicAssets: (runtime, publicPath) => {
+    runtime.use(
+      '/assets',
+      express.static(path.resolve(publicPath), {
+        maxAge: '7d',
+      }),
+    );
+  },
+  errorHandler: ErrorHandler,
+});
+```
+
 ## Notes
 
 - `app.boot(port)` mounts public assets, binds router, applies middleware, registers error handling, starts the server, and attaches graceful shutdown.
+- Static asset mounting happens before configured middleware is applied.
 - For middleware layering and recommended usage, see [Middleware Guide](/guide/middleware).
 - Use the router contract (`getRouter`) for framework-agnostic behavior where possible.
 - Prefer `expressApp` only when you specifically need native Express APIs.

docs/guide/h3-runtime.md

@@ -90,9 +90,38 @@ await app.boot(3000);
 await app.shutdown();
 ```
 
+## Static Assets
+
+H3 mounts the `public` directory automatically during `app.boot(port)` through `H3Driver`.
+
+Default behavior:
+
+- serves files from `process.cwd()/public`
+- only handles requests that look like asset paths
+- blocks dotfiles and path traversal attempts
+- applies long-lived cache headers and permissive CORS headers
+
+If you need to change that behavior, override `mountPublicAssets` in `src/core/app.ts` when constructing `H3Driver`.
+
+```ts
+import { H3Driver } from '@arkstack/driver-h3';
+import { staticAssetHandler } from '@arkstack/driver-h3/middlewares';
+
+this.driver = new H3Driver({
+  createApp: () => new H3({ onError: ErrorHandler }),
+  bindRouter: async (runtime) => {
+    await Router.bind(runtime);
+  },
+  mountPublicAssets: (runtime, publicPath) => {
+    runtime.use(staticAssetHandler(publicPath));
+  },
+});
+```
+
 ## Notes
 
 - `app.boot(port)` mounts public assets, binds router, applies middleware, starts the server, and attaches graceful shutdown.
+- Static asset mounting happens before configured middleware is applied.
 - For middleware layering and recommended usage, see [Middleware Guide](/guide/middleware).
 - Use the router contract (`getRouter`) for framework-agnostic behavior where possible.
 - Prefer `h3App` only when you specifically need native H3 APIs.

docs/guide/middleware.md

@@ -27,6 +27,45 @@ Arkstack applies middleware in this order during `app.boot(port)`:
 5. `after` middleware runs.
 6. Runtime-specific startup continues (Express error handler registration, then server start).
 
+## Static asset mounting
+
+Static assets are mounted by the runtime driver before configured middleware runs.
+
+Default locations:
+
+- Express: `path.join(process.cwd(), 'public')`
+- H3: `process.cwd()/public`
+
+Use this default behavior when your app only needs a conventional `public` directory. If you need a different mount path, cache policy, or asset strategy, override `mountPublicAssets` when constructing the driver in `src/core/app.ts`.
+
+Express example:
+
+```ts
+this.driver = new ExpressDriver({
+  bindRouter: async (runtime) => {
+    runtime.use(await Router.bind());
+  },
+  mountPublicAssets: (runtime, publicPath) => {
+    runtime.use('/assets', express.static(publicPath));
+  },
+  errorHandler: ErrorHandler,
+});
+```
+
+H3 example:
+
+```ts
+this.driver = new H3Driver({
+  createApp: () => new H3({ onError: ErrorHandler }),
+  bindRouter: async (runtime) => {
+    await Router.bind(runtime);
+  },
+  mountPublicAssets: (runtime, publicPath) => {
+    runtime.use(staticAssetHandler(publicPath));
+  },
+});
+```
+
 Use each group with this intent:
 
 - `global`: middleware that should always run for every request (body parsing, CORS, method override, baseline security headers).