acrylblends 0.4.1 → 0.5.0

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

@@ -1,17 +1,18 @@
 # 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
+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
-import { HttpError } from 'acryl-router'
-import { readJson, streamSSE, valid, validate } from 'acryl-router/helpers'
-import { bodyLimit } from 'acryl-router/middleware'
+```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')
@@ -33,12 +34,14 @@ export function apply(ctx: Context): void {
 0.4.0:
 
 ```ts
-import { App, HTTPException } from 'acryl-router'
-import { schemaValidator, streamSSE } from 'acryl-router/helpers'
-import { bodyLimit } from 'acryl-router/middleware'
+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 App()
+  const app = new Acryl()
     .use(bodyLimit({ maxSize: 16 * 1024 }))
     .get('/todos/:id', c => {
       const todo = find(c.req.param('id'))
@@ -63,16 +66,16 @@ Public paths do not change: the mount path plus the app's route path is the old
 
 | 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.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 `App` per group mounted at `prefix`, or `app.route(prefix, sub)` / `app.basePath(prefix)` |
+| `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 App<RouterEnv>()` to read `c.env.connection` |
+| `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) |
@@ -86,7 +89,7 @@ Public paths do not change: the mount path plus the app's route path is the old
 | 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 |
+| `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
 

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/{migration-from-dsh-webserver.md → cordis/migration-from-dsh-webserver.md}

@@ -1,7 +1,7 @@
 # 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 `App`, a mount, and Web-standard requests.
+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
 
@@ -24,12 +24,12 @@ export function apply(ctx: Context): void {
 After, it builds an app, mounts it, and asks the Host adapter to serve the prefix:
 
 ```ts
-import { App } from 'acryl-router'
+import { Acryl } from 'acrylblends'
 
 export const inject = ['router']
 
 export function apply(ctx: Context): void {
-  const app = new App().get('/health', c => c.json({ ok: true }))
+  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') })
 }
@@ -42,8 +42,8 @@ the route in process (`ctx.router.request('/api/health')`), which the old handle
 
 | webServer | Framework |
 | --- | --- |
-| `register({ kind: 'exact', path, handler })` | a route on an `App`, mounted with `ctx.router.route`; served with `routerHttp.mount(path)` |
-| `register({ kind: 'prefix', path, handler })` | an `App` mounted at `path` with its own routes below it |
+| `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 |
@@ -56,7 +56,7 @@ the route in process (`ctx.router.request('/api/health')`), which the old handle
 
 Move one capability at a time:
 
-1. Build an `App` for the capability and move its handlers into it without changing their public answers.
+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
@@ -71,7 +71,7 @@ per domain folder (`filesRoutes`, `gitRoutes`, `ptyRoutes`, ...), composes them
 result after the effect that builds its services, and serves the one prefix `/api/acryl-workspace`:
 
 ```ts
-const built: { api?: App } = {}
+const built: { api?: Acryl } = {}
 ctx.effect(() => {
   // ... the PTY table, git, files, the project registry ...
   built.api = privateApi(filesRoutes(files, report), gitRoutes(git, report) /* , ... */)

package/docs/framework/{routing.md → cordis/mounting.md}

@@ -1,109 +1,6 @@
-# Routing and mounting
+# Mounting and trailing slashes
 
-Routing has two levels:
-
-1. Routes inside an `App`.
-2. Cordis mounts that place an `App` in the host at a base path.
-
-Keeping those levels separate lets application code stay portable while the host controls the public route space.
-
-## HTTP methods
-
-```ts
-app.get('/todos', listTodos)
-app.post('/todos', createTodo)
-app.put('/todos/:id', replaceTodo)
-app.patch('/todos/:id', updateTodo)
-app.delete('/todos/:id', deleteTodo)
-app.options('/todos', options)
-app.all('/health', health)              // any method
-app.on('PURGE', '/cache', purge)        // a custom method
-app.on(['PUT', 'DELETE'], '/post', handler)
-app.on('GET', ['/hello', '/en/hello'], handler)
-```
-
-`HEAD` is answered from the `GET` route with the body removed. A known path asked with another method answers 404 like an unknown path;
-add the `methodNotAllowed` middleware to an app that should answer 405 with an `Allow` header instead.
-
-```ts
-import { methodNotAllowed } from 'acryl-router/middleware'
-
-const app = new App()
-app.use(methodNotAllowed({ app }))      // POST /item -> 405, Allow: GET, HEAD
-app.get('/item', c => c.text('item'))
-```
-
-Routes can be chained, and a chained call without a path reuses the last one:
-
-```ts
-app
-  .get('/endpoint', c => c.text('GET /endpoint'))
-  .post(c => c.text('POST /endpoint'))
-  .delete(c => c.text('DELETE /endpoint'))
-```
-
-Chaining also carries the route types, which the typed `testClient` and `acryl-router/client` read.
-
-## Path parameters
-
-```ts
-app.get('/users/:userId/todos/:todoId', c => {
-  const { userId, todoId } = c.req.param()
-  return c.json({ userId, todoId })
-})
-
-app.get('/api/animal/:type?', c => c.text('Animal!'))             // optional: /api/animal and /api/animal/cat
-app.get('/post/:date{[0-9]+}/:title{[a-z]+}', handler)            // constrained by a regular expression
-app.get('/posts/:filename{.+\\.png}', handler)                    // a parameter that includes slashes
-```
-
-Prefer explicit routes over complex patterns when both express the same rule.
-
-## Wildcards
-
-```ts
-app.use('/admin/*', requireAdmin)
-app.get('/wild/*/card', c => c.text('GET /wild/*/card'))
-```
-
-A wildcard is appropriate for a prefix boundary. It should not hide distinct resources that callers need to address independently.
-
-## Priority
-
-Handlers and middleware run in registration order, and the first handler that returns a response ends the request:
-
-```ts
-app.get('/book/a', c => c.text('a'))          // GET /book/a -> a
-app.get('/book/:slug', c => c.text('common'))  // GET /book/b -> common
-```
-
-Put middleware above the handlers it should wrap and a fallback such as `app.get('*', ...)` below the others.
-
-## Grouping related routes
-
-Build a smaller app for a feature, then place it inside another app:
-
-```ts
-const todos = new App()
-todos.get('/', listTodos)
-todos.post('/', createTodo)
-todos.get('/:id', showTodo)
-
-const app = new App()
-app.route('/todos', todos)
-```
-
-`route` copies the routes the sub-app has at that moment. Register them first: a route added to `todos` after `app.route(...)` is not
-part of `app`.
-
-## Base paths
-
-```ts
-const api = new App().basePath('/api/v1')
-api.get('/todos', listTodos)   // GET /api/v1/todos
-```
-
-Do not repeat a mount prefix both in `basePath` and in the outer mount unless the doubled path is deliberate.
+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
 
@@ -164,15 +61,15 @@ What each choice does for an app mounted at `/orders` with routes `/` and `/:id`
 | 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 App({ strict: false })` for the mounted app | 200 | 404 | 200 | 404 |
+| `new Acryl({ strict: false })` for the mounted app | 200 | 404 | 200 | 404 |
 
-- **`trimTrailingSlash()`** (from `acryl-router/middleware`) is the choice a plugin makes for itself. It acts after the handlers: only
+- **`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 `App` is the core's option and works for an app you serve yourself (`app.fetch`, `app.request`). It has no
+- **`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.

package/docs/framework/{node-server.md → cordis/node-server.md}

@@ -10,7 +10,7 @@ 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 'acryl-node-server'
+import * as nodeServer from 'acrylblends/node-server'
 import * as todo from './todo.ts'
 
 const root = new Context()
@@ -39,16 +39,16 @@ Every request goes to `ctx.router.fetch`, so routes appear and disappear as plug
 
 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](./context.md#transport-facts).
+[Context](../api/context.md#transport-facts).
 
 ## Static files
 
 The Node `serveStatic` reads files from disk:
 
 ```ts
-import { serveStatic } from 'acryl-node-server'
+import { serveStatic } from 'acrylblends/node-server'
 
-const app = new App()
+const app = new Acryl()
   .use('/assets/*', serveStatic({ root: './public' }))
   .get('/', serveStatic({ path: './public/index.html' }))
 ```

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

@@ -33,7 +33,7 @@ so a plugin cannot take over a Host route by mounting on it.
 
 Desktop runs the same Host inside Electron, and its window talks to the Host's web server on a loopback port. A plugin's routes therefore
 serve Desktop exactly as they serve Web, with no Desktop-specific code. Guard local control routes with `loopbackOnly` (see
-[Middleware](./middleware.md#loopbackonly)).
+[Middleware](../concepts/middleware.md#loopbackonly)).
 
 A transport without a port, handing `ctx.router.fetch` to Electron's `protocol.handle`, needs no change to plugins and is a later task
 (`specs/047-framework-port/plan.md` T014).
@@ -57,7 +57,7 @@ host declares instead of assuming a network route exists.
 
 | Concern | Owner |
 | --- | --- |
-| Route handlers and middleware | the feature plugin's `App` |
+| Route handlers and middleware | the feature plugin's `Acryl` |
 | Mount path and lifetime | the feature plugin, through `ctx.router.route` |
 | Socket and port | the Host (`acryl-router-http`) or `acryl-node-server` |
 | Terminal rendering and input | the terminal surface |

package/docs/framework/cordis/transport-and-cancellation.md

@@ -0,0 +1,57 @@
+# Transport facts and cancellation
+
+`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 { Acryl } from 'acrylblends'
+import { connectionOf, type RouterEnv } from 'acrylblends/conninfo'
+import { getConnInfo } from 'acrylblends/conninfo'
+
+const app = new Acryl<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 'acrylblends/http-exception'
+
+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/{validation.md → cordis/validation.md}

@@ -7,15 +7,15 @@ Validate untrusted input at the route boundary. `schemaValidator` takes any [Sta
 
 ```ts
 import z from '@deepseek-ai/schemastery'
-import { App } from 'acryl-router'
-import { schemaValidator } from 'acryl-router/helpers'
+import { Acryl } from 'acrylblends'
+import { schemaValidator } from 'acrylblends/schema-validator'
 
 const NewTodo = z.object({
   title: z.string().required(),
   done: z.boolean().default(false),
 })
 
-const app = new App().post('/todos', schemaValidator('json', NewTodo), c => {
+const app = new Acryl().post('/todos', schemaValidator('json', NewTodo), c => {
   const todo = c.req.valid('json')   // typed by the schema's output
   return c.json({ todo }, 201)
 })
@@ -60,7 +60,7 @@ If you see a field error for a field the request clearly carries, check the requ
 explicitly can refuse other content types before the validator:
 
 ```ts
-import type { MiddlewareHandler } from 'acryl-router'
+import type { MiddlewareHandler } from 'acrylblends'
 
 const jsonOnly: MiddlewareHandler = async (c, next) => {
   // The same types the json target reads: application/json and application/*+json, parameters allowed.
@@ -101,11 +101,11 @@ app.get('/todos/:id', schemaValidator('param', z.object({ id: z.natural() })), s
 
 ## The core validator
 
-`validator` (also from `acryl-router/helpers`) takes a function instead of a schema. Return the value the handler should see, or a
+`validator` (from `acrylblends/validator`) takes a function instead of a schema. Return the value the handler should see, or a
 response to refuse:
 
 ```ts
-import { validator } from 'acryl-router/helpers'
+import { validator } from 'acrylblends/validator'
 
 app.post('/posts', validator('form', (value, c) => {
   const body = value['body']
@@ -119,15 +119,15 @@ app.post('/posts', validator('form', (value, c) => {
 Validation reads the whole body. Put `bodyLimit` in front of a validator on any route open to untrusted callers:
 
 ```ts
-import { bodyLimit } from 'acryl-router/middleware'
+import { bodyLimit } from 'acrylblends/body-limit'
 
 app.post('/todos', bodyLimit({ maxSize: 16 * 1024 }), schemaValidator('json', NewTodo), createTodo)
 ```
 
 ## Typed clients
 
-The validated input types flow into the route types, so the typed `testClient` and `acryl-router/client` check the request a caller sends.
-See [Helpers](./helpers.md#testing).
+The validated input types flow into the route types, so the typed `testClient` and `acrylblends/client` check the request a caller sends.
+See [Helpers](../guides/helpers.md#testing).
 
 ## What not to validate twice
 

package/docs/framework/getting-started/basic.md

@@ -0,0 +1,196 @@
+# Getting Started
+
+Using Acryl is easy. You set up the project, write code, develop with a local server, and run it. The same application code works on every verified runtime, with a different
+entry point for each. This page shows the basic usage.
+
+## Starter
+
+Starter templates are available for each runtime. Use the "create-acrylblends" command.
+
+**npm**
+
+```sh
+npm create acrylblends@latest my-app
+```
+
+**yarn**
+
+```sh
+yarn create acrylblends my-app
+```
+
+**pnpm**
+
+```sh
+pnpm create acrylblends@latest my-app
+```
+
+**bun**
+
+```sh
+bun create acrylblends@latest my-app
+```
+
+You are asked which template you want:
+
+```
+? Which template do you want to use?
+❯   nodejs
+    bun (experimental)
+    acryl-app
+```
+
+`nodejs` and `bun` (experimental) are a minimal Acryl application for that runtime. `acryl-app` is a Cordis app built from plugins, with an agent that can extend it while it
+runs (see [Acryl in a Cordis app](../cordis/acryl-in-a-cordis-app.md)). Pass `--template` to skip the question, see [create-acrylblends](../guides/create-acrylblends.md).
+
+The template is created in `my-app`: go to it, install the dependencies and start the local server.
+
+```sh
+cd my-app
+npm install
+npm run dev
+```
+
+## Hello World
+
+Write your first application in `src/index.ts`. The example below is a starter Acryl application.
+
+The `import` and the final `export default` are the same on every runtime; what differs is how the runtime starts the app (see [Node.js](nodejs.md) and [Bun](bun.md)).
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+
+const app = new Acryl()
+
+app.get('/', (c) => {
+  return c.text('Hello Acryl!')
+})
+
+export default app
+```
+
+Start the development server and open the address it prints.
+
+## Return JSON
+
+Returning JSON is also easy. The following handles a GET request to `/api/hello` and returns an `application/json` response.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+
+const app = new Acryl()
+
+app.get('/api/hello', (c) => {
+  return c.json({
+    ok: true,
+    message: 'Hello Acryl!',
+  })
+})
+```
+
+## Request and Response
+
+Getting a path parameter, a URL query value, and adding a response header is written as follows.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+
+const app = new Acryl()
+
+app.get('/posts/:id', (c) => {
+  const page = c.req.query('page')
+  const id = c.req.param('id')
+  c.header('X-Message', 'Hi!')
+  return c.text(`You want to see ${page} of ${id}`)
+})
+```
+
+POST, PUT and DELETE are handled the same way as GET.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+
+const app = new Acryl()
+
+app.post('/posts', (c) => c.text('Created!', 201))
+app.delete('/posts/:id', (c) => c.text(`${c.req.param('id')} is deleted!`))
+```
+
+## Return HTML
+
+Write HTML with [the html helper](../helpers/html.md):
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+import { html } from 'acrylblends/html'
+
+const app = new Acryl()
+
+app.get('/', (c) => {
+  const name = 'Acryl'
+  return c.html(html`<!doctype html><h1>Hello ${name}!</h1>`)
+})
+```
+
+[JSX](../guides/jsx.md) is not yet available.
+
+## Return raw Response
+
+You can also return a raw Web Standard `Response`.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+
+const app = new Acryl()
+
+app.get('/', () => {
+  return new Response('Good morning!')
+})
+```
+
+## Using Middleware
+
+Middleware can do the hard work for you. For example, add Basic Authentication.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+import { basicAuth } from 'acrylblends/basic-auth'
+
+const app = new Acryl()
+
+app.use(
+  '/admin/*',
+  basicAuth({
+    username: 'admin',
+    password: 'secret',
+  })
+)
+
+app.get('/admin', (c) => {
+  return c.text('You are authorized!')
+})
+```
+
+There are useful middleware included, such as Bearer and JWT authentication, CORS and ETag. See [Built-in middleware](../middleware/builtin/basic-auth.md).
+
+## Testing
+
+An app is a function from `Request` to `Response`, so a test needs no server:
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+
+const app = new Acryl()
+app.get('/', (c) => c.text('Hello Acryl!'))
+
+const response = await app.request('/')
+console.log(response.status, await response.text())
+```
+
+See [Testing](../guides/testing.md).
+
+## Next
+
+- [Node.js](nodejs.md) and [Bun](bun.md) (experimental)
+- [Routing](../api/routing.md), [Context](../api/context.md) and [Request](../api/request.md)
+- [Validation](../guides/validation.md)