acrylblends 0.4.1 → 0.5.1

package/LICENSE

@@ -0,0 +1,73 @@
+MIT License
+
+Copyright (c) 2026 WebBoxes s.r.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This package is built from the ACRYL port of Hono v4.13.13 (https://github.com/honojs/hono), used under this license:
+
+MIT License
+
+Copyright (c) 2021 - present, Yusuke Wada and Hono contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Its node-server entries are built from the ACRYL port of @hono/node-server v2.1.5 (https://github.com/honojs/node-server), used under this license:
+
+MIT License
+
+Copyright (c) 2022 - present, Yusuke Wada and Hono contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,325 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/acrylblends/acrylblends/main/docs/assets/acrylblends-logo.png" alt="ACRYLBLENDS" width="120">
+</p>
+
+<h1 align="center">acrylblends</h1>
+
+<p align="center"><strong>Acryl, a small web framework on Web Standards, for Node.js.</strong><br>
+One <code>Request</code> in, one <code>Response</code> out: routing, middleware, validation, a typed client and a Node.js server, with no dependencies.</p>
+
+<p align="center">
+  <a href="https://github.com/acryldev/acryl/blob/main/docs/framework/README.md">Documentation</a> ·
+  <a href="https://github.com/acryldev/acryl/blob/main/docs/framework/getting-started/basic.md">Getting started</a> ·
+  <a href="https://github.com/acryldev/acryl/blob/main/docs/framework/api/index.md">API</a> ·
+  <a href="https://acrylblends.github.io">acrylblends.github.io</a> ·
+  <a href="https://acryl.dev">acryl.dev</a> ·
+  <a href="https://github.com/acrylblends/acrylblends">GitHub</a>
+</p>
+
+---
+
+```ts
+import { Acryl } from 'acrylblends'
+
+const app = new Acryl()
+app.get('/', (c) => c.text('Hello Acryl!'))
+
+export default app
+```
+
+## Contents
+
+- [Requirements](#requirements)
+- [Quick start](#quick-start)
+- [Start from a template](#start-from-a-template)
+- [A first API](#a-first-api)
+- [Middleware](#middleware)
+- [Validation](#validation)
+- [Typed client](#typed-client)
+- [Testing](#testing)
+- [Serving on Node.js](#serving-on-nodejs)
+- [What is in the package](#what-is-in-the-package)
+- [Upgrading from 0.4](#upgrading-from-04)
+- [The acrylblends command](#the-acrylblends-command)
+- [Links](#links)
+- [License](#license)
+
+## Requirements
+
+- **Node.js 22.19 or newer.** Node.js is the verified runtime, and it runs `.ts` files directly, so there is no build step.
+- **Bun** runs the same app (`export default app`) and is experimental.
+- `acrylblends` has no dependencies. Its types need only Node's types (`@types/node`), not the DOM library.
+
+## Quick start
+
+Create a folder and install the package:
+
+```sh
+mkdir my-app && cd my-app
+npm init -y
+npm pkg set type=module
+npm install acrylblends
+```
+
+Write the app in `index.ts`:
+
+```ts
+import { Acryl } from 'acrylblends'
+
+const app = new Acryl()
+
+app.get('/', (c) => c.text('Hello Acryl!'))
+
+export default app
+```
+
+Serve it on Node.js with the adapter in `server.ts`:
+
+```ts
+import { serve } from 'acrylblends/node-server'
+import app from './index.ts'
+
+serve({ fetch: app.fetch, port: 3000 }, (info) => {
+  console.log(`Listening on http://localhost:${info.port}`)
+})
+```
+
+Run it and open http://localhost:3000:
+
+```sh
+node server.ts
+```
+
+For Bun, `bun run index.ts` serves the same `export default app`.
+
+## Start from a template
+
+`create-acrylblends` creates a ready project with `dev`, `test` and `start` scripts:
+
+```sh
+npm create acrylblends@latest my-app
+cd my-app
+npm install
+npm run dev
+```
+
+The `nodejs` template is a minimal Acryl app. `bun` is the same for Bun (experimental). `acryl-app` is a Cordis app built from plugins,
+with an agent that can extend it while it runs. See the
+[create-acrylblends guide](https://github.com/acryldev/acryl/blob/main/docs/framework/guides/create-acrylblends.md).
+
+## A first API
+
+```ts
+import { Acryl } from 'acrylblends'
+import { HTTPException } from 'acrylblends/http-exception'
+
+type Book = { id: string, title: string }
+const books = new Map<string, Book>()
+
+const app = new Acryl()
+
+app.get('/api/books', (c) => c.json([...books.values()]))
+
+app.get('/api/books/:id', (c) => {
+  const book = books.get(c.req.param('id'))
+  if (book === undefined) throw new HTTPException(404, { message: 'no such book' })
+  return c.json(book)
+})
+
+app.post('/api/books', async (c) => {
+  const { title } = await c.req.json<{ title: string }>()
+  const book = { id: crypto.randomUUID(), title }
+  books.set(book.id, book)
+  return c.json(book, 201)
+})
+
+app.notFound((c) => c.json({ error: 'not found' }, 404))
+app.onError((error, c) => error instanceof HTTPException ? error.getResponse() : c.json({ error: 'internal error' }, 500))
+
+export default app
+```
+
+Read more: [Routing](https://github.com/acryldev/acryl/blob/main/docs/framework/api/routing.md),
+[Context](https://github.com/acryldev/acryl/blob/main/docs/framework/api/context.md),
+[Request](https://github.com/acryldev/acryl/blob/main/docs/framework/api/request.md),
+[Exceptions](https://github.com/acryldev/acryl/blob/main/docs/framework/api/exception.md).
+
+## Middleware
+
+Each built-in middleware has its own subpath:
+
+```ts
+import { Acryl } from 'acrylblends'
+import { cors } from 'acrylblends/cors'
+import { logger } from 'acrylblends/logger'
+import { secureHeaders } from 'acrylblends/secure-headers'
+import { bearerAuth } from 'acrylblends/bearer-auth'
+
+const app = new Acryl()
+
+app.use(logger())
+app.use(secureHeaders())
+app.use('/api/*', cors())
+app.use('/admin/*', bearerAuth({ token: process.env.ADMIN_TOKEN ?? '' }))
+```
+
+Built in: `basic-auth`, `bearer-auth`, `body-limit`, `combine`, `compress`, `context-storage`, `cors`, `csrf`, `etag`, `ip-restriction`,
+`jwk`, `jwt`, `language`, `logger`, `method-not-allowed`, `method-override`, `powered-by`, `pretty-json`, `request-id`, `secure-headers`,
+`serve-static`, `timeout`, `timing`, `trailing-slash`, plus ACRYL's `loopback-only`. Each one is documented under
+[Middleware](https://github.com/acryldev/acryl/tree/main/docs/framework/middleware/builtin). To write your own, see the
+[middleware guide](https://github.com/acryldev/acryl/blob/main/docs/framework/guides/middleware.md).
+
+## Validation
+
+`acrylblends/validator` validates any part of a request: `json`, `form`, `query`, `param`, `header`, `cookie`. The validated value is typed
+in the handler:
+
+```ts
+import { Acryl } from 'acrylblends'
+import { validator } from 'acrylblends/validator'
+
+const app = new Acryl()
+
+app.post(
+  '/api/books',
+  validator('json', (value, c) => {
+    const title = (value as { title?: unknown }).title
+    if (typeof title !== 'string' || title === '') return c.json({ error: 'title is required' }, 400)
+    return { title }
+  }),
+  (c) => c.json({ title: c.req.valid('json').title }, 201),
+)
+```
+
+`acrylblends/schema-validator` drives the same validator with any [Standard Schema](https://standardschema.dev) library (Zod, Valibot,
+ArkType and others). See the [validation guide](https://github.com/acryldev/acryl/blob/main/docs/framework/guides/validation.md).
+
+## Typed client
+
+Export the app's type, and `acrylblends/client` calls its routes with typed paths, inputs and answers:
+
+```ts
+// api.ts
+import { Acryl } from 'acrylblends'
+
+const app = new Acryl().get('/api/hello', (c) => c.json({ message: 'Hello Acryl!' }))
+export type AppType = typeof app
+export default app
+```
+
+```ts
+// client.ts
+import { hc } from 'acrylblends/client'
+import type { AppType } from './api.ts'
+
+const client = hc<AppType>('http://localhost:3000')
+const answer = await client.api.hello.$get()
+console.log((await answer.json()).message)
+```
+
+See [RPC](https://github.com/acryldev/acryl/blob/main/docs/framework/guides/rpc.md).
+
+## Testing
+
+`app.request()` answers a request in process, with no server and no port, so tests need nothing else running:
+
+```ts
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import app from './index.ts'
+
+test('GET / says hello', async () => {
+  const response = await app.request('/')
+  assert.equal(response.status, 200)
+  assert.equal(await response.text(), 'Hello Acryl!')
+})
+```
+
+Run it with `node --test`. `acrylblends/testing` adds `testClient`, the typed client over `app.request()`. See the
+[testing guide](https://github.com/acryldev/acryl/blob/main/docs/framework/guides/testing.md).
+
+## Serving on Node.js
+
+`acrylblends/node-server` serves any Acryl app on Node's `http` module (or `http2` and `https` with `createServer`), streams bodies, aborts
+`c.req.raw.signal` when the client goes away, and serves files:
+
+```ts
+import { Acryl } from 'acrylblends'
+import { serve } from 'acrylblends/node-server'
+import { serveStatic } from 'acrylblends/node-server/serve-static'
+import { getConnInfo } from 'acrylblends/node-server/conninfo'
+
+const app = new Acryl()
+app.use('/static/*', serveStatic({ root: './' }))
+app.get('/ip', (c) => c.text(getConnInfo(c).remote.address ?? 'unknown'))
+
+const server = serve({ fetch: app.fetch, port: 3000, hostname: '127.0.0.1' })
+process.on('SIGTERM', () => { server.close() })
+```
+
+See [Node.js](https://github.com/acryldev/acryl/blob/main/docs/framework/getting-started/nodejs.md).
+
+## What is in the package
+
+| Import | What |
+| --- | --- |
+| `acrylblends` | `Acryl`, `Context`, `AcrylRequest`, and the types |
+| `acrylblends/<middleware>` | each built-in middleware, for example `acrylblends/cors` |
+| `acrylblends/validator`, `acrylblends/schema-validator` | request validation |
+| `acrylblends/client`, `acrylblends/testing` | the typed client and its in-process test version |
+| `acrylblends/accepts`, `adapter`, `cookie`, `factory`, `html`, `route`, `streaming`, `ws`, `conninfo` | helpers ([helpers docs](https://github.com/acryldev/acryl/tree/main/docs/framework/helpers)) |
+| `acrylblends/http-exception` | `HTTPException` |
+| `acrylblends/router/*` | the routers: `reg-exp-router`, `smart-router`, `trie-router`, `pattern-router`, `linear-router` ([routers](https://github.com/acryldev/acryl/blob/main/docs/framework/concepts/routers.md)) |
+| `acrylblends/utils/*` | the utilities the framework is built from |
+| `acrylblends/node-server` | `serve`, `createAdaptorServer`, `getRequestListener`; with `node-server/serve-static` and `node-server/conninfo` |
+
+Every subpath is listed in the package's `exports`. JSX, SSG, the cache, mount, proxy and dev helpers and other runtimes' adapters are
+being ported. The docs mark them "not yet available" until they ship
+([FAQ](https://github.com/acryldev/acryl/blob/main/docs/framework/guides/faq.md)).
+
+To extend the context's typed variables, augment the root module:
+
+```ts
+declare module 'acrylblends' {
+  interface ContextVariableMap {
+    user: string
+  }
+}
+```
+
+## Upgrading from 0.4
+
+From 0.5 the package's root is the framework. `App` and `AppRequest`, the 0.4 names, still work as deprecated aliases of `Acryl` and
+`AcrylRequest` for one release. The scaffolding API that was the root in 0.4 is now `acrylblends/cli`. See
+[Migration from 0.4](https://github.com/acryldev/acryl/blob/main/docs/framework/cordis/migration-from-0-4.md).
+
+## The acrylblends command
+
+The package also carries the `acrylblends` command. It scaffolds Cordis apps with ACRYL's plugins as code you own (instance, settings,
+plugins installed while the app runs, an agent that builds plugins, durable tasks, the app as data in `blend.yaml`, a save that refuses
+secrets):
+
+```sh
+npx acrylblends init my-app --agent -y
+cd my-app && npm install && npm run dev
+```
+
+See the [ACRYLBLENDS documentation](https://github.com/acrylblends/acrylblends/blob/main/docs/README.md) and
+[Acryl in a Cordis app](https://github.com/acryldev/acryl/blob/main/docs/framework/cordis/acryl-in-a-cordis-app.md).
+
+## Links
+
+| | |
+| --- | --- |
+| Framework documentation | https://github.com/acryldev/acryl/blob/main/docs/framework/README.md |
+| ACRYLBLENDS website | https://acrylblends.github.io |
+| ACRYL website | https://acryl.dev |
+| This package's source and issues | https://github.com/acrylblends/acrylblends ([issues](https://github.com/acrylblends/acrylblends/issues)) |
+| The framework's source | https://github.com/acryldev/acryl (`plugins/acryl-router`, `plugins/acryl-node-server`) |
+| For coding agents | https://github.com/acryldev/acryl/blob/main/docs/framework/agents/index.md |
+| npm | https://www.npmjs.com/package/acrylblends |
+
+## License
+
+MIT. Copyright (c) 2026 WebBoxes s.r.o. The framework is ported from MIT-licensed open-source projects. Their notices are kept in the
+package's `LICENSE` file.

package/docs/framework/README.md

@@ -1,63 +1,63 @@
-# ACRYL Framework
+# Acryl
 
-Status: 0.4.0 (spec 047, `specs/047-framework-port/plan.md`). The application core in `acryl-router` and the Node adapter in
-`acryl-node-server` are ported from a mature MIT web framework with their test suites; the Cordis plugins around them are ACRYL's own.
+Acryl is a small web framework built on Web Standards. You write handlers over the standard `Request` and `Response`, and the same application runs on Node.js (and, experimentally, Bun), and inside a Cordis app as a plugin that an agent can extend while it runs.
 
-The ACRYL Framework is the small, readable layer on top of Cordis that turns "a bunch of DSH packages" into building an agentic app. You
-write an ordinary `App` (routes, a `Context`, middleware with `next()`, validators and helpers on Web-standard `Request` and `Response`),
-and a Cordis plugin mounts it with `ctx.router.route(path, app)`.
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
 
-## The five rules
+app.get('/', (c) => c.text('Acryl!'))
 
-1. **Everything extensible is a Cordis plugin.**
-2. **One application, several surfaces** - share capabilities and contracts, not necessarily the transport.
-3. **One declared contract per plugin** - what it provides, needs, and registers (routes, commands, tools, slots).
-4. **Every registration is reversible** - unloading a plugin removes what it owns.
-5. **Conventions are explicit and small** - an ordinary feature needs no knowledge of runtime internals.
+export default app
+```
 
-## What it gives you
+## Quick Start
 
-One handler, every surface. A plugin writes a handler once; Web and Desktop reach it over HTTP (Desktop's window talks to the app's own
-loopback server), the terminal UI and tests call it in process with `ctx.router.request(path)`, and a standalone process serves it with
-`acryl-node-server`. The universal entry point is `ctx.router.fetch(request)`.
+```sh
+npm create acrylblends@latest my-app
+```
 
-## Documentation map
+Other package managers work the same way: `pnpm create acrylblends@latest`, `yarn create acrylblends`, `bun create acrylblends@latest`.
+The starter asks which template you want (`nodejs`, `bun` (experimental), or `acryl-app`, a Cordis app with an agent). See [Getting started](getting-started/basic.md).
 
-| Topic | Page |
-| --- | --- |
-| First application | [Getting started](./getting-started.md) |
-| Every everyday call on one page | [API summary](./api-summary.md) |
-| Framework model | [Core concepts](./concepts.md) |
-| Routes and mounting | [Routing and mounting](./routing.md) |
-| Handler context | [Context](./context.md) |
-| Reading requests | [Request](./request.md) |
-| Cross-cutting behavior, and the built-in list | [Middleware](./middleware.md) |
-| Input checking | [Validation](./validation.md) |
-| Streaming, cookies, testing and the rest | [Helpers](./helpers.md) |
-| Serving without the ACRYL Host | [Node server](./node-server.md) |
-| Cordis ownership and service state | [Plugin lifecycle and disposal](./plugin-lifecycle.md) |
-| The application surfaces | [Surfaces and adapters](./surfaces.md) |
-| Leaving the DSH server | [Migration from the DSH webServer](./migration-from-dsh-webserver.md) |
-| Moving from 0.3 | [Migration from 0.3](./migration-from-0-3.md) |
-
-[ACRYL Blends](https://acrylblends.github.io/) is the product-facing guide for building and publishing complete applications. The
-framework pages here are the API and integration reference behind those guides. The mirrored developer documentation is published at
-[acryl.dev/docs](https://acryl.dev/docs).
-
-## The packages
-
-| Package | What it is |
+## What is in the box
+
+- **Routing** with several routers behind one API: `RegExpRouter`, `TrieRouter`, `SmartRouter` (the default, which chooses between them), `LinearRouter` and `PatternRouter`.
+  See [Routers](concepts/routers.md) and [Routing](api/routing.md).
+- **Web Standards only.** Handlers receive a `Context` over `Request` and return `Response`, with no runtime-specific objects. See [Web Standards](concepts/web-standard.md).
+- **Built-in middleware** for authentication, CORS, CSRF, compression, ETag, logging, request ids, secure headers, timeouts and more.
+  See [Built-in middleware](middleware/builtin/basic-auth.md) and [Middleware](concepts/middleware.md).
+- **Helpers** for cookies, streaming and server-sent events, content negotiation, HTML templates, WebSockets and testing. See [Helpers](guides/helpers.md).
+- **Typed routes and a typed client.** Route types flow from the server to `acrylblends/client`. See [RPC](guides/rpc.md).
+- **Validation** with a validator function or any Standard Schema library. See [Validation](guides/validation.md).
+- **A Cordis plugin around it.** A plugin mounts an app with `ctx.router.route`, the mount goes away when the plugin unloads, and a coding agent can write such plugins
+  into a running app. See [Acryl in a Cordis app](cordis/acryl-in-a-cordis-app.md) and [Agents](agents/index.md).
+
+## Runtimes
+
+Verified: Node.js. Bun is experimental. The other runtimes the framework could target are listed on [Other runtimes](getting-started/other-runtimes.md) as not yet verified.
+
+## Not yet available
+
+Some parts of the documented API surface are not part of the package yet, and their pages say so at the top: the JSX packages, static site generation, the CSS helper, the
+`proxy`, `dev` and `cache` pieces, the `quick` and `tiny` presets and the adapters of the runtimes other than Node.js. They are enabled as they are ported.
+
+## Where to read next
+
+| I want to | Read |
 | --- | --- |
-| `acryl-router` | `App` and the whole application API; the Cordis `router` service that composes the mounted apps; `acryl-router/middleware`, `acryl-router/helpers`, `acryl-router/client` |
-| `acryl-router-http` | inside the ACRYL Host: `ctx.routerHttp.mount(prefix)` serves a prefix of the router on the Host's web server |
-| `acryl-node-server` | without the Host: one `node:http` server for the whole router, `ctx.nodeServer.url`, and `serveStatic` |
-| `acryl-state` | observable cells shared by every surface, with read-only HTTP and SSE routes and `useCell` for React |
-| `acryl-inspect` | what each plugin requires, provides and mounts, read from the running system |
+| Run something in five minutes | [Getting started](getting-started/basic.md) |
+| Look up a call | [API](api/index.md), [Routing](api/routing.md), [Context](api/context.md), [Request](api/request.md), [API summary](api/summary.md) |
+| Understand the design | [Concepts](concepts/motivation.md) |
+| Copy a pattern | [Guides](guides/best-practices.md), [Validation](guides/validation.md), [Testing](guides/testing.md) |
+| Use Acryl inside a Cordis app | [Acryl in a Cordis app](cordis/acryl-in-a-cordis-app.md), [Plugin lifecycle](cordis/plugin-lifecycle.md), [Mounting](cordis/mounting.md) |
+| Move from the 0.3 router calls | [Migration from 0.3](cordis/migration-from-0-3.md) |
+| Move from the 0.4 names (`App`) | [Migration from 0.4](cordis/migration-from-0-4.md) |
 
-An app's `tsconfig.json` can extend `acryl-router/tsconfig.app.json` (ES2024 with the DOM types, strict).
+The license of these pages and of the framework source they describe is in [LICENSE](LICENSE).
 
-## Why this exists
+## TypeScript in a Cordis app
 
-DSH changes fast and stays one optional agent inside ACRYL. Cordis is the lifecycle ACRYL keeps across Web (browser), Desktop (Electron)
-and the terminal UI. HTTP used to go through DSH's `webServer` - a `node:http` route table with no middleware and no Web-standard
-`Request`/`Response` - which the terminal UI cannot reuse. The framework removes that coupling.
+An app's `tsconfig.json` can extend `acryl-router/tsconfig.app.json` (ES2024 with the DOM types, strict). The DOM types are optional: every
+entry point's types also stand with only `"lib": ["ES2024"]` and `"types": ["node"]`, the setting a Host-only plugin uses so browser globals
+do not typecheck in server code (the router's `tests/no-dom` fixture checks this on every typecheck).

package/docs/framework/UPSTREAM.md

@@ -1,3 +1,3 @@
 # Generated copy
 
-This folder is a copy of `docs/framework` of acryldev/acryl at commit `64e7c9d2e787f74b2da82492644fbbb46a601074`, made by `scripts/sync-framework.mjs`. Do not edit it here: change the text in ACRYL and sync again. `pnpm run verify:framework` fails when a page differs from the recorded digest.
+This folder is a copy of `docs/framework` of acryldev/acryl at commit `5743482e4199ded676a77f594bce15fd4aa0ca2f`, made by `scripts/sync-framework.mjs`. Do not edit it here: change the text in ACRYL and sync again. `pnpm run verify:framework` fails when a page differs from the recorded digest.

package/docs/framework/agents/index.md

@@ -0,0 +1,24 @@
+# Agents
+
+A coding agent (Claude Code, Codex, OpenCode, Copilot and others) builds on Acryl best when the documentation is in the folder it works in. A project created with
+`npm create acrylblends@latest` (and one made with `npx acrylblends init`) therefore contains:
+
+- `docs/framework/`: these pages. Start at `README.md`; `api/summary.md` is the one-page summary of the API.
+- `AGENTS.md`: where the API is, how a feature is built (an `Acryl` app mounted with `ctx.router.route`, a plugin registered in `src/app.ts` and `blend.yaml`, a state cell),
+  the things that surprise people, and what must pass before a task is done (`npm test` and `npm run check`).
+- `CLAUDE.md`: one line, `@AGENTS.md`, so tools that read `CLAUDE.md` read the same guide.
+
+## What an agent can do inside a running app
+
+The `acryl-app` template (a Cordis app) also lets an agent change the app while it runs:
+
+1. The agent writes a plugin into `extensions/<name>/index.ts`. The plugin may import `acrylblends` and the other subpaths by name.
+2. The app installs it as a child plugin, runs its `check(ctx)` with the plugin's own context, and keeps the previous version if the new one fails to start or to pass its check.
+3. A plugin's routes are an `Acryl` app mounted with `ctx.router.route`, so removing the plugin removes its routes.
+
+See [Acryl in a Cordis app](../cordis/acryl-in-a-cordis-app.md), [Plugin lifecycle](../cordis/plugin-lifecycle.md) and [Mounting](../cordis/mounting.md).
+
+## Checking that an agent can use the docs
+
+The repository has a manual gate: it creates a fresh app, starts a headless coding agent inside it with a one-line task (for example "add a /customers/count route with a test"),
+and checks that the app's tests and type-check pass afterwards and that the route answers.