acrylblends 0.4.1 → 0.5.0

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/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 `f5151e7f0c4de3b81bddb5cc686b5ef329e48e1c`, 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.

package/docs/framework/api/acryl.md

@@ -0,0 +1,259 @@
+# App - Acryl
+
+`Acryl` is the primary object.
+It will be imported first and used until the end.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+
+const app = new Acryl()
+//...
+
+export default app // for Cloudflare Workers or Bun
+```
+
+## Methods
+
+An instance of `Acryl` has the following methods.
+
+- app.**HTTP_METHOD**(\[path,\]handler|middleware...)
+- app.**all**(\[path,\]handler|middleware...)
+- app.**on**(method|method[], path|path[], handler|middleware...)
+- app.**use**(\[path,\]middleware)
+- app.**route**(path, \[app\])
+- app.**basePath**(path)
+- app.**notFound**(handler)
+- app.**onError**(err, handler)
+- app.**mount**(path, anotherApp, \[options\])
+- app.**fire**()
+- app.**fetch**(request, env, event)
+- app.**request**(path, options)
+
+The first part of them is used for routing, please refer to the [routing section](routing.md).
+
+## Not Found
+
+`app.notFound` allows you to customize a Not Found Response.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+// ---cut---
+app.notFound((c) => {
+  return c.text('Custom 404 Message', 404)
+})
+```
+
+> **Warning.** The `notFound` method is only called from the top-level app. For more information, see this issue.
+
+## Error Handling
+
+`app.onError` allows you to handle uncaught errors and return a custom Response.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+// ---cut---
+app.onError((err, c) => {
+  console.error(`${err}`)
+  return c.text('Custom Error Message', 500)
+})
+```
+
+> **Note.** If both a parent app and its routes have `onError` handlers, the route-level handlers get priority.
+
+## fire()
+
+> **Warning.** **`app.fire()` is deprecated**. Use `fire()` from `acrylblends/service-worker` instead. See the Service Worker documentation for details.
+
+`app.fire()` automatically adds a global `fetch` event listener.
+
+This can be useful for environments that adhere to the [Service Worker API](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API), such as [non-ES module Cloudflare Workers](https://developers.cloudflare.com/workers/reference/migrate-to-module-workers/).
+
+`app.fire()` executes the following for you:
+
+```ts
+addEventListener('fetch', (event: FetchEventLike): void => {
+  event.respondWith(this.dispatch(...))
+})
+```
+
+## fetch()
+
+`app.fetch` will be the entry point of your application.
+
+For Cloudflare Workers, you can use the following:
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+type Env = any
+type ExecutionContext = any
+// ---cut---
+export default {
+  fetch(request: Request, env: Env, ctx: ExecutionContext) {
+    return app.fetch(request, env, ctx)
+  },
+}
+```
+
+or just do:
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+// ---cut---
+export default app
+```
+
+Bun:
+
+<!-- prettier-ignore -->
+```ts
+export default {
+  port: 3000,
+  fetch: app.fetch,
+}
+```
+
+## request()
+
+`request` is a useful method for testing.
+
+You can pass a URL or pathname to send a GET request.
+`app` will return a `Response` object.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+declare const test: (name: string, fn: () => void) => void
+declare const expect: (value: any) => any
+// ---cut---
+test('GET /hello is ok', async () => {
+  const res = await app.request('/hello')
+  expect(res.status).toBe(200)
+})
+```
+
+You can also pass a `Request` object:
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+declare const test: (name: string, fn: () => void) => void
+declare const expect: (value: any) => any
+// ---cut---
+test('POST /message is ok', async () => {
+  const req = new Request('Hello!', {
+    method: 'POST',
+  })
+  const res = await app.request(req)
+  expect(res.status).toBe(201)
+})
+```
+
+## mount()
+
+> **Warning.** **`app.mount()` is deprecated**. Use the [Mount Middleware](../middleware/builtin/mount.md) instead.
+
+The `mount()` allows you to mount applications built with other frameworks into your Acryl application.
+
+```ts
+import { Router as IttyRouter } from 'itty-router'
+import { Acryl } from 'acrylblends'
+
+// Create itty-router application
+const ittyRouter = IttyRouter()
+
+// Handle `GET /itty-router/hello`
+ittyRouter.get('/hello', () => new Response('Hello from itty-router'))
+
+// Acryl application
+const app = new Acryl()
+
+// Mount!
+app.mount('/itty-router', ittyRouter.handle)
+```
+
+By default, `mount()` passes a new `Request` with the mount path removed from its URL. Provide a `replaceRequest` function to control which `Request` is passed to the mounted application:
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+const handler = (request: Request) => new Response(request.url)
+// ---cut---
+app.mount('/app', handler, {
+  replaceRequest: (originalRequest) => originalRequest,
+})
+```
+
+To pass the original `Request` unchanged, set `replaceRequest` to `false` as a shorthand for the function above:
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+const handler = (request: Request) => new Response(request.url)
+// ---cut---
+app.mount('/app', handler, {
+  replaceRequest: false,
+})
+```
+
+## strict mode
+
+Strict mode defaults to `true` and distinguishes the following routes.
+
+- `/hello`
+- `/hello/`
+
+`app.get('/hello')` will not match `GET /hello/`.
+
+By setting strict mode to `false`, both paths will be treated equally.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+// ---cut---
+const app = new Acryl({ strict: false })
+```
+
+## router option
+
+The `router` option specifies which router to use. The default router is `SmartRouter`. If you want to use `RegExpRouter`, pass it to a new `Acryl` instance:
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+// ---cut---
+import { RegExpRouter } from 'acrylblends/router/reg-exp-router'
+
+const app = new Acryl({ router: new RegExpRouter() })
+```
+
+## Generics
+
+You can pass Generics to specify the types of Cloudflare Workers Bindings and variables used in `c.set`/`c.get`.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+type User = any
+declare const user: User
+// ---cut---
+type Bindings = {
+  TOKEN: string
+}
+
+type Variables = {
+  user: User
+}
+
+const app = new Acryl<{
+  Bindings: Bindings
+  Variables: Variables
+}>()
+
+app.use('/auth/*', async (c, next) => {
+  const token = c.env.TOKEN // token is `string`
+  // ...
+  c.set('user', user) // user should be `User`
+  await next()
+})
+```