create-acrylblends 0.0.0-stage → 0.1.1

package/docs/framework/cordis/acryl-in-a-cordis-app.md

@@ -0,0 +1,146 @@
+# Acryl in a Cordis app
+
+The ACRYL Framework puts its application model inside Cordis. You build an ordinary `Acryl`, register routes and middleware on it, then
+mount that app from a Cordis plugin.
+
+## The mental model
+
+There are two layers:
+
+1. **Application layer** - `Acryl`, handlers, middleware, context, requests, responses, validation and helpers. This is the ACRYL
+   application API.
+2. **Cordis layer** - plugins, services, injection, effects and disposal. This decides when an application exists and which surface can
+   reach it.
+
+A route therefore has two owners. The `Acryl` owns the route table. The plugin that mounted the app owns the mount for as long as its
+Cordis fiber is active.
+
+## A minimal plugin
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import { Acryl } from 'acrylblends'
+
+export const name = 'todo'           // equals the package name and the Loader row id
+export const inject = ['router']     // PENDING until a router exists
+
+export function apply(ctx: Context): void {
+  const app = new Acryl()
+    .get('/', c => c.json({ ok: true }))
+    .get('/todos/:id', c => c.json({ id: c.req.param('id') }))
+
+  ctx.router.route('/todo', app)
+  // Over HTTP only where the Host's adapter exists; the terminal UI and tests have no such service and skip this.
+  ctx.inject(['routerHttp'], inner => { inner.routerHttp.mount('/todo') })
+}
+```
+
+`ctx.router.route('/todo', app)` serves the app below `/todo`:
+
+| Request | Answer |
+| --- | --- |
+| `GET /todo` | `{ "ok": true }` |
+| `GET /todo/todos/42` | `{ "id": "42" }` |
+| `GET /todo/` | 404: `/todo` and `/todo/` are different paths (see below) |
+
+### `/todo/` is a 404 until you choose
+
+`/todo/` is the first thing people type, and by default it is not found: the router treats `/todo` and `/todo/` as two paths. Choose
+one of these, in this order of preference:
+
+- **Redirect in your app** (what `examples/acryl-todo` does): add `trimTrailingSlash()` from `acrylblends/trailing-slash` to the app.
+  A GET or HEAD that would be a 404 and ends in `/` gets a 301 to the same path without it, so `/todo/` reaches the page and every
+  route keeps one canonical path. Other methods are not redirected: `POST /todo/api/` stays a 404.
+
+  ```ts
+  import { trimTrailingSlash } from 'acrylblends/trailing-slash'
+
+  const app = new Acryl()
+    .use(trimTrailingSlash())
+    .get('/', c => c.json({ ok: true }))
+  ```
+
+- **One path everywhere**: the `acryl-router` row's config `trailingSlash: 'ignore'` makes `/a` and `/a/` the same path for every
+  mounted app, with no redirect. It is the app's composition that sets it (the Blueprint or profile that owns the router row), not one
+  plugin, because it changes every other plugin's routes too.
+
+`new Acryl({ strict: false })` does not help once the app is mounted: the router composes every mount into its own root app, and only the
+router's `trailingSlash` setting decides. `strict: false` applies to an `Acryl` you serve yourself (`app.fetch`, `app.request`). Details
+and a measured table: [Routing and mounting](../api/routing.md#trailing-slashes).
+
+The mount belongs to the plugin that made it: `route` registers it as a Cordis effect of the caller, so when the plugin unloads the
+routes disappear, and a reload mounts the app again without duplicating routes. `route` also returns a function that removes the mount
+sooner.
+
+Finish building the app before you mount it: the router copies the app's routes at the `route` call, as the core's own `app.route` does.
+
+## Add middleware
+
+Middleware is registered on the app before the routes it should wrap:
+
+```ts
+const app = new Acryl()
+  .use(async (c, next) => {
+    const started = Date.now()
+    await next()
+    c.header('X-Response-Time', String(Date.now() - started))
+  })
+  .get('/', c => c.json({ ok: true }))
+```
+
+Use middleware for authentication, logging, CORS, compression, request IDs and other behavior that should wrap more than one handler.
+The built-in set is listed in [Middleware](../concepts/middleware.md).
+
+## Run the same app on a surface
+
+The application does not open a socket. A surface supplies requests to it:
+
+- **Web** and **Desktop**: the Host's web server, through `acryl-router-http` (`routerHttp.mount(prefix)`).
+- **Terminal UI**: in process, `await ctx.router.request('/todo/todos/42')`.
+- **Tests**: `await ctx.router.request(...)` through the plugin, or `await app.request(...)` on the app alone.
+- **A standalone process**: `acryl-node-server`, see [Node server](./node-server.md).
+
+## Mount it in a Blend
+
+Add a row to the Blend's `cordis.patch.yml`; the row id is the package name:
+
+```yaml
+- insert:
+    - id: todo
+      name: todo
+```
+
+A Blank app already carries the router, the HTTP adapter, state and the inspector. The reference app is `examples/acryl-todo`; the
+smallest one to copy is `examples/acryl-framework-starter`.
+
+## Test it without a socket
+
+```ts
+import { Context } from '@deepseek-ai/cordis'
+import * as router from 'acryl-router'
+import * as todo from '../src/index.ts'
+
+const ctx = new Context()
+ctx.plugin(router)
+ctx.plugin(todo)
+await new Promise(resolve => setTimeout(resolve, 0))   // let both plugins activate
+const response = await ctx.router.request('/todo/todos/42')
+expect(await response.json()).toEqual({ id: '42' })
+```
+
+## Package map
+
+| Package | Responsibility |
+| --- | --- |
+| `acryl-router` | the application API and the Cordis `router` service |
+| `acryl-router-http` | serving router prefixes on the ACRYL Host's web server |
+| `acryl-node-server` | serving the whole router from a standalone Node.js process |
+| `acryl-state` | shared application state across surfaces |
+| `acryl-inspect` | runtime inspection of mounts, routes and plugins |
+
+## Next
+
+- [Core concepts](./concepts.md)
+- [Routing and mounting](../api/routing.md)
+- [Context](../api/context.md)
+- [Plugin lifecycle and disposal](./plugin-lifecycle.md)

package/docs/framework/cordis/concepts.md

@@ -0,0 +1,105 @@
+# Core concepts
+
+The framework's request-handling model is designed so every extension point belongs to a Cordis plugin. This page explains the pieces
+before the API reference.
+
+## Acryl
+
+An `Acryl` is a self-contained ACRYL application. It owns:
+
+- routes;
+- middleware;
+- an error handler (`app.onError`);
+- a request entry point (`app.fetch`, and `app.request` for tests);
+- sub-applications placed below a path with `app.route(path, sub)`.
+
+An app can be tested without a server:
+
+```ts
+const response = await app.request('/todos/42')
+```
+
+An app is not itself a Cordis service. That separation lets the same app be mounted by different hosts, at different paths, or not
+mounted at all.
+
+## Router service
+
+The Cordis `router` service (`ctx.router`, provided by `acryl-router`) composes the mounted apps into one route space. A plugin builds an
+app and mounts it:
+
+```ts
+ctx.router.route('/todo', app)
+```
+
+The mount copies the app's routes at that call. When any mount is added or removed, the next request composes a fresh app from the mounts
+that are live, in the order they were made; requests already running keep the app they started with. This matches Cordis: plugins can
+load, unload, reload and be replaced while the host stays up. The core's route tables are add-only, so rebuilding is the only correct way
+to remove a route; it costs about 1 ms per 1000 routes, once per change.
+
+The router also takes one router-wide `onError` and one `notFound` (each owned by the plugin that set it), and runs requests in process:
+`ctx.router.fetch(request, connection?)` and `ctx.router.request(path, init?, connection?)`.
+
+## Handler
+
+A handler receives one context object, conventionally named `c`:
+
+```ts
+app.get('/todos/:id', c => {
+  return c.json({ id: c.req.param('id') })
+})
+```
+
+Handlers return a Web `Response`, either directly or through context helpers such as `c.text`, `c.json` and `c.html`.
+
+## Middleware
+
+Middleware wraps handlers and other middleware:
+
+```ts
+app.use('/admin/*', async (c, next) => {
+  if (!isAllowed(c)) return c.text('Forbidden', 403)
+  await next()
+})
+```
+
+Code before `await next()` runs on the way in. Code after it can inspect or change the response (`c.res`) on the way out.
+
+## Surface
+
+A surface is the place a person or another program uses the application:
+
+| Surface | Transport |
+| --- | --- |
+| Web | the ACRYL Host's web server, through `acryl-router-http` |
+| Desktop | the same: the Electron window talks to the app's own loopback web server |
+| Terminal UI | in process: `ctx.router.request(...)`, no server |
+| A standalone process | `acryl-node-server` serves the whole router |
+| Tests | `ctx.router.request(...)` or `app.request(...)` |
+
+Surfaces share capabilities and contracts. They do not need to share a transport or a user interface.
+
+## Plugin contract
+
+Following the ACRYL framework rules, a plugin declares what it:
+
+- provides as services;
+- requires through injection;
+- registers as routes, commands, tools or interface slots;
+- owns until disposal.
+
+The declaration is what lets tooling answer two questions without reading all the code: what does this plugin do, and what disappears
+when it unloads? `acryl-inspect` reads it from the running system: each mount is labeled with its path and has one labeled child per route it serves.
+
+## State
+
+Request state belongs to the context. Application state shared between surfaces belongs in `acryl-state` or an application-owned Cordis
+service. Do not hide shared mutable state in module globals: Cordis can reload plugins and run several surfaces from one host, and a
+module global outlives the plugin that wrote it.
+
+## Design rules
+
+1. Everything extensible is a Cordis plugin.
+2. One application can serve several surfaces.
+3. Each plugin has one declared contract.
+4. Every registration is reversible.
+5. Normal application code should not need runtime internals.

package/docs/framework/cordis/middleware.md

@@ -0,0 +1,8 @@
+# Middleware in Cordis
+
+Middleware belongs to an `Acryl`; it is not a separate Cordis registration, and it disappears with the mount that serves it. A plugin may
+build middleware from an injected service, but resources the middleware uses (timers, watchers, connections) are acquired in the plugin's
+`ctx.effect()` and only the finished middleware goes into the app. Do not start timers, watchers or sockets from a handler.
+
+Middleware an app registers with a path wraps the matching routes of every later mount too (an app mounted at `/` with
+`app.use('/todo/*', ...)` wraps a plugin mounted at `/todo`), so a host can put a guard in front of other plugins by mounting first.

package/docs/framework/cordis/migration-from-0-3.md

@@ -0,0 +1,111 @@
+# Migration from 0.3
+
+0.3.0 had the framework's own small router API: routes registered one at a time on `ctx.router`, and a `RouteContext` with a few
+helpers. 0.4.0 replaces it with the ported application API: a plugin builds an `Acryl` and mounts it. The old calls are removed, not kept
+as aliases, so there is one way to write a route.
+
+## Before and after
+
+0.3.0:
+
+```ts no-check
+import { HttpError } from 'acrylblends'
+import { readJson, valid, validate } from 'acrylblends'
+import { streamSSE } from 'acrylblends/streaming'
+import { bodyLimit } from 'acrylblends/body-limit'
+
+export function apply(ctx: Context): void {
+  const api = ctx.router.group('/todo')
+  api.use(bodyLimit({ maxBytes: 16 * 1024 }))
+  api.get('/todos/:id', c => {
+    const todo = find(c.param('id'))
+    if (!todo) throw new HttpError(404, { message: 'no such todo' })
+    return c.json(todo)
+  })
+  api.post('/todos', validate('json', NewTodo), c => c.json(create(valid(c, 'json')), 201))
+  api.get('/events', c => streamSSE(c, stream => {
+    const off = events.on('change', todo => stream.send(todo, { event: 'change' }))
+    return off
+  }))
+  ctx.inject(['routerHttp'], inner => { inner.routerHttp.mount('/todo') })
+}
+```
+
+0.4.0:
+
+```ts
+import { Acryl } from 'acrylblends'
+import { HTTPException } from 'acrylblends/http-exception'
+import { schemaValidator } from 'acrylblends/schema-validator'
+import { streamSSE } from 'acrylblends/streaming'
+import { bodyLimit } from 'acrylblends/body-limit'
+
+export function apply(ctx: Context): void {
+  const app = new Acryl()
+    .use(bodyLimit({ maxSize: 16 * 1024 }))
+    .get('/todos/:id', c => {
+      const todo = find(c.req.param('id'))
+      if (!todo) throw new HTTPException(404, { message: 'no such todo' })
+      return c.json(todo)
+    })
+    .post('/todos', schemaValidator('json', NewTodo), c => c.json(create(c.req.valid('json')), 201))
+    .get('/events', c => streamSSE(c, async stream => {
+      const off = events.on('change', todo => { void stream.writeSSE({ event: 'change', data: JSON.stringify(todo) }) })
+      stream.onAbort(off)
+      while (!stream.aborted) await stream.sleep(15_000).then(() => stream.write(': keep-alive\n\n'))
+    }))
+
+  ctx.router.route('/todo', app)
+  ctx.inject(['routerHttp'], inner => { inner.routerHttp.mount('/todo') })
+}
+```
+
+Public paths do not change: the mount path plus the app's route path is the old group prefix plus the old route path.
+
+## What maps to what
+
+| 0.3.0 | 0.4.0 |
+| --- | --- |
+| `ctx.router.get/post/put/patch/delete/all/on(path, ...)` | the same methods on an `Acryl`, then `ctx.router.route(prefix, app)` |
+| `ctx.router.use(...)` | `app.use(...)` on the app it should wrap (or on an app mounted earlier, for a guard in front of other plugins) |
+| `ctx.router.group(prefix, ...middleware)` | one `Acryl` per group mounted at `prefix`, or `app.route(prefix, sub)` / `app.basePath(prefix)` |
+| the remover each registration returned | the one remover `ctx.router.route` returns; the mount is owned by the calling plugin as before |
+| `ctx.router.onError`, `ctx.router.notFound` | unchanged; an app's own `app.onError` now also applies to its routes |
+| `c.param(name)`, `c.params` | `c.req.param(name)`, `c.req.param()` |
+| `c.query(name)`, `c.query()` | `c.req.query(name)`, `c.req.query()` (and `c.req.queries(name)` for repeated values) |
+| `c.url` | `new URL(c.req.url)`, or `c.req.path` |
+| `c.req` (the Web `Request`) | `c.req.raw`; `c.req` is now the request wrapper |
+| `c.connection` | `connectionOf(c)` (or `getConnInfo(c)`); type the app `new Acryl<RouterEnv>()` to read `c.env.connection` |
+| `c.signal` | `c.req.raw.signal` |
+| `c.waitUntil(task)` | `c.executionCtx.waitUntil(task)` |
+| `c.get(key)` / `c.set(key, value)` | unchanged, typed by the app's `Variables` (`c.var.key` also works) |
+| `c.json/text/html/body/redirect/notFound/header/status` | unchanged |
+| `HttpError(status, { message, response, cause })` | `HTTPException(status, { message, res, cause })` |
+| `readJson(c)`, `readText(c)`, `readBytes(c)` with `{ maxBytes }` | `bodyLimit({ maxSize })` in front, then `c.req.json()`, `c.req.text()`, `c.req.arrayBuffer()` |
+| `bodyLimit({ maxBytes })` | `bodyLimit({ maxSize })` |
+| `validate(target, schema)` and `valid(c, target)` | `schemaValidator(target, schema)` and `c.req.valid(target)`, with more targets (`form`, `header`, `cookie`) |
+| `streamSSE(c, stream => cleanup)` with `stream.send(data, { event, id })` | `streamSSE(c, async stream => ...)` with `stream.writeSSE({ data, event, id })`; `data` is a string, so `JSON.stringify` objects |
+| the SSE stream's automatic keep-alive comment | none: write a comment on a timer when a proxy closes idle connections |
+| the cleanup function `run` returned | `stream.onAbort(cleanup)`; the callback's end closes the stream |
+| a 405 with `Allow` for a known path and another method | 404 by default; add the `methodNotAllowed` middleware for 405 |
+| the `Middleware` type, `(c, next) => Response` | `MiddlewareHandler`, `async (c, next) => { await next() }`; change `c.res` after `next()` instead of returning it |
+| `logger`, `cors`, `requestId`, `secureHeaders`, `loopbackOnly` | same names, each from its own subpath (`acrylblends/logger`, `acrylblends/cors`, ...); the first four now take the core's options |
+
+## Behavior changes to check
+
+- **A mount is a snapshot.** Routes an app registers after `ctx.router.route(...)` are not served. 0.3.0 registered each call live.
+- **A JSON validator needs a JSON `Content-Type`.** Without it the schema sees `{}`. 0.3.0 read the body whatever its type.
+- **`await next()` does not throw.** A thrown error has already become a response; read it from `c.error`.
+- **Trailing slashes are strict by default, as before**, and `trailingSlash: 'ignore'` still treats `/a` and `/a/` as one path.
+- **Disposal is unchanged:** a plugin's unload ends the requests and streams its code is serving, and router disposal ends all of them,
+  bounded by `disposeGraceMs`.
+
+## Checklist
+
+For each plugin:
+
+- collect its route registrations into one app per mount path and keep the public paths;
+- move middleware and error handling onto the owning app;
+- replace the context and helper calls from the table above;
+- run its route tests, then one activation test that unloads and reloads the plugin;
+- leave no 0.3.0-style calls behind: the old API is gone, and two styles would give new code a second API to copy.

package/docs/framework/cordis/migration-from-0-4.md

@@ -0,0 +1,14 @@
+# Migration from 0.4
+
+0.5 gives the framework its public names: the application class is `Acryl` and the request class is `AcrylRequest`, the upstream names
+with the project renamed. Everything else (`Context`, `HTTPException`, the middleware, the helpers, `ctx.router.route(path, app)`) is
+unchanged.
+
+| 0.4 | 0.5 |
+| --- | --- |
+| `import { App } from 'acryl-router'`, `new App()` | `import { Acryl } from 'acryl-router'`, `new Acryl()` |
+| `AppRequest` | `AcrylRequest` |
+
+`App` and `AppRequest` still work in 0.5, marked deprecated, and are removed in the next release. Code outside Cordis imports the same
+names from the public package: `import { Acryl } from 'acrylblends'`, and each upstream subpath under it (`acrylblends/cors`,
+`acrylblends/jwt`, `acrylblends/node-server`).

package/docs/framework/cordis/migration-from-dsh-webserver.md

@@ -0,0 +1,109 @@
+# Migration from the DSH webServer
+
+ACRYL plugins have registered HTTP routes directly with the DSH `webServer` (or the Host's `acrylWeb` wrapper of it): one Node-style handler
+per exact path or prefix, with no middleware chain. The framework replaces that with an `Acryl`, a mount, and Web-standard requests.
+
+## Before and after
+
+Before, a plugin claims a path and writes the Node response itself:
+
+```ts
+export function apply(ctx: Context): void {
+  ctx.effect(() => ctx.acrylWeb.register({
+    kind: 'exact',
+    path: '/api/health',
+    handler: (req, res) => {
+      res.statusCode = 200
+      res.setHeader('content-type', 'application/json')
+      res.end(JSON.stringify({ ok: true }))
+    },
+  }))
+}
+```
+
+After, it builds an app, mounts it, and asks the Host adapter to serve the prefix:
+
+```ts
+import { Acryl } from 'acrylblends'
+
+export const inject = ['router']
+
+export function apply(ctx: Context): void {
+  const app = new Acryl().get('/health', c => c.json({ ok: true }))
+  ctx.router.route('/api', app)
+  ctx.inject(['routerHttp'], inner => { inner.routerHttp.mount('/api/health') })
+}
+```
+
+`routerHttp.mount(prefix)` claims the prefix on the same web server, so the public path does not change. The terminal UI and tests reach
+the route in process (`ctx.router.request('/api/health')`), which the old handler never allowed.
+
+## What maps to what
+
+| webServer | Framework |
+| --- | --- |
+| `register({ kind: 'exact', path, handler })` | a route on an `Acryl`, mounted with `ctx.router.route`; served with `routerHttp.mount(path)` |
+| `register({ kind: 'prefix', path, handler })` | an `Acryl` mounted at `path` with its own routes below it |
+| `req.method` checks in the handler | `app.get`, `app.post`, ... (add `methodNotAllowed` for 405 answers) |
+| `new URL(req.url, ...)` and manual parsing | `c.req.param`, `c.req.query`, `c.req.header` |
+| reading the body stream by hand | `c.req.json()`, `c.req.parseBody()` behind `bodyLimit`, or a validator |
+| `res.statusCode`, `res.setHeader`, `res.end` | `c.json`, `c.text`, `c.body`, `c.header`, or a returned `Response` |
+| `req.socket.remoteAddress` | `connectionOf(c)` / `getConnInfo(c)` |
+| a peer or origin check copied into each handler | `loopbackOnly`, `cors`, `csrf` or a middleware of your own |
+| the disposer returned by `register` | nothing: `route` and `mount` belong to the calling plugin |
+
+## Migration steps
+
+Move one capability at a time:
+
+1. Build an `Acryl` for the capability and move its handlers into it without changing their public answers.
+2. Mount it with `ctx.router.route` and serve the same prefix with `routerHttp.mount`.
+3. Remove the direct `webServer` registration in the same change: the two cannot claim one prefix, `mount` throws.
+4. Test the route through the router (`ctx.router.request`) and over the Host, and unload and reload the plugin to confirm the route goes
+   away and comes back once.
+
+Keep domain calls unchanged until the transport change is green; do not rewrite transport, handlers and authorization in one step.
+
+## A worked example: the workspace
+
+`acryl-workspace` (files, git, terminals, projects, agents) was the largest user of the webServer: 24 exact routes. It now builds one app
+per domain folder (`filesRoutes`, `gitRoutes`, `ptyRoutes`, ...), composes them once (`privateApi` in `src/private-route.ts`), mounts the
+result after the effect that builds its services, and serves the one prefix `/api/acryl-workspace`:
+
+```ts
+const built: { api?: Acryl } = {}
+ctx.effect(() => {
+  // ... the PTY table, git, files, the project registry ...
+  built.api = privateApi(filesRoutes(files, report), gitRoutes(git, report) /* , ... */)
+  return async () => { /* release them */ }
+})
+ctx.router.route('/', built.api)
+ctx.routerHttp.mount('/api/acryl-workspace')
+```
+
+Mounting after the effect orders the unload: the mount goes first, so the requests and event streams its code is serving end and are
+waited for, then the services are released. Each route names its guard (`loopbackOnly({ callers: 'own-page' })` for the page, a bearer token
+for the agent hooks) and its body limit; the event stream is `streamSSE`, and its keep-alive is one timer the plugin owns, not one per
+request. The terminal's WebSocket stays a webServer upgrade until the router carries upgrades (spec 047 T009).
+
+The answers that changed are recorded with it: a body over a route's limit is 413 on every route (some said 400); a wrong method is 405 with
+an `Allow` header on every route; a missing or wrong agent-hook token is 401 with `WWW-Authenticate` (it was 403); and the hook's `Host`
+must be the app's own loopback address. Its routes refuse an in-process call on purpose (the guard needs a socket to check), so its tests
+run over loopback through the same adapter (`tests/serve-api.ts`), which is the "test over the Host" below.
+
+`acryl-agent-control` (the door `acryl control`, workers and the MCP config use) moved the same way and kept its trust model exactly:
+operator routes still answer a non-loopback peer or a missing or wrong secret with 403 `{ "error": "forbidden" }`, which `acryl control`
+reads as "refused", never the bearer middleware's 401. What changed there: an oversized body is 413 (was 400), a wrong method's `Allow`
+lists what the router serves (`GET, HEAD` for the audit log), and a page route's refusal carries `loopbackOnly`'s message instead of
+`forbidden`. Only the page channel's WebSocket stays a webServer upgrade.
+
+## Completion check
+
+A capability is migrated when:
+
+- no handler in it touches Node `req` / `res` objects or the old server types;
+- its public paths and answers are unchanged, or the changes are recorded;
+- it unloads and reloads without duplicate or missing routes;
+- the same handler passes an in-process test and a test over the Host.
+
+Typed RPC stays a separate concern. Do not convert RPC methods because their names look like HTTP routes.

package/docs/framework/cordis/mounting.md

@@ -0,0 +1,85 @@
+# Mounting and trailing slashes
+
+How a Cordis plugin serves an `Acryl` app, what happens to errors and unknown paths, and how trailing slashes behave. For routing itself (methods, parameters, wildcards, grouping) see the [routing API](../api/routing.md).
+
+## Mounting from Cordis
+
+A plugin mounts its app through the `router` service:
+
+```ts
+export const name = 'todo'
+export const inject = ['router']
+
+export function apply(ctx: Context): void {
+  const app = createTodoApp()
+  ctx.router.route('/todo', app)
+  ctx.inject(['routerHttp'], inner => { inner.routerHttp.mount('/todo') })
+}
+```
+
+- The mount is owned by the calling plugin: `route` registers it as that plugin's effect, so unloading the plugin removes it and a reload
+  mounts again without duplicates. The returned function removes it sooner.
+- `route` copies the app's routes at the call, like `app.route`; mount the app once it is complete.
+- Mounts run in the order they were made, so middleware an earlier mount registers for a path (`app.use('/todo/*', ...)` mounted at `/`)
+  wraps routes a later mount serves below it. Two plugins may mount on the same path: the first one's matching route answers, and when it
+  unloads the second takes over.
+- `ctx.router.route` is the only way to register with the router.
+- To be reachable over HTTP inside the ACRYL Host, ask the adapter to serve the prefix with `routerHttp.mount(prefix)` (an optional
+  dependency, hence the inner `ctx.inject`). A standalone `acryl-node-server` serves the whole router, so there the call is not needed.
+
+## Not found and errors
+
+An app's own error handler applies to that app's routes, also when the app is mounted:
+
+```ts
+app.onError((error, c) => {
+  console.error(error)
+  return c.json({ error: 'internal_error' }, 500)
+})
+```
+
+A mounted app's `app.notFound` is not used: a request no mount claims is answered by the router. A plugin can replace that answer, and
+the router's fallback error handler, once per router:
+
+```ts
+ctx.router.notFound(c => c.json({ error: 'not_found' }, 404))
+ctx.router.onError((error, c) => c.json({ error: 'internal_error' }, 500))
+```
+
+Without them, an `HTTPException` becomes its own response, an aborted request is a 499 and anything else is logged and becomes a 500.
+Return client errors from the handler that detected them (or throw an `HTTPException`); reserve `onError` for unexpected failures.
+
+## Trailing slashes
+
+`/a` and `/a/` are different paths by default. That surprises people most on a mount's root: an app mounted at `/orders` with a route
+`/` answers `/orders` and returns 404 on `/orders/`.
+
+What each choice does for an app mounted at `/orders` with routes `/` and `/:id`, measured on the router:
+
+| Choice | `/orders` | `/orders/` | `/orders/42` | `/orders/42/` |
+| --- | --- | --- | --- | --- |
+| nothing (the default) | 200 | 404 | 200 | 404 |
+| `.use(trimTrailingSlash())` in the app | 200 | 301 to `/orders` | 200 | 301 to `/orders/42` |
+| `acryl-router` row config `trailingSlash: 'ignore'` | 200 | 200 | 200 | 200 |
+| `new Acryl({ strict: false })` for the mounted app | 200 | 404 | 200 | 404 |
+
+- **`trimTrailingSlash()`** (from `acrylblends/trailing-slash`) is the choice a plugin makes for itself. It acts after the handlers: only
+  a GET or HEAD that would be a 404 and ends in `/` is redirected, so a path you did register with a trailing slash keeps working, and a
+  POST, PUT, PATCH or DELETE to `/orders/` stays a 404. `trimTrailingSlash({ alwaysRedirect: true })` redirects before the handlers run,
+  which a wildcard route (`/files/*`) needs. `appendTrailingSlash()` does the opposite, for an app whose canonical paths end in `/`.
+- **`trailingSlash: 'ignore'`** is the router's own setting and applies to every mount at once, without a redirect. Set it in the
+  composition that owns the `acryl-router` row (the Blueprint or profile), not from one plugin.
+- **`strict: false`** on an `Acryl` is the core's option and works for an app you serve yourself (`app.fetch`, `app.request`). It has no
+  effect on a mounted app, because the router composes all mounts into one root app whose strictness comes from `trailingSlash`.
+
+`examples/acryl-todo` uses `trimTrailingSlash()`: `/todo/` sends the browser to `/todo`, and the API keeps one path per route.
+
+## Testing routes
+
+```ts
+const response = await app.request('/todos/42')
+const body = await response.json()
+```
+
+Test both the application in isolation and at least one mounted route through the Cordis router. The second test proves the mount,
+prefix and disposal contract, not just handler logic.

package/docs/framework/cordis/node-server.md

@@ -0,0 +1,75 @@
+# Node server
+
+`acryl-node-server` serves the whole router over HTTP from a standalone Node.js process. Use it for an app that runs without the ACRYL
+Host. Inside the Host (Web and Desktop), the Host owns the web server and a plugin asks `acryl-router-http` to serve its prefix instead.
+
+## Serve the router
+
+The server is a Cordis plugin that provides the `nodeServer` service:
+
+```ts
+import { Context } from '@deepseek-ai/cordis'
+import * as router from 'acryl-router'
+import * as nodeServer from 'acrylblends/node-server'
+import * as todo from './todo.ts'
+
+const root = new Context()
+root.plugin(router)
+root.plugin(nodeServer, { port: 3000 })
+root.plugin(todo)
+
+root.inject(['nodeServer'], ctx => {
+  console.log(`listening on ${ctx.nodeServer.url}`)
+})
+```
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `hostname` | `127.0.0.1` | address to bind; binding elsewhere exposes the app to the network |
+| `port` | `0` | port to listen on; 0 lets the system choose |
+| `scan` | `20` | how many further ports to try when the configured one is taken |
+
+The plugin becomes active once the server listens, so a plugin that injects `nodeServer` can rely on `ctx.nodeServer.url` and
+`ctx.nodeServer.port`. A failure to bind fails the plugin.
+
+Every request goes to `ctx.router.fetch`, so routes appear and disappear as plugins mount and unload, with no restart. A plugin's
+`ctx.inject(['routerHttp'], ...)` call never fires here: this adapter serves every prefix already.
+
+## Connection information
+
+The adapter passes the socket's peer address and local port to the router as connection facts. Handlers read them through
+`connectionOf(c)` or `getConnInfo(c)` and never touch Node socket objects, so the same handler runs in process and through the Host. See
+[Context](../api/context.md#transport-facts).
+
+## Static files
+
+The Node `serveStatic` reads files from disk:
+
+```ts
+import { serveStatic } from 'acrylblends/node-server'
+
+const app = new Acryl()
+  .use('/assets/*', serveStatic({ root: './public' }))
+  .get('/', serveStatic({ path: './public/index.html' }))
+```
+
+`root` is joined with the request path, relative to the working directory unless absolute. A request path with a `.` or `..` segment, a
+doubled slash, a backslash or (unless `allowPercentInPath`) an encoded `%` is treated as not found and passed on with `next()`. Only `GET`
+and `HEAD` are served. Other options: `rewriteRequestPath`, `precompressed` (serve a `.br`, `.zst` or `.gz` sibling when the client
+accepts it), `index` (default `index.html`), and `onFound` / `onNotFound` hooks. Serve build output, never source folders.
+
+## Shutdown
+
+Disposing the plugin (or the root context) ends open streams, closes every connection and returns once the port is free. Disposing a
+plugin that only mounted routes is different: its mount and the requests it is serving end, and the server keeps serving the others (see
+[Plugin lifecycle](./plugin-lifecycle.md#disposal-sequence)).
+
+## Choosing a port
+
+Let the process configuration choose the address. Do not hard-code a development port in a reusable plugin: a plugin mounts routes and
+leaves the socket to whichever adapter the app runs with.
+
+## Not yet supported
+
+WebSocket upgrades under the router are a later task. The adapter's own WebSocket support exists in `src/adapter/` with its tests but is
+not wired to the router yet.