acrylblends 0.4.0 → 0.4.1

package/docs/framework/migration-from-dsh-webserver.md

@@ -0,0 +1,103 @@
+# 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.
+
+## Before and after
+
+Before, a plugin claims a path and writes the Node response itself:
+
+```ts
+export function apply(ctx: Context): void {
+  ctx.effect(() => ctx.acrylWeb.register({
+    kind: 'exact',
+    path: '/api/health',
+    handler: (req, res) => {
+      res.statusCode = 200
+      res.setHeader('content-type', 'application/json')
+      res.end(JSON.stringify({ ok: true }))
+    },
+  }))
+}
+```
+
+After, it builds an app, mounts it, and asks the Host adapter to serve the prefix:
+
+```ts
+import { App } from 'acryl-router'
+
+export const inject = ['router']
+
+export function apply(ctx: Context): void {
+  const app = new App().get('/health', c => c.json({ ok: true }))
+  ctx.router.route('/api', app)
+  ctx.inject(['routerHttp'], inner => { inner.routerHttp.mount('/api/health') })
+}
+```
+
+`routerHttp.mount(prefix)` claims the prefix on the same web server, so the public path does not change. The terminal UI and tests reach
+the route in process (`ctx.router.request('/api/health')`), which the old handler never allowed.
+
+## What maps to what
+
+| 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 |
+| `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 |
+| `res.statusCode`, `res.setHeader`, `res.end` | `c.json`, `c.text`, `c.body`, `c.header`, or a returned `Response` |
+| `req.socket.remoteAddress` | `connectionOf(c)` / `getConnInfo(c)` |
+| a peer or origin check copied into each handler | `loopbackOnly`, `cors`, `csrf` or a middleware of your own |
+| the disposer returned by `register` | nothing: `route` and `mount` belong to the calling plugin |
+
+## Migration steps
+
+Move one capability at a time:
+
+1. Build an `App` 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
+   away and comes back once.
+
+Keep domain calls unchanged until the transport change is green; do not rewrite transport, handlers and authorization in one step.
+
+## A worked example: the workspace
+
+`acryl-workspace` (files, git, terminals, projects, agents) was the largest user of the webServer: 24 exact routes. It now builds one app
+per domain folder (`filesRoutes`, `gitRoutes`, `ptyRoutes`, ...), composes them once (`privateApi` in `src/private-route.ts`), mounts the
+result after the effect that builds its services, and serves the one prefix `/api/acryl-workspace`:
+
+```ts
+const built: { api?: App } = {}
+ctx.effect(() => {
+  // ... the PTY table, git, files, the project registry ...
+  built.api = privateApi(filesRoutes(files, report), gitRoutes(git, report) /* , ... */)
+  return async () => { /* release them */ }
+})
+ctx.router.route('/', built.api)
+ctx.routerHttp.mount('/api/acryl-workspace')
+```
+
+Mounting after the effect orders the unload: the mount goes first, so the requests and event streams its code is serving end and are
+waited for, then the services are released. Each route names its guard (`loopbackOnly({ callers: 'own-page' })` for the page, a bearer token
+for the agent hooks) and its body limit; the event stream is `streamSSE`, and its keep-alive is one timer the plugin owns, not one per
+request. The terminal's WebSocket stays a webServer upgrade until the router carries upgrades (spec 047 T009).
+
+The answers that changed are recorded with it: a body over a route's limit is 413 on every route (some said 400); a wrong method is 405 with
+an `Allow` header on every route; a missing or wrong agent-hook token is 401 with `WWW-Authenticate` (it was 403); and the hook's `Host`
+must be the app's own loopback address. Its routes refuse an in-process call on purpose (the guard needs a socket to check), so its tests
+run over loopback through the same adapter (`tests/serve-api.ts`), which is the "test over the Host" below.
+
+## Completion check
+
+A capability is migrated when:
+
+- no handler in it touches Node `req` / `res` objects or the old server types;
+- its public paths and answers are unchanged, or the changes are recorded;
+- it unloads and reloads without duplicate or missing routes;
+- the same handler passes an in-process test and a test over the Host.
+
+Typed RPC stays a separate concern. Do not convert RPC methods because their names look like HTTP routes.

package/docs/framework/node-server.md

@@ -0,0 +1,75 @@
+# Node server
+
+`acryl-node-server` serves the whole router over HTTP from a standalone Node.js process. Use it for an app that runs without the ACRYL
+Host. Inside the Host (Web and Desktop), the Host owns the web server and a plugin asks `acryl-router-http` to serve its prefix instead.
+
+## Serve the router
+
+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 todo from './todo.ts'
+
+const root = new Context()
+root.plugin(router)
+root.plugin(nodeServer, { port: 3000 })
+root.plugin(todo)
+
+root.inject(['nodeServer'], ctx => {
+  console.log(`listening on ${ctx.nodeServer.url}`)
+})
+```
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `hostname` | `127.0.0.1` | address to bind; binding elsewhere exposes the app to the network |
+| `port` | `0` | port to listen on; 0 lets the system choose |
+| `scan` | `20` | how many further ports to try when the configured one is taken |
+
+The plugin becomes active once the server listens, so a plugin that injects `nodeServer` can rely on `ctx.nodeServer.url` and
+`ctx.nodeServer.port`. A failure to bind fails the plugin.
+
+Every request goes to `ctx.router.fetch`, so routes appear and disappear as plugins mount and unload, with no restart. A plugin's
+`ctx.inject(['routerHttp'], ...)` call never fires here: this adapter serves every prefix already.
+
+## Connection information
+
+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).
+
+## Static files
+
+The Node `serveStatic` reads files from disk:
+
+```ts
+import { serveStatic } from 'acryl-node-server'
+
+const app = new App()
+  .use('/assets/*', serveStatic({ root: './public' }))
+  .get('/', serveStatic({ path: './public/index.html' }))
+```
+
+`root` is joined with the request path, relative to the working directory unless absolute. A request path with a `.` or `..` segment, a
+doubled slash, a backslash or (unless `allowPercentInPath`) an encoded `%` is treated as not found and passed on with `next()`. Only `GET`
+and `HEAD` are served. Other options: `rewriteRequestPath`, `precompressed` (serve a `.br`, `.zst` or `.gz` sibling when the client
+accepts it), `index` (default `index.html`), and `onFound` / `onNotFound` hooks. Serve build output, never source folders.
+
+## Shutdown
+
+Disposing the plugin (or the root context) ends open streams, closes every connection and returns once the port is free. Disposing a
+plugin that only mounted routes is different: its mount and the requests it is serving end, and the server keeps serving the others (see
+[Plugin lifecycle](./plugin-lifecycle.md#disposal-sequence)).
+
+## Choosing a port
+
+Let the process configuration choose the address. Do not hard-code a development port in a reusable plugin: a plugin mounts routes and
+leaves the socket to whichever adapter the app runs with.
+
+## Not yet supported
+
+WebSocket upgrades under the router are a later task. The adapter's own WebSocket support exists in `src/adapter/` with its tests but is
+not wired to the router yet.

package/docs/framework/plugin-lifecycle.md

@@ -0,0 +1,111 @@
+# Plugin lifecycle and disposal
+
+Cordis gives every framework registration an owner and a lifetime. This is the main difference between using the application API on its
+own and using it as part of ACRYL.
+
+## Every registration has an owner
+
+```ts
+export const name = 'todo'
+export const inject = ['router']
+
+export function apply(ctx: Context): void {
+  ctx.router.route('/todo', createTodoApp())
+}
+```
+
+`route`, `onError` and `notFound` register themselves as effects of the plugin that called them, so there is nothing to wrap: when the
+plugin's fiber unloads, its mount goes away, and a reload mounts it again without duplicates. `route` returns a function that removes the
+mount sooner. Never register routes as a side effect of importing a module.
+
+Resources an app uses (timers, watchers, connections, subprocesses) belong to one `ctx.effect()` of the plugin, whose disposer releases
+them:
+
+```ts
+export function apply(ctx: Context): void {
+  const events = new EventEmitter()
+  ctx.effect(() => {
+    const timer = setInterval(() => events.emit('tick'), 1000)
+    return () => clearInterval(timer)
+  }, 'todo: ticker')
+  ctx.router.route('/todo', createTodoApp(events))
+}
+```
+
+## Live composition
+
+The router is built for a host whose plugin set changes while it runs. Mounts are added and removed, and each request after a change is
+served by an app composed from the mounts that are live at that time; a request already running keeps the app it started with. The core's
+route tables only grow, so the router rebuilds the composition instead of editing it. Application code does not manage this.
+
+A mount is a snapshot of the app's routes at the `route` call. Build the app, then mount it.
+
+## Missing providers
+
+A plugin that injects `router` stays PENDING while no router exists. That is a normal Cordis state, not an error: when a router appears the
+plugin activates and mounts. When the router is replaced, the plugin unloads and activates again against the new one, so it must not keep
+the old service object anywhere else.
+
+## Disposal sequence
+
+When a plugin that owns a mount unloads:
+
+1. The mount leaves the composition, so new requests no longer reach it.
+2. The requests its code is still serving end: a request inside one of its handlers or middleware (before `next()` returned), and a
+   response body one of its handlers produced. Their signals abort (`c.req.raw.signal`) and their bodies are cancelled, which runs the
+   stream helpers' `onAbort`.
+3. The unload waits for those requests, their bodies and their `c.executionCtx.waitUntil` work, bounded by the router's `disposeGraceMs`.
+
+A request the plugin's middleware already passed on to another plugin's handler is not touched. When the router itself is disposed, the
+same happens to every running request, and new requests are answered with 503.
+
+Handlers get a chance to release their resources, nothing a plugin started outlives it, and disposal cannot hang forever.
+
+## Services and the shadow context
+
+A plugin reaches a service through its own view of it: `ctx.router` in one plugin and in another are two different objects over one
+service. Two facts follow, each with a test as proof.
+
+**Fields are shared.** Reading or assigning a service's field through any plugin's view reads or writes the one instance, so every caller
+sees the same value (`plugins/acryl-router/tests/shadow-state.spec.ts`). Keeping changing state in one object, as the router does, is a
+readability choice, not a requirement.
+
+**`this.ctx` inside a method is the caller's view, not the service's own context.** It is what lets `route` tie a mount to the plugin
+that called it. It is the wrong context for starting something that should belong to the service: a plugin started with
+`this.ctx.plugin(...)` from a method resolves services as the service's own fiber and fails with "cannot get property router without
+inject". Keep the context the constructor received and use that:
+
+```ts
+class Installer extends Service {
+  private readonly owner: Context
+
+  constructor(ctx: Context) {
+    super(ctx, 'installer')
+    this.owner = ctx                  // the service's own context
+  }
+
+  async install(plugin: Plugin): Promise<void> {
+    await this.owner.plugin(plugin)   // right: behaves like a plugin mounted at startup
+    // await this.ctx.plugin(plugin)  // wrong: the caller's view, see above
+  }
+}
+```
+
+The proof is `plugins/acryl-router/tests/live-install.spec.ts`, which runs both forms against a live router. This sits next to the general
+rule: a plugin started with `this.ctx.plugin(...)` in `apply` is a child of the plugin and unloads with it.
+
+## Module state
+
+Do not hide mutable state in module globals. Cordis can reload a plugin and run several surfaces from one host, and a module global
+outlives the plugin that wrote it.
+
+## What to test
+
+Test a route-owning plugin through real Cordis activation for:
+
+- activation when the router is present, and PENDING until it appears;
+- route removal after the plugin unloads, and a clean mount after reload, without duplicates over repeated cycles;
+- router replacement without stale service references;
+- disposal while a response is still open.
+
+`app.request` tests prove handler behavior. Only activation tests prove ownership.

package/docs/framework/request.md

@@ -0,0 +1,106 @@
+# Request
+
+Handlers read input through `c.req`, a thin wrapper around the Web `Request`. The original is `c.req.raw`.
+
+## Route parameters
+
+```ts
+app.get('/entry/:id', c => {
+  const id = c.req.param('id')
+  return c.json({ id })
+})
+
+app.get('/entry/:id/comment/:commentId', c => {
+  const { id, commentId } = c.req.param()
+  return c.json({ id, commentId })
+})
+```
+
+Named reads keep route contracts visible; read the whole map only when a generic logger or adapter needs it.
+
+## Query strings
+
+```ts
+const page = c.req.query('page')     // one value
+const all = c.req.query()            // every parameter, first value of each
+const tags = c.req.queries('tag')    // repeated values: ?tag=work&tag=home
+```
+
+Convert strings to numbers, booleans or dates at the application boundary and reject invalid values explicitly; a validator does both
+(see [Validation](./validation.md)).
+
+## Headers
+
+```ts
+const requestId = c.req.header('X-Request-Id')
+const headers = c.req.header()        // every header, keys in lowercase
+```
+
+Header names are case-insensitive for a named read. With no argument the record's keys are lowercase, so `c.req.header()['X-Foo']` is
+always undefined; read `c.req.header('X-Foo')` instead. Optional headers need a deliberate fallback; do not let a missing authentication
+header silently become an anonymous request unless that is the declared behavior.
+
+## Bodies
+
+```ts
+app.post('/entry', async c => {
+  const body = await c.req.json()       // application/json
+  return c.json({ received: body }, 201)
+})
+
+await c.req.text()
+await c.req.arrayBuffer()
+await c.req.blob()
+await c.req.formData()
+await c.req.parseBody()                 // multipart/form-data or application/x-www-form-urlencoded
+```
+
+The reads are cached, so a validator and the handler can both read the body. Read untrusted bodies behind `bodyLimit`, which refuses a body
+over the limit with 413 while it streams instead of after buffering it.
+
+### Forms and uploads
+
+`parseBody()` returns `string | File` per field; the last one wins when a name repeats:
+
+```ts
+const body = await c.req.parseBody()
+body['file']                                       // string | File
+const many = await c.req.parseBody({ all: true })  // repeated names become arrays
+many['files']                                      // (string | File)[] when several were sent
+const nested = await c.req.parseBody({ dot: true }) // obj.key1 -> { obj: { key1 } }
+```
+
+A field named with a `[]` suffix (`files[]`) is always an array. Treat every uploaded file as untrusted: check its type, size and
+destination, and never use a caller-provided filename as a filesystem path without normalizing it and confining it to the intended
+directory.
+
+## Validated input
+
+`c.req.valid(target)` returns what a validator for `json`, `form`, `query`, `header`, `cookie` or `param` produced, typed by it. See
+[Validation](./validation.md).
+
+## Method, path and URL
+
+```ts
+c.req.method   // 'GET'
+c.req.path     // '/about/me'
+c.req.url      // 'http://127.0.0.1:3290/about/me'
+```
+
+Do not parse the URL by hand to recover route parameters or query values the router already exposes. `routePath(c)` and
+`matchedRoutes(c)` from `acryl-router/helpers` give the registered path and the routes that matched.
+
+## Raw Web Request
+
+```ts
+const raw = c.req.raw
+const url = new URL(raw.url)
+```
+
+Use the raw object for standards-based libraries, streaming bodies and signatures over the exact payload. Use `c.req` for normal
+application code.
+
+## Request cancellation
+
+`c.req.raw.signal` aborts when the client goes away, when the plugin serving the request unloads and when the router is
+disposed. Work that ignores it can outlive the plugin that owns it; see [Context](./context.md#cancellation-and-background-work).

package/docs/framework/routing.md

@@ -0,0 +1,188 @@
+# Routing and mounting
+
+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.
+
+## Mounting from Cordis
+
+A plugin mounts its app through the `router` service:
+
+```ts
+export const name = 'todo'
+export const inject = ['router']
+
+export function apply(ctx: Context): void {
+  const app = createTodoApp()
+  ctx.router.route('/todo', app)
+  ctx.inject(['routerHttp'], inner => { inner.routerHttp.mount('/todo') })
+}
+```
+
+- The mount is owned by the calling plugin: `route` registers it as that plugin's effect, so unloading the plugin removes it and a reload
+  mounts again without duplicates. The returned function removes it sooner.
+- `route` copies the app's routes at the call, like `app.route`; mount the app once it is complete.
+- Mounts run in the order they were made, so middleware an earlier mount registers for a path (`app.use('/todo/*', ...)` mounted at `/`)
+  wraps routes a later mount serves below it. Two plugins may mount on the same path: the first one's matching route answers, and when it
+  unloads the second takes over.
+- `ctx.router.route` is the only way to register with the router.
+- To be reachable over HTTP inside the ACRYL Host, ask the adapter to serve the prefix with `routerHttp.mount(prefix)` (an optional
+  dependency, hence the inner `ctx.inject`). A standalone `acryl-node-server` serves the whole router, so there the call is not needed.
+
+## Not found and errors
+
+An app's own error handler applies to that app's routes, also when the app is mounted:
+
+```ts
+app.onError((error, c) => {
+  console.error(error)
+  return c.json({ error: 'internal_error' }, 500)
+})
+```
+
+A mounted app's `app.notFound` is not used: a request no mount claims is answered by the router. A plugin can replace that answer, and
+the router's fallback error handler, once per router:
+
+```ts
+ctx.router.notFound(c => c.json({ error: 'not_found' }, 404))
+ctx.router.onError((error, c) => c.json({ error: 'internal_error' }, 500))
+```
+
+Without them, an `HTTPException` becomes its own response, an aborted request is a 499 and anything else is logged and becomes a 500.
+Return client errors from the handler that detected them (or throw an `HTTPException`); reserve `onError` for unexpected failures.
+
+## Trailing slashes
+
+`/a` and `/a/` are different paths by default. That surprises people most on a mount's root: an app mounted at `/orders` with a route
+`/` answers `/orders` and returns 404 on `/orders/`.
+
+What each choice does for an app mounted at `/orders` with routes `/` and `/:id`, measured on the router:
+
+| Choice | `/orders` | `/orders/` | `/orders/42` | `/orders/42/` |
+| --- | --- | --- | --- | --- |
+| 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 |
+
+- **`trimTrailingSlash()`** (from `acryl-router/middleware`) 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
+  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.
+
+## Testing routes
+
+```ts
+const response = await app.request('/todos/42')
+const body = await response.json()
+```
+
+Test both the application in isolation and at least one mounted route through the Cordis router. The second test proves the mount,
+prefix and disposal contract, not just handler logic.

package/docs/framework/surfaces.md

@@ -0,0 +1,71 @@
+# Surfaces and adapters
+
+An ACRYL application is written once and reached through the surface that fits the user. Surfaces provide transport and presentation;
+plugins provide capabilities.
+
+## Surface model
+
+| Surface | How requests arrive | Typical use |
+| --- | --- | --- |
+| Web | HTTP to the ACRYL Host's web server, through `acryl-router-http` | browser applications and APIs |
+| Desktop | the same Host web server on a loopback port, opened in the Electron window | local-first applications |
+| Terminal UI | in process: `ctx.router.request(...)` or `ctx.router.fetch(...)` | operator tools, agents, terminal workflows |
+| Standalone process | HTTP through `acryl-node-server` | an app that runs without the Host |
+| Tests | `ctx.router.request(...)` or `app.request(...)` | handler and contract tests |
+
+The handler does not know which row supplied the request. When it needs a transport fact it reads the connection from the context
+(`connectionOf(c)`), which is empty for an in-process call.
+
+## Web
+
+The Host owns the listening socket, the address and process shutdown. A plugin mounts its app on the router, then asks the adapter to
+serve the prefix over HTTP:
+
+```ts
+ctx.router.route('/todo', app)
+ctx.inject(['routerHttp'], inner => { inner.routerHttp.mount('/todo') })
+```
+
+Only prefixes asked for this way are served over HTTP. A prefix the Host's web server already serves cannot be claimed: `mount` throws,
+so a plugin cannot take over a Host route by mounting on it.
+
+## Desktop
+
+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)).
+
+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).
+
+Desktop capabilities such as windows, files and native dialogs belong in declared Cordis services. A handler calls the service; it does not
+import Electron.
+
+## Terminal UI
+
+A terminal surface needs no server. It calls the composed router in process:
+
+```ts
+const response = await ctx.router.request('/todo/todos')
+const todos = await response.json()
+```
+
+The `routerHttp` service does not exist there, so the plugin's `ctx.inject(['routerHttp'], ...)` simply never runs. Check the services a
+host declares instead of assuming a network route exists.
+
+## What belongs where
+
+| Concern | Owner |
+| --- | --- |
+| Route handlers and middleware | the feature plugin's `App` |
+| 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 |
+| Shared domain behavior | a domain service every surface uses |
+| Shared reactive state | `acryl-state` or an application service |
+
+## Loopback-only routes
+
+Some routes exist only for the local host, such as callbacks and control endpoints. Guard them with `loopbackOnly` at the framework
+boundary; do not rely on an obscure path or a missing link as access control. Loopback restriction is separate from authentication: a
+local route that does privileged work still needs the host's authorization policy.

package/docs/framework/upstream.json

@@ -0,0 +1,9 @@
+{
+  "source": {
+    "repo": "acryldev/acryl",
+    "path": "docs/framework",
+    "commit": "64e7c9d2e787f74b2da82492644fbbb46a601074"
+  },
+  "files": 16,
+  "digest": "sha256:f41321a2c2da4a9348634c9a6a6d7a62632d7c5906fbcba30479d569ef4bc6ef"
+}