acrylblends 0.4.0 → 0.4.1

package/docs/framework/context.md

@@ -0,0 +1,129 @@
+# Context
+
+Every handler and middleware receives a context, normally named `c`. The context connects the current request, the response being built,
+route data, transport information and work that must finish after the response. It lives for one request.
+
+## Return a response
+
+```ts
+app.get('/text', c => c.text('Hello'))
+app.get('/json', c => c.json({ ok: true }))
+app.get('/html', c => c.html('<h1>Hello</h1>'))
+app.get('/empty', c => c.body(null, 204))
+app.get('/raw', () => new Response('Good morning!'))
+app.get('/notfound', c => c.notFound())
+app.get('/redirect', c => c.redirect('/'))              // 302
+app.get('/moved', c => c.redirect('/', 301))
+```
+
+Set the status and headers before or with the body:
+
+```ts
+app.post('/posts', c => {
+  c.status(201)
+  c.header('X-Message', 'created')
+  return c.json({ created: true })
+})
+
+app.get('/welcome', c => c.body('Thank you for coming', 201, { 'X-Message': 'Hello!', 'Content-Type': 'text/plain' }))
+```
+
+## The response on the way out
+
+Middleware can read or replace the response after `next()`:
+
+```ts
+app.use(async (c, next) => {
+  await next()
+  c.res.headers.append('X-Debug', 'Debug message')
+})
+```
+
+## Read request data
+
+The request object is `c.req`:
+
+```ts
+const id = c.req.param('id')
+const search = c.req.query('q')
+const agent = c.req.header('User-Agent')
+```
+
+See [Request](./request.md) for bodies, repeated values and validated input.
+
+## Store request-local values
+
+`c.set` and `c.get` (or `c.var.name`) pass data from middleware to handlers. Declare the variables as the app's type parameter so both
+sides agree:
+
+```ts
+const app = new App<{ Variables: { requestId: string } }>()
+
+app.use(async (c, next) => {
+  c.set('requestId', crypto.randomUUID())
+  await next()
+})
+
+app.get('/', c => c.text(c.get('requestId')))
+```
+
+These values live only for the current request. Do not use them as a cache or as application state. `createMiddleware` (from
+`acryl-router/helpers`) types a middleware that sets variables, and chained `.use(...)` calls accumulate their types; see
+[Middleware](./middleware.md).
+
+## Transport facts
+
+`c.env` carries what the caller of the router supplied for this request. Under the router that is `{ connection }`: the socket's peer
+address and the real local port, filled by the HTTP adapter and empty for an in-process call. Transport facts never travel in headers.
+
+```ts
+import { App, connectionOf, type RouterEnv } from 'acryl-router'
+import { getConnInfo } from 'acryl-router/helpers'
+
+const app = new App<RouterEnv>()   // types c.env.connection
+app.get('/peer', c => c.json({
+  connection: connectionOf(c),     // { remoteAddress?, localPort? }
+  info: getConnInfo(c),            // the same peer in the core's conninfo shape, for middleware such as ipRestriction
+}))
+```
+
+The same handler then runs over HTTP, in process or in a test, and reads an empty connection where there is no socket. Guards such as
+`loopbackOnly` refuse an empty one unless told otherwise.
+
+## Cancellation and background work
+
+- `c.req.raw.signal` aborts when the caller goes away, when the plugin whose code is serving the request unloads, and when the router is
+  disposed. Long work
+  should pass it on (`fetch(url, { signal: c.req.raw.signal })`) or check it.
+- `c.executionCtx.waitUntil(promise)` keeps the request in flight until the promise settles, for work that continues after the response
+  is returned.
+
+Both belong to the current request, and both end with their owner: see [Plugin lifecycle](./plugin-lifecycle.md#disposal-sequence).
+
+## Errors and control flow
+
+Return a response for expected failures, or throw an `HTTPException`, which becomes its own response:
+
+```ts
+import { HTTPException } from 'acryl-router'
+
+if (!todo) return c.json({ error: 'todo_not_found' }, 404)
+if (!allowed) throw new HTTPException(403, { message: 'not yours' })
+```
+
+Anything else that is thrown goes to the app's `onError`, or to the router's when the app has none. A middleware's `await next()` never
+throws: the error has already become a response by then, and the error itself is in `c.error`:
+
+```ts
+app.use(async (c, next) => {
+  await next()
+  if (c.error) report(c.error)
+})
+```
+
+## Context rules
+
+- Treat the context as request-local.
+- Do not retain it after the handler returns.
+- Do not put sockets, server objects or Cordis internals into context values for other plugins to discover accidentally.
+- Put cross-plugin capabilities in a declared Cordis service, not in `c.set`.

package/docs/framework/getting-started.md

@@ -0,0 +1,146 @@
+# Getting started
+
+The ACRYL Framework puts its application model inside Cordis. You build an ordinary `App`, register routes and middleware on it, then
+mount that app from a Cordis plugin.
+
+## The mental model
+
+There are two layers:
+
+1. **Application layer** - `App`, 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 `App` 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 { App } from 'acryl-router'
+
+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 App()
+    .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 `acryl-router/middleware` 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 'acryl-router/middleware'
+
+  const app = new App()
+    .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 App({ 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 `App` you serve yourself (`app.fetch`, `app.request`). Details
+and a measured table: [Routing and mounting](./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 App()
+  .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](./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](./routing.md)
+- [Context](./context.md)
+- [Plugin lifecycle and disposal](./plugin-lifecycle.md)

package/docs/framework/helpers.md

@@ -0,0 +1,118 @@
+# Helpers
+
+Helpers are small utilities an application should not have to rewrite. They are plain functions over the context, not Cordis services.
+Import them from `acryl-router/helpers`, except the typed client, which has its own entry, `acryl-router/client`.
+
+| Helper | Use |
+| --- | --- |
+| `stream`, `streamText`, `streamSSE` | streaming responses and server-sent events |
+| `getCookie`, `setCookie`, `deleteCookie`, `getSignedCookie`, `setSignedCookie`, `generateCookie`, `generateSignedCookie` | cookies |
+| `testClient` | a typed client that calls an app in process, for tests |
+| `validator`, `schemaValidator` | input validation, see [Validation](./validation.md) |
+| `createMiddleware`, `createFactory` | typed middleware and handlers that share variables |
+| `html`, `raw` | escaped HTML templates |
+| `accepts` | content negotiation from `Accept` headers |
+| `routePath`, `matchedRoutes`, `baseRoutePath`, `basePath` | the route a request matched |
+| `getConnInfo`, `connectionOf` | the peer and local port, see [Context](./context.md#transport-facts) |
+| `getMimeType`, `getExtension`, `mimes` | media types by file extension |
+| `defineWebSocketHelper`, `WSContext` and their types | the runtime-neutral WebSocket pieces an adapter builds on |
+
+JWT signing and verification (`sign`, `verify`, `decode`) live with the `jwt` middleware in `acryl-router/middleware`.
+
+## Streaming
+
+```ts
+import { stream, streamSSE, streamText } from 'acryl-router/helpers'
+
+app.get('/stream', c => stream(c, async stream => {
+  stream.onAbort(() => console.log('aborted'))
+  await stream.write(new Uint8Array([0x48, 0x69]))
+  await stream.pipe(anotherReadableStream)
+}))
+
+app.get('/text', c => streamText(c, async stream => {
+  await stream.writeln('Hello')
+  await stream.sleep(1000)
+  await stream.write('there')
+}))
+```
+
+Server-sent events write one message at a time with `writeSSE`:
+
+```ts
+app.get('/events', c => streamSSE(c, async stream => {
+  let id = 0
+  while (!stream.aborted) {
+    await stream.writeSSE({ event: 'time', data: new Date().toISOString(), id: String(id++) })
+    await stream.sleep(1000)
+  }
+}))
+```
+
+- The callback runs after the response is returned. When it throws, the optional third argument `onError(error, stream)` runs and the
+  stream sends an `error` event before it closes.
+- There is no built-in keep-alive: send a comment or an event on a timer when a proxy closes idle connections.
+- When the plugin that serves the stream unloads, or the router is disposed, the router cancels the response body, so `onAbort` runs,
+  `aborted` turns true and a loop that checks `stream.aborted` ends with its owner.
+
+## Cookies
+
+```ts
+import { deleteCookie, getCookie, getSignedCookie, setCookie, setSignedCookie } from 'acryl-router/helpers'
+
+app.get('/cookie', c => {
+  setCookie(c, 'theme', 'dark', { path: '/', httpOnly: true, secure: true, sameSite: 'Strict', maxAge: 60 * 60 * 24 })
+  const theme = getCookie(c, 'theme')
+  const all = getCookie(c)
+  deleteCookie(c, 'old')
+  return c.json({ theme, all })
+})
+
+app.get('/signed', async c => {
+  await setSignedCookie(c, 'session', 'value', secret)
+  const session = await getSignedCookie(c, secret, 'session')   // false when the signature does not match
+  return c.json({ session })
+})
+```
+
+`generateCookie` and `generateSignedCookie` return the `Set-Cookie` string without touching a context. The `__Secure-` and `__Host-`
+prefixes are available through `{ prefix: 'secure' }` and `{ prefix: 'host' }`, and the options are checked against their rules.
+
+## Testing
+
+`app.request(path, init?)` calls an app in process and returns a `Response`. `testClient` adds the route types:
+
+```ts
+import { testClient } from 'acryl-router/helpers'
+
+const app = new App()
+  .get('/search', c => c.json({ query: c.req.query('q') }))
+
+const client = testClient(app)
+const response = await client.search.$get({ query: { q: 'cordis' } })
+expect(await response.json()).toEqual({ query: 'cordis' })
+```
+
+The routes must be chained on one expression (as above) for their types to reach the client. Add a test through the Cordis router as well:
+an app test cannot prove the mount, the prefix or the disposal.
+
+## The typed client
+
+`acryl-router/client` is the same client for a real server. It runs in a browser or any runtime with `fetch`, without Cordis:
+
+```ts
+import { hc } from 'acryl-router/client'
+import type { SearchRoutes } from 'my-server'   // the type of the chained app, exported by the server package
+
+const client = hc<SearchRoutes>('http://127.0.0.1:3290/search-app')
+const response = await client.search.$get({ query: { q: 'cordis' } })
+```
+
+Export the app's type (`export type SearchRoutes = typeof app`) from the server package; the client imports only the type, never the
+server code.
+
+## Not yet ported
+
+Proxying, a WebSocket upgrade under the router, JSX, static-site generation, CSS-in-JS and the cache helpers are later tasks (see
+`specs/047-framework-port/plan.md`). Add a missing helper to the framework as a ported, tested helper, not as private code in one
+application.

package/docs/framework/middleware.md

@@ -0,0 +1,154 @@
+# Middleware
+
+Middleware is code that runs around a handler. Use it for behavior shared by several routes: authentication, authorization, logging, CORS,
+caching, compression, request IDs and timing.
+
+## Write middleware
+
+```ts
+import type { MiddlewareHandler } from 'acryl-router'
+
+const timing: MiddlewareHandler = async (c, next) => {
+  const started = performance.now()
+  await next()
+  c.header('X-Response-Time', String(Math.round(performance.now() - started)))
+}
+
+app.use(timing)
+```
+
+`await next()` runs the remaining middleware and then the handler. Not calling it ends the chain, so middleware that refuses a request
+returns a response itself:
+
+```ts
+const requireAdmin: MiddlewareHandler = async (c, next) => {
+  if (!isAdmin(c)) return c.json({ error: 'forbidden' }, 403)
+  await next()
+}
+```
+
+Middleware does not return a response *and* call `next()`: after `next()` it changes `c.res` (or assigns a new `Response` to it) instead.
+
+Authentication establishes an identity; authorization decides whether that identity may do this. Keep them as separate middleware when
+their failure answers differ.
+
+## Scope and order
+
+```ts
+app.use(requestLogger)               // every route of this app
+app.use('/admin/*', requireAdmin)    // below a prefix
+app.on(['POST', 'PUT'], '/items/*', audit)
+```
+
+Middleware runs in registration order and only wraps routes registered after it. The first middleware registered is the outermost: its code
+before `next()` runs first and its code after `next()` runs last.
+
+## Share values with handlers
+
+`createMiddleware` types the variables a middleware sets, and the app picks them up when it is chained:
+
+```ts
+import { createMiddleware } from 'acryl-router/helpers'
+
+const withUser = createMiddleware<{ Variables: { user: User } }>(async (c, next) => {
+  c.set('user', await loadUser(c))
+  await next()
+})
+
+const app = new App().use(withUser).get('/me', c => c.json(c.var.user))
+```
+
+Only request-local values belong here. Shared services belong behind Cordis injection.
+
+## Errors
+
+`await next()` does not throw. When a handler or later middleware throws, the error becomes a response first (an `HTTPException` its own,
+anything else through `onError`) and is left in `c.error`:
+
+```ts
+app.use(async (c, next) => {
+  await next()
+  if (c.error) metrics.count('request_failed')
+})
+```
+
+So a `try { await next() } catch` around `next()` never catches anything. Map domain errors to answers in `app.onError`:
+
+```ts
+app.onError((error, c) => {
+  if (error instanceof DomainError) return c.json({ error: error.code }, error.status)
+  console.error(error)
+  return c.json({ error: 'internal_error' }, 500)
+})
+```
+
+## Built-in middleware
+
+Import from `acryl-router/middleware`:
+
+| Middleware | What it does |
+| --- | --- |
+| `basicAuth`, `bearerAuth` | HTTP Basic and Bearer authentication |
+| `jwt`, `jwk` (with `sign`, `verify`, `decode`, `verifyWithJwks`) | JSON Web Token verification, from a secret or a key set |
+| `bodyLimit` | refuse a request body over a size, with 413, while it streams |
+| `cors` | CORS headers and preflight answers |
+| `csrf` | refuse a cross-site form submission by its `Origin` or `Sec-Fetch-Site` |
+| `secureHeaders` (with `NONCE`) | security headers, including a content security policy with nonces |
+| `ipRestriction` | allow or deny by the peer address (read through `getConnInfo`) |
+| `loopbackOnly` (with `loopbackAuthority`, `sameOrigin`) | only requests from this machine to this app; see below |
+| `compress` | gzip or deflate the response |
+| `etag` | ETag headers and 304 answers |
+| `logger` | one log line per request and response |
+| `requestId` | a request ID header and `c.var.requestId` |
+| `timing` (with `startTime`, `endTime`, `setMetric`, `wrapTime`) | `Server-Timing` headers |
+| `timeout` | answer with an error when a handler takes too long |
+| `prettyJSON` | indented JSON when the query asks for it |
+| `poweredBy` | an `X-Powered-By` header |
+| `methodNotAllowed({ app })` | 405 with an `Allow` header for a known path of `app` asked with another method |
+| `methodOverride` | take the method from a form field, header or query |
+| `trimTrailingSlash`, `appendTrailingSlash` | redirect to the canonical path |
+| `languageDetector` (with `detectFromPath`, `detectFromQuery`, `detectFromCookie`, `detectFromHeader`) | the request's language as a variable |
+| `contextStorage` (with `getContext`, `tryGetContext`) | the current context from code that is not given `c` |
+| `every`, `some`, `except` | combine middleware: all, the first that passes, or all except on some paths |
+| `serveStatic` | the runtime-neutral static file middleware; it needs a `getContent`. On Node use the one from `acryl-node-server` |
+
+### loopbackOnly
+
+The guard for a local app's own routes, such as a control API a desktop window calls:
+
+```ts
+import { loopbackOnly } from 'acryl-router/middleware'
+
+app.use('/control/*', loopbackOnly())
+```
+
+A request passes only when:
+
+- the peer is a loopback address and arrived on the real local port, both read from the transport, never from a header;
+- the `Host` header names a loopback hostname (`127.0.0.1`, `localhost`, `[::1]`, or `hostnames`) with that port, which stops DNS
+  rebinding;
+- for a request that changes things (not `GET`, `HEAD`, `OPTIONS`), any `Origin` is this same authority (`mutations: 'none'` turns this
+  off).
+
+An in-process call has no socket and is refused unless `inProcess: 'allow'` says the host's own code may call it. Everything refused gets a
+403.
+
+A private route that no other program on the machine may call either, such as a workspace's file and terminal routes, takes
+`callers: 'own-page'`:
+
+```ts
+app.use('/api/workspace/*', loopbackOnly({ callers: 'own-page', hostnames: ['127.0.0.1'] }))
+```
+
+Then every request must come from a page this app served: an `Origin` that is exactly this authority (with `Sec-Fetch-Site` absent or
+`same-origin`), or, for a read, which browsers often send without `Origin`, `Sec-Fetch-Site: same-origin` and a `Referer` from this
+authority. A script with no `Origin` is refused even for a read. `fromOwnPage(c, authority)` is the same check for middleware of your own.
+
+## Middleware in Cordis
+
+Middleware belongs to an `App`; 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/migration-from-0-3.md

@@ -0,0 +1,108 @@
+# 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 `App` 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
+import { HttpError } from 'acryl-router'
+import { readJson, streamSSE, valid, validate } from 'acryl-router/helpers'
+import { bodyLimit } from 'acryl-router/middleware'
+
+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 { App, HTTPException } from 'acryl-router'
+import { schemaValidator, streamSSE } from 'acryl-router/helpers'
+import { bodyLimit } from 'acryl-router/middleware'
+
+export function apply(ctx: Context): void {
+  const app = new App()
+    .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 `App`, 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 `App` 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 App<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 in `acryl-router/middleware`; 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.