acrylblends 0.4.1 → 0.5.0

package/docs/framework/{api-summary.md → api/summary.md}

@@ -6,9 +6,10 @@ One page with the calls an ordinary app uses, each linked to the page that expla
 
 ```ts
 import type { Context } from '@deepseek-ai/cordis'
-import { App } from 'acryl-router'
-import { trimTrailingSlash } from 'acryl-router/middleware'
-import { schemaValidator, streamSSE, type StandardSchema } from 'acryl-router/helpers'
+import { Acryl } from 'acrylblends'
+import { trimTrailingSlash } from 'acrylblends/trailing-slash'
+import { schemaValidator, type StandardSchema } from 'acrylblends/schema-validator'
+import { streamSSE } from 'acrylblends/streaming'
 import type {} from 'acryl-state'
 
 export const name = 'orders'                 // the package name and the Loader row id
@@ -26,7 +27,7 @@ const NewOrder: StandardSchema<{ item: string }> = {
 
 export function apply(ctx: Context): void {
   const orders = ctx.state.cell<Order[]>('orders.list', [])
-  const app = new App()
+  const app = new Acryl()
     .use(trimTrailingSlash())
     .get('/', c => c.json(orders.get()))
     .post('/', schemaValidator('json', NewOrder), c => {
@@ -45,11 +46,11 @@ export function apply(ctx: Context): void {
 }
 ```
 
-## `App` ([Routing](./routing.md))
+## `Acryl` ([Routing](../api/routing.md))
 
 | Call | Does |
 | --- | --- |
-| `new App()` | an application: a route table plus middleware |
+| `new Acryl()` | an application: a route table plus middleware |
 | `.get / .post / .put / .patch / .delete / .options (path, ...handlers)` | a route; handlers before the last are middleware for that route |
 | `.all(path, ...)`, `.on(methods, path, ...)` | any method, or a list of methods |
 | `.use([path], ...middleware)` | middleware for every route below `path` (all routes without it), registered before the routes it wraps |
@@ -60,9 +61,9 @@ export function apply(ctx: Context): void {
 | `.fetch(request)` | the app as a fetch handler |
 
 Paths: `/posts/:id` (parameter), `/posts/:id?` (optional), `/files/*` (wildcard), `/:name{[a-z]+}` (pattern). `/a` and `/a/` are different
-paths: see [Trailing slashes](./routing.md#trailing-slashes).
+paths: see [Trailing slashes](../api/routing.md#trailing-slashes).
 
-## The handler context `c` ([Context](./context.md))
+## The handler context `c` ([Context](../api/context.md))
 
 | Call | Does |
 | --- | --- |
@@ -78,7 +79,7 @@ paths: see [Trailing slashes](./routing.md#trailing-slashes).
 | `connectionOf(c)` / `getConnInfo(c)` | the caller's address and the local port, when a transport supplied them |
 | `throw new HTTPException(status, { message })` | stop with that status from anywhere in the chain |
 
-## The request `c.req` ([Request](./request.md))
+## The request `c.req` ([Request](../api/request.md))
 
 | Call | Gives |
 | --- | --- |
@@ -89,10 +90,11 @@ paths: see [Trailing slashes](./routing.md#trailing-slashes).
 | `c.req.valid(target)` | the value a validator checked, typed by its schema |
 | `c.req.method`, `c.req.path`, `c.req.url`, `c.req.raw` | the method, path, full URL and the Web `Request` |
 
-## Validation ([Validation](./validation.md))
+## Validation ([Validation](../cordis/validation.md))
 
 ```ts
-import { schemaValidator, validator } from 'acryl-router/helpers'
+import { schemaValidator } from 'acrylblends/schema-validator'
+import { validator } from 'acrylblends/validator'
 app.post('/', schemaValidator('json', Schema), c => c.json(c.req.valid('json')))
 ```
 
@@ -101,9 +103,9 @@ app.post('/', schemaValidator('json', Schema), c => c.json(c.req.valid('json')))
 - A failure is 400 `{ error: 'invalid <target>', issues: [{ message, path }] }`; `path` is dotted, and `""` when the issue has none.
 - The `json` target reads the body only with a JSON `Content-Type`; otherwise the schema sees `{}`.
 - `validator(target, (value, c) => valueOrResponse)` is the same middleware with a function instead of a schema.
-- Put `bodyLimit({ maxSize })` from `acryl-router/middleware` in front on routes open to untrusted callers.
+- Put `bodyLimit({ maxSize })` from `acrylblends/body-limit` in front on routes open to untrusted callers.
 
-## Streaming ([Helpers](./helpers.md))
+## Streaming ([Helpers](../guides/helpers.md))
 
 | Call | Does |
 | --- | --- |
@@ -123,16 +125,16 @@ Do not start timers inside a handler for keep-alives; let the plugin own one tim
 | `ctx.router.request(path, init?)`, `ctx.router.fetch(request)` | `router` | call the mounted routes in process (terminal UI, tests, other plugins) |
 | `ctx.router.onError(handler)`, `ctx.router.notFound(handler)` | `router` | router-wide error and not-found answers, owned by the caller |
 | `ctx.routerHttp.mount(prefix)` | `routerHttp` (`acryl-router-http`) | inside the ACRYL Host: serve a router prefix on the Host's web server (Web and Desktop). Use it through `ctx.inject(['routerHttp'], ...)` so the app also runs where there is no Host |
-| `ctx.nodeServer.url`, `ctx.nodeServer.port` | `nodeServer` (`acryl-node-server`) | without the Host: one Node server for the whole router; options `hostname` (`127.0.0.1`), `port` (`0`), `scan` (`20`). See [Node server](./node-server.md) |
+| `ctx.nodeServer.url`, `ctx.nodeServer.port` | `nodeServer` (`acryl-node-server`) | without the Host: one Node server for the whole router; options `hostname` (`127.0.0.1`), `port` (`0`), `scan` (`20`). See [Node server](../cordis/node-server.md) |
 | `ctx.state.cell(key, initial)` | `state` (`acryl-state`) | a writable cell owned by the plugin: `get()`, `set(value)`, `update(fn)`, `subscribe(fn)` returning an unsubscribe |
 | `ctx.state.derive(key, [cells], fn)` | `state` | a read-only cell computed from others |
 | `GET /api/state/:key`, `GET /api/state/:key/events` | `state` | each cell over the router, read-only; `useCell(cell)` from `acryl-state/react` in a React page |
 
 Everything a plugin registers this way (mounts, cells, handlers) goes away when the plugin unloads, and comes back once when it reloads:
-see [Plugin lifecycle and disposal](./plugin-lifecycle.md).
+see [Plugin lifecycle and disposal](../cordis/plugin-lifecycle.md).
 
-## Middleware ([Middleware](./middleware.md))
+## Middleware ([Middleware](../concepts/middleware.md))
 
-From `acryl-router/middleware`: `bodyLimit`, `cors`, `csrf`, `secureHeaders`, `etag`, `compress`, `logger`, `requestId`, `timeout`,
+Each from its own subpath (`acrylblends/body-limit`, `acrylblends/cors`, ...): `bodyLimit`, `cors`, `csrf`, `secureHeaders`, `etag`, `compress`, `logger`, `requestId`, `timeout`,
 `bearerAuth`, `basicAuth`, `jwt`, `jwk`, `ipRestriction`, `methodNotAllowed`, `trimTrailingSlash`, `appendTrailingSlash`, `some` /
 `every` / `except`, and ACRYL's `loopbackOnly` for private loopback routes.

package/docs/framework/concepts/benchmarks.md

@@ -0,0 +1,26 @@
+# Benchmarks
+
+> **Not yet measured.** The routers in the framework are designed for different situations (see [Routers](routers.md)), but benchmark results for Acryl itself have not been
+> produced yet, and this page does not quote anyone else's numbers as ours. When Acryl has its own reproducible benchmark suite, its scripts and results will be here.
+
+To compare routers on your own workload today, register your routes on an `Acryl` app with each router and time `app.request()` for the paths you care about:
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+import { RegExpRouter } from 'acrylblends/router/reg-exp-router'
+import { TrieRouter } from 'acrylblends/router/trie-router'
+
+const routes = ['/', '/users/:id', '/posts/:id/comments']
+
+const apps = {
+  RegExpRouter: new Acryl({ router: new RegExpRouter() }),
+  TrieRouter: new Acryl({ router: new TrieRouter() }),
+}
+
+for (const [name, app] of Object.entries(apps)) {
+  for (const path of routes) app.get(path, (c) => c.text('ok'))
+  const start = performance.now()
+  for (let i = 0; i < 100_000; i++) await app.request('/users/42')
+  console.log(name, Math.round(performance.now() - start), 'ms')
+}
+```

package/docs/framework/concepts/developer-experience.md

@@ -0,0 +1,5 @@
+# Developer Experience
+
+To create a great application, we need great development experience.
+Fortunately, we can write applications for Node.js and Bun in TypeScript without having the need to transpile it to JavaScript.
+Acryl is written in TypeScript and can make applications type-safe.

package/docs/framework/concepts/middleware.md

@@ -0,0 +1,21 @@
+# Middleware
+
+We call the primitive that returns `Response` as "Handler".
+"Middleware" is executed before and after the Handler and handles the `Request` and `Response`.
+It's like an onion structure.
+
+For example, we can write the middleware to add the "X-Response-Time" header as follows.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+// ---cut---
+app.use(async (c, next) => {
+  const start = performance.now()
+  await next()
+  const end = performance.now()
+  c.res.headers.set('X-Response-Time', `${end - start}`)
+})
+```
+
+With this simple method, we can write our own custom middleware and we can use the built-in or third party middleware.

package/docs/framework/concepts/motivation.md

@@ -0,0 +1,14 @@
+# Philosophy
+
+## Motivation
+
+A web application should not be written twice because it runs in two places. Acryl builds on the Web Standard APIs (`Request`, `Response`, `fetch`, `URL`, streams), so a
+handler written once runs on Node.js (and experimentally Bun), in a test with no socket, and inside a Cordis app.
+
+Three ideas follow from that:
+
+- **The handler is a function over Web Standards.** There is no runtime object to import, so there is nothing to replace when the runtime changes. See
+  [Web Standards](web-standard.md).
+- **A plugin owns what it mounts.** Inside a Cordis app an application is mounted by a plugin and disappears when that plugin unloads, which is what lets an agent add,
+  update and remove features while the app runs. See [Plugin lifecycle](../cordis/plugin-lifecycle.md).
+- **The documentation travels with the app.** A generated app contains these pages, so a person or a coding agent working in the folder reads the API from the folder.

package/docs/framework/concepts/routers.md

@@ -0,0 +1,63 @@
+# Routers
+
+The router decides which handler answers a request. Acryl has five routers behind one API, and an `Acryl` app uses `SmartRouter` unless you choose another.
+
+| Router | Import | Built for |
+| --- | --- | --- |
+| `SmartRouter` | `acrylblends/router/smart-router` | the default: it picks from the routers it is given, by the routes registered |
+| `RegExpRouter` | `acrylblends/router/reg-exp-router` | matching all routes with one regular expression built before dispatch |
+| `TrieRouter` | `acrylblends/router/trie-router` | all route patterns, with a trie tree and no linear loop |
+| `LinearRouter` | `acrylblends/router/linear-router` | applications that register routes at every start, because registration compiles nothing |
+| `PatternRouter` | `acrylblends/router/pattern-router` | the smallest implementation |
+
+## RegExpRouter
+
+**RegExpRouter** turns the route patterns into one large regular expression and gets the result with one match. It is not the kind of "RegExp router" that tries each
+route's expression in a loop, so matching does not repeat for every route.
+
+It does not support every routing pattern, so it is normally combined with a router that does, through `SmartRouter`.
+
+## TrieRouter
+
+**TrieRouter** uses a trie tree, and like RegExpRouter it does not loop over the routes. It supports all patterns.
+
+## SmartRouter
+
+**SmartRouter** is for using several routers. It infers, from the routes registered, which of the routers it was given can serve them, and keeps using that one. An `Acryl`
+app defaults to:
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+import { RegExpRouter } from 'acrylblends/router/reg-exp-router'
+import { SmartRouter } from 'acrylblends/router/smart-router'
+import { TrieRouter } from 'acrylblends/router/trie-router'
+
+const app = new Acryl({
+  router: new SmartRouter({ routers: [new RegExpRouter(), new TrieRouter()] }),
+})
+```
+
+## LinearRouter
+
+**LinearRouter** registers a route without compiling anything, by keeping the routes in a list and matching them in order. Registration is cheap and matching is linear in
+the number of routes, so it suits an environment that builds the application at every start and serves few requests.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+import { LinearRouter } from 'acrylblends/router/linear-router'
+
+const app = new Acryl({ router: new LinearRouter() })
+```
+
+## PatternRouter
+
+**PatternRouter** is the smallest of the routers: it adds a pattern and matches it, and nothing else. Choose it when size matters more than anything else.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+import { PatternRouter } from 'acrylblends/router/pattern-router'
+
+const app = new Acryl({ router: new PatternRouter() })
+```
+
+How the routers compare on your workload is for you to measure; see [Benchmarks](benchmarks.md).

package/docs/framework/concepts/stacks.md

@@ -0,0 +1,235 @@
+# Acryl Stacks
+
+Acryl makes easy things easy and hard things easy.
+It is suitable for not just only returning JSON, but it's also great for building the full-stack application including REST API servers and the client.
+
+## RPC
+
+Acryl's RPC feature allows you to share API specs with little change to your code.
+The client generated by `hc` will read the spec and access the endpoint type-safety.
+
+The following libraries make it possible.
+
+- Acryl - API Server
+- [Zod](https://zod.dev) - Validator
+- Zod Validator Middleware
+- `hc` - HTTP Client
+
+We can call the set of these components the **Acryl Stack**.
+Now let's create an API server and a client with it.
+
+## Writing API
+
+First, write an endpoint that receives a GET request and returns JSON.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+
+const app = new Acryl()
+
+app.get('/hello', (c) => {
+  return c.json({
+    message: `Hello!`,
+  })
+})
+```
+
+## Validation with Zod
+
+Validate with Zod to receive the value of the query parameter.
+
+```ts
+import { schemaValidator } from 'acrylblends/schema-validator'
+import * as z from 'zod'
+
+app.get(
+  '/hello',
+  schemaValidator(
+    'query',
+    z.object({
+      name: z.string(),
+    })
+  ),
+  (c) => {
+    const { name } = c.req.valid('query')
+    return c.json({
+      message: `Hello! ${name}`,
+    })
+  }
+)
+```
+
+## Sharing the Types
+
+To emit an endpoint specification, export its type.
+
+> **Warning.**
+> For the RPC to infer routes correctly, all included methods must be chained, and the endpoint or app type must be inferred from a declared variable. For more, see [Best Practices for RPC](../guides/best-practices.md#if-you-want-to-use-rpc-features).
+>
+
+```ts
+const route = app.get(
+  '/hello',
+  schemaValidator(
+    'query',
+    z.object({
+      name: z.string(),
+    })
+  ),
+  (c) => {
+    const { name } = c.req.valid('query')
+    return c.json({
+      message: `Hello! ${name}`,
+    })
+  }
+)
+
+export type AppType = typeof route
+```
+
+## Client
+
+Next, The client-side implementation.
+Create a client object by passing the `AppType` type to `hc` as generics.
+Then, magically, completion works and the endpoint path and request type are suggested.
+
+```ts
+import type { AppType } from './server'
+import { hc } from 'acrylblends/client'
+
+const client = hc<AppType>('/api')
+const res = await client.hello.$get({
+  query: {
+    name: 'Acryl',
+  },
+})
+```
+
+The `Response` is compatible with the fetch API, but the data that can be retrieved with `json()` has a type.
+
+```ts
+const data = await res.json()
+console.log(`${data.message}`)
+```
+
+Sharing API specifications means that you can be aware of server-side changes.
+
+## With React
+
+You can create an application with a React front-end using the typed client.
+
+The API server.
+
+```ts
+// src/index.ts
+import { Acryl } from 'acrylblends'
+import * as z from 'zod'
+import { schemaValidator } from 'acrylblends/schema-validator'
+
+const schema = z.object({
+  id: z.string(),
+  title: z.string(),
+})
+
+type Todo = z.infer<typeof schema>
+
+const todos: Todo[] = []
+
+const api = new Acryl()
+  .post('/todo', schemaValidator('form', schema), (c) => {
+    const todo = c.req.valid('form')
+    todos.push(todo)
+    return c.json({
+      message: 'created!',
+    })
+  })
+  .get('/todo', (c) => {
+    return c.json({
+      todos,
+    })
+  })
+
+export type AppType = typeof api
+
+const app = new Acryl()
+app.route('/api', api)
+
+export default app
+```
+
+The client with React and React Query.
+
+```tsx
+// src/App.tsx
+import {
+  useQuery,
+  useMutation,
+  QueryClient,
+  QueryClientProvider,
+} from '@tanstack/react-query'
+import type { AppType } from '../functions/api/[[route]]'
+import { hc, InferResponseType, InferRequestType } from 'acrylblends/client'
+
+const queryClient = new QueryClient()
+const client = hc<AppType>('/api')
+
+export default function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <Todos />
+    </QueryClientProvider>
+  )
+}
+
+const Todos = () => {
+  const query = useQuery({
+    queryKey: ['todos'],
+    queryFn: async () => {
+      const res = await client.todo.$get()
+      return await res.json()
+    },
+  })
+
+  const $post = client.todo.$post
+
+  const mutation = useMutation<
+    InferResponseType<typeof $post>,
+    Error,
+    InferRequestType<typeof $post>['form']
+  >({
+    mutationFn: async (todo) => {
+      const res = await $post({
+        form: todo,
+      })
+      return await res.json()
+    },
+    onSuccess: async () => {
+      queryClient.invalidateQueries({ queryKey: ['todos'] })
+    },
+    onError: (error) => {
+      console.log(error)
+    },
+  })
+
+  return (
+    <div>
+      <button
+        onClick={() => {
+          mutation.mutate({
+            id: Date.now().toString(),
+            title: 'Write code',
+          })
+        }}
+      >
+        Add Todo
+      </button>
+
+      <ul>
+        {query.data?.todos.map((todo) => (
+          <li key={todo.id}>{todo.title}</li>
+        ))}
+      </ul>
+    </div>
+  )
+}
+```

package/docs/framework/concepts/web-standard.md

@@ -0,0 +1,37 @@
+# Web Standards
+
+Acryl uses only **Web Standards** like Fetch.
+They were originally used in the `fetch` function and consist of basic objects that handle HTTP requests and responses.
+In addition to `Requests` and `Responses`, there are `URL`, `URLSearchParam`, `Headers` and others.
+
+Cloudflare Workers, Deno, and Bun also are built upon Web Standards.
+For example, a server that returns "Hello World" could be written as below. This could run on Cloudflare Workers and Bun.
+
+```ts twoslash
+export default {
+  async fetch() {
+    return new Response('Hello World')
+  },
+}
+```
+
+Acryl uses only Web Standards, which means that Acryl can run on any runtime that supports them.
+In addition, we have a Node.js adapter. Acryl runs on these runtimes:
+
+- Cloudflare Workers (`workerd`)
+- Deno
+- Bun
+- Fastly Compute
+- AWS Lambda
+- Node.js
+- Vercel (edge-light)
+- WebAssembly (w/ [WebAssembly System Interface (WASI)][wasi] via [`wasi:http`][wasi-http])
+
+It also works on Netlify and other platforms.
+The same code runs on all platforms.
+
+Cloudflare Workers, Deno, Shopify, and others launched [WinterCG](https://wintercg.org) to discuss the possibility of using the Web Standards to enable "web-interoperability".
+Acryl will follow their steps and go for **the Standard of the Web Standards**.
+
+[wasi]: https://github.com/WebAssembly/wasi
+[wasi-http]: https://github.com/WebAssembly/wasi-http

package/docs/framework/{getting-started.md → cordis/acryl-in-a-cordis-app.md}

@@ -1,31 +1,31 @@
-# Getting started
+# Acryl in a Cordis app
 
-The ACRYL Framework puts its application model inside Cordis. You build an ordinary `App`, register routes and middleware on it, then
+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** - `App`, handlers, middleware, context, requests, responses, validation and helpers. This is the ACRYL
+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 `App` owns the route table. The plugin that mounted the app owns the mount for as long as its
+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 { App } from 'acryl-router'
+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 App()
+  const app = new Acryl()
     .get('/', c => c.json({ ok: true }))
     .get('/todos/:id', c => c.json({ id: c.req.param('id') }))
 
@@ -48,14 +48,14 @@ export function apply(ctx: Context): void {
 `/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.
+- **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 'acryl-router/middleware'
+  import { trimTrailingSlash } from 'acrylblends/trailing-slash'
 
-  const app = new App()
+  const app = new Acryl()
     .use(trimTrailingSlash())
     .get('/', c => c.json({ ok: true }))
   ```
@@ -64,9 +64,9 @@ one of these, in this order of preference:
   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).
+`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
@@ -79,7 +79,7 @@ Finish building the app before you mount it: the router copies the app's routes
 Middleware is registered on the app before the routes it should wrap:
 
 ```ts
-const app = new App()
+const app = new Acryl()
   .use(async (c, next) => {
     const started = Date.now()
     await next()
@@ -89,7 +89,7 @@ const app = new App()
 ```
 
 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).
+The built-in set is listed in [Middleware](../concepts/middleware.md).
 
 ## Run the same app on a surface
 
@@ -141,6 +141,6 @@ expect(await response.json()).toEqual({ id: '42' })
 ## Next
 
 - [Core concepts](./concepts.md)
-- [Routing and mounting](./routing.md)
-- [Context](./context.md)
+- [Routing and mounting](../api/routing.md)
+- [Context](../api/context.md)
 - [Plugin lifecycle and disposal](./plugin-lifecycle.md)

package/docs/framework/{concepts.md → cordis/concepts.md}

@@ -3,9 +3,9 @@
 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.
 
-## App
+## Acryl
 
-An `App` is a self-contained ACRYL application. It owns:
+An `Acryl` is a self-contained ACRYL application. It owns:
 
 - routes;
 - middleware;

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.