feat: add runtime interaction guides for Express and H3, update README files

Author: 3m1n3nc3

docs/.vitepress/config.ts

@@ -38,6 +38,8 @@ export default defineConfig({
           { text: 'Getting Started', link: '/guide/getting-started' },
           { text: 'CLI', link: '/guide/cli' },
           { text: 'Database & Modeling', link: '/guide/database-modeling' },
+          { text: 'Express Runtime Interaction', link: '/guide/express-runtime' },
+          { text: 'H3 Runtime Interaction', link: '/guide/h3-runtime' },
           { text: 'API Reference', link: '/api' },
         ]
       },

docs/guide/express-runtime.md

@@ -0,0 +1,95 @@
+# Express Runtime Interaction
+
+This page documents every supported way to interact directly with Arkstack's Express runtime.
+
+## Bootstrap Exports
+
+From `src/core/bootstrap.ts`:
+
+- `expressApp`: raw Express instance
+- `app`: Arkstack `Application` instance
+
+```ts
+import { app, expressApp } from 'src/core/bootstrap';
+```
+
+## Interaction Options
+
+### 1. Raw runtime: `expressApp`
+
+Use this for direct Express APIs.
+
+```ts
+import { expressApp } from 'src/core/bootstrap';
+
+expressApp.set('trust proxy', 1);
+expressApp.disable('x-powered-by');
+expressApp.locals.serviceName = 'api';
+```
+
+### 2. Instance runtime accessor: `app.getAppInstance()`
+
+Get the runtime instance from the Arkstack wrapper.
+
+```ts
+import { app } from 'src/core/bootstrap';
+
+const runtime = app.getAppInstance();
+runtime.use((req, _res, next) => {
+  req.headers['x-runtime'] = 'express';
+  next();
+});
+```
+
+### 3. Static runtime accessor: `Application.getAppInstance()`
+
+Access the static runtime reference.
+
+```ts
+import Application from 'src/core/app';
+
+const runtime = Application.getAppInstance();
+runtime.set('etag', false);
+```
+
+### 4. Driver interaction: `app.getDriver()`
+
+Use the runtime driver for lifecycle-level integration.
+
+```ts
+import { app } from 'src/core/bootstrap';
+
+const driver = app.getDriver();
+const runtime = app.getAppInstance();
+await driver.applyMiddleware(runtime, (req, _res, next) => next());
+```
+
+### 5. Router contract interaction: `app.getRouter()`
+
+Use the framework-agnostic router contract.
+
+```ts
+import { app } from 'src/core/bootstrap';
+
+const router = app.getRouter();
+await router.bind(app.getAppInstance());
+
+const routes = await router.list({ path: '/api' });
+console.log(routes);
+```
+
+### 6. Lifecycle control: `boot` and `shutdown`
+
+```ts
+import { app } from 'src/core/bootstrap';
+
+await app.boot(3000);
+// later
+await app.shutdown();
+```
+
+## Notes
+
+- `app.boot(port)` mounts public assets, binds router, applies middleware, registers error handling, starts the server, and attaches graceful shutdown.
+- 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

@@ -0,0 +1,97 @@
+# H3 Runtime Interaction
+
+This page documents every supported way to interact directly with Arkstack's H3 runtime.
+
+## Bootstrap Exports
+
+From `src/core/bootstrap.ts`:
+
+- `h3App`: raw H3 instance
+- `app`: Arkstack `Application` instance
+
+```ts
+import { app, h3App } from 'src/core/bootstrap';
+```
+
+## Interaction Options
+
+### 1. Raw runtime: `h3App`
+
+Use this for direct H3 APIs.
+
+```ts
+import { h3App } from 'src/core/bootstrap';
+import { HTTPResponse } from 'h3';
+
+h3App.get('/health', () => {
+  return new HTTPResponse('ok');
+});
+```
+
+### 2. Instance runtime accessor: `app.getAppInstance()`
+
+Get the runtime instance from the Arkstack wrapper.
+
+```ts
+import { app } from 'src/core/bootstrap';
+
+const runtime = app.getAppInstance();
+runtime.use((event) => {
+  event.context.source = 'arkstack';
+});
+```
+
+### 3. Static runtime accessor: `Application.getAppInstance()`
+
+Access the static runtime reference.
+
+```ts
+import Application from 'src/core/app';
+
+const runtime = Application.getAppInstance();
+runtime.use(() => {
+  // global middleware hook
+});
+```
+
+### 4. Driver interaction: `app.getDriver()`
+
+Use the runtime driver for lifecycle-level integration.
+
+```ts
+import { app } from 'src/core/bootstrap';
+
+const driver = app.getDriver();
+const runtime = app.getAppInstance();
+await driver.applyMiddleware(runtime, () => {});
+```
+
+### 5. Router contract interaction: `app.getRouter()`
+
+Use the framework-agnostic router contract.
+
+```ts
+import { app } from 'src/core/bootstrap';
+
+const router = app.getRouter();
+await router.bind(app.getAppInstance());
+
+const routes = await router.list({ path: '/api' }, app.getAppInstance());
+console.log(routes);
+```
+
+### 6. Lifecycle control: `boot` and `shutdown`
+
+```ts
+import { app } from 'src/core/bootstrap';
+
+await app.boot(3000);
+// later
+await app.shutdown();
+```
+
+## Notes
+
+- `app.boot(port)` mounts public assets, binds router, applies middleware, starts the server, and attaches graceful shutdown.
+- Use the router contract (`getRouter`) for framework-agnostic behavior where possible.
+- Prefer `h3App` only when you specifically need native H3 APIs.

express/README.md

@@ -1,6 +1,11 @@
 # Arkstack Express.js
 
-Express.js app scaffolded with Tonelix's Arkstack
+Express.js app scaffolded with Toneflix's Arkstack.
+
+Full framework documentations are available from [https://arkstack.toneflix.net](https://arkstack.toneflix.net/).
+
+- Runtime interaction guide: [guide/express-runtime](https://arkstack.toneflix.net/guide/express-runtime)
+- Getting started guide: [guide/getting-started](https://arkstack.toneflix.net/guide/getting-started)
 
 ## Developing
 
@@ -16,13 +21,13 @@ npm install
 npx prisma generate
 ```
 
-### Run Migrations
+### Run migrations
 
 ```sh
 npx prisma migrate dev
 ```
 
-### Start Dev Server
+### Start dev server
 
 ```sh
 npm run dev

express/src/core/bootstrap.ts

@@ -1,4 +1,6 @@
 import Application from 'src/core/app'
 import express from 'express'
 
-export const app = new Application(express())
+export const expressApp = express()
+
+export const app = new Application(expressApp)

express/src/core/router.ts

@@ -33,7 +33,7 @@ export class Router extends ClearRouter {
 
   static async list (_options: ArkstackRouteListOptions = {}) {
     await this.bind()
-    
-return this.allRoutes()
+
+    return this.allRoutes()
   }
 }

h3/README.md

@@ -1,6 +1,11 @@
 # Arkstack H3.js
 
-H3.js app scaffolded with Tonelix's Arkstack
+H3.js app scaffolded with Toneflix's Arkstack.
+
+Full framework documentations are available from [https://arkstack.toneflix.net](https://arkstack.toneflix.net/).
+
+- Runtime interaction guide: [guide/h3-runtime](https://arkstack.toneflix.net/guide/h3-runtime)
+- Getting started guide: [guide/getting-started](https://arkstack.toneflix.net/guide/getting-started)
 
 ## Developing
 
@@ -16,13 +21,13 @@ npm install
 npx prisma generate
 ```
 
-### Run Migrations
+### Run migrations
 
 ```sh
 npx prisma migrate dev
 ```
 
-### Start Dev Server
+### Start dev server
 
 ```sh
 npm run dev

h3/src/core/bootstrap.ts

@@ -2,8 +2,8 @@ import Application from 'src/core/app'
 import ErrorHandler from './utils/request-handlers'
 import { H3 } from 'h3'
 
-export const app = new Application(
-  new H3({
-    onError: ErrorHandler,
-  }),
-) 
+export const h3App = new H3({
+  onError: ErrorHandler,
+})
+
+export const app = new Application(h3App)