acrylblends 0.3.0 → 0.4.1

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"
+}

package/docs/framework/validation.md

@@ -0,0 +1,135 @@
+# Validation
+
+Validate untrusted input at the route boundary. `schemaValidator` takes any [Standard Schema](https://standardschema.dev): Schemastery
+(the schema library Cordis already uses for plugin config), Zod and Valibot all implement it, so a route needs no extra dependency.
+
+## Validate JSON
+
+```ts
+import z from '@deepseek-ai/schemastery'
+import { App } from 'acryl-router'
+import { schemaValidator } from 'acryl-router/helpers'
+
+const NewTodo = z.object({
+  title: z.string().required(),
+  done: z.boolean().default(false),
+})
+
+const app = new App().post('/todos', schemaValidator('json', NewTodo), c => {
+  const todo = c.req.valid('json')   // typed by the schema's output
+  return c.json({ todo }, 201)
+})
+```
+
+A validated route has three parts: a schema for one input target, the validator middleware for that target, and a handler that reads
+`c.req.valid(target)` instead of the raw body.
+
+## Failures
+
+When the schema reports issues the handler does not run and the answer is 400 with `Content-Type: application/json` and exactly this
+shape:
+
+```ts
+{ error: `invalid ${target}`, issues: Array<{ message: string, path: string }> }
+```
+
+```json
+{ "error": "invalid json", "issues": [{ "message": "title must be 1 to 200 characters", "path": "title" }] }
+```
+
+- `error` names the target: `invalid json`, `invalid query`, `invalid param`, ...
+- There is one entry per issue the schema reported, in its order, with the schema's own `message`.
+- `path` is the issue's path joined with dots: `["items", 0, "title"]` becomes `"items.0.title"`, and a path segment given as
+  `{ key }` (as Standard Schema allows) contributes its `key`.
+- An issue without a path, which a hand-written Standard Schema often reports for a whole-value check, gets `"path": ""`.
+  `{ issues: [{ message: 'not allowed' }] }` answers `{ "error": "invalid json", "issues": [{ "message": "not allowed", "path": "" }] }`.
+  Give issues a path when a client should point at a field.
+
+### A JSON body without a JSON content type
+
+A `json` target reads the body only when the request's `Content-Type` is JSON (`application/json`, with or without parameters such as
+`; charset=utf-8`, or `application/*+json`). Any other content type, or none, is not an error by itself: the schema sees `{}`. So a
+client that forgets the header gets a misleading field error for a field it did send:
+
+```sh
+curl -X POST -d '{"title":"milk"}' http://127.0.0.1:<port>/todo/api      # no content type: curl sends a form type
+# 400 {"error":"invalid json","issues":[{"message":"title must be 1 to 200 characters","path":"title"}]}
+```
+
+If you see a field error for a field the request clearly carries, check the request's `Content-Type` first. A route that wants to say so
+explicitly can refuse other content types before the validator:
+
+```ts
+import type { MiddlewareHandler } from 'acryl-router'
+
+const jsonOnly: MiddlewareHandler = async (c, next) => {
+  // The same types the json target reads: application/json and application/*+json, parameters allowed.
+  const type = c.req.header('content-type')?.split(';', 1)[0]?.trim() ?? ''
+  if (!/^application\/([a-z.-]+\+)?json$/i.test(type)) return c.json({ error: 'content type must be JSON' }, 415)
+  await next()
+}
+
+app.post('/todos', jsonOnly, schemaValidator('json', NewTodo), createTodo)
+```
+
+### A body that is not JSON
+
+A JSON content type with a body that does not parse fails before the schema runs: the answer is 400 with the text body
+`Malformed JSON in request body` (a thrown `HTTPException`, so an `onError` handler can reshape it). The `form` target does the same for
+a form body that does not parse, with the text `Malformed FormData request.`
+
+Keep the public failure shape consistent across the application and do not leak internals in messages. An application that needs a
+different body writes its own check with the core `validator` (below). Valid input is not proof that the caller may use it:
+authentication and authorization stay separate checks.
+
+## Targets
+
+| Target | Read from |
+| --- | --- |
+| `json` | the JSON body |
+| `form` | a `multipart/form-data` or `application/x-www-form-urlencoded` body |
+| `query` | the query string |
+| `param` | route parameters |
+| `header` | request headers (names in lowercase) |
+| `cookie` | cookies |
+
+Validate only the targets the route uses, and chain one validator per target:
+
+```ts
+app.get('/todos/:id', schemaValidator('param', z.object({ id: z.natural() })), schemaValidator('query', Paging), handler)
+```
+
+## 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
+response to refuse:
+
+```ts
+import { validator } from 'acryl-router/helpers'
+
+app.post('/posts', validator('form', (value, c) => {
+  const body = value['body']
+  if (typeof body !== 'string') return c.text('Invalid!', 400)
+  return { body }
+}), c => c.json({ body: c.req.valid('form').body }, 201))
+```
+
+## Limit the body first
+
+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'
+
+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).
+
+## What not to validate twice
+
+Validate shape at the HTTP boundary, then enforce domain rules in the domain service. The route checks that `title` is a string; the
+todo service decides whether that title is allowed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acrylblends",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Scaffold Cordis apps: acrylblends init.",
   "license": "MIT",
   "type": "module",
@@ -20,7 +20,9 @@
     "bin",
     "dist",
     "templates",
-    "plugins"
+    "shared",
+    "plugins",
+    "docs"
   ],
   "scripts": {
     "build": "tsdown",

package/plugins/acryl-inspect/plugin.json

@@ -7,5 +7,6 @@
   "dependencies": {
     "@deepseek-ai/cordis": "4.0.4"
   },
-  "mount": "root.plugin(inspect); ctx.inspect.plugins(), ctx.inspect.explain('name'), ctx.inspect.render()"
+  "mount": "root.plugin(inspect); ctx.inspect.plugins(), ctx.inspect.explain('name'), ctx.inspect.render()",
+  "omit": ["**/*.test.*", "**/*.case.ts"]
 }

package/plugins/acryl-inspect/src/report.ts

@@ -36,10 +36,10 @@ export interface PluginReport {
   readonly requires: readonly string[]
   /** Services it provides. */
   readonly provides: readonly string[]
-  /** Routes it registered on the router. */
+  /** Paths it mounted an app under on the router. */
+  readonly mounts: readonly string[]
+  /** What those mounts serve; middleware and `all` routes show as method `ALL`, the way the core keeps them. */
   readonly routes: readonly RouteReport[]
-  /** Router middleware paths it registered. */
-  readonly middleware: readonly string[]
   /** Every other labeled registration (event listeners, timers, commands, tools). */
   readonly other: readonly string[]
   /** How many registrations disappear when it unloads: all of them. */
@@ -47,13 +47,19 @@ export interface PluginReport {
 }
 
 const PROVIDE = /^ctx\.provide\("(.+)"\)$/
-const ROUTE = /^acryl-router: (GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS|\*) (\/\S*)$/
-const USE = /^acryl-router: use (\/\S*)$/
+const MOUNT = /^acryl-router: route (\S+)$/
+const SERVES = /^acryl-router: serves ([A-Z]+) (\S+)$/
 
 function flatten(effects: readonly EffectLabel[]): string[] {
   return effects.flatMap(effect => [effect.label, ...flatten(effect.children)])
 }
 
+/** A mount's children name the routes it serves; they describe that one registration and are not registrations of their own. */
+function routeOf(label: string): RouteReport | undefined {
+  const served = SERVES.exec(label)
+  return served?.[1] !== undefined && served[2] !== undefined ? { method: served[1], path: served[2] } : undefined
+}
+
 export function stateName(state: number): FiberStateName {
   return STATE_NAMES[state] ?? 'FAILED'
 }
@@ -74,17 +80,19 @@ export function ownerOf(fiber: FiberView): FiberView {
 /** Describe one fiber, counting the registrations of the unnamed inline callbacks it owns (`adopted`) as its own. */
 export function reportFiber(fiber: FiberView, adopted: readonly FiberView[] = []): PluginReport {
   const provides: string[] = []
+  const mounts: string[] = []
   const routes: RouteReport[] = []
-  const middleware: string[] = []
   const other: string[] = []
   const labels = [fiber, ...adopted].flatMap(source => flatten(source.getEffects()))
+  let registrations = 0
   for (const label of labels) {
     const provided = PROVIDE.exec(label)
-    const route = ROUTE.exec(label)
-    const used = USE.exec(label)
+    const mount = MOUNT.exec(label)
+    const route = routeOf(label)
+    if (route !== undefined) { routes.push(route); continue }
+    registrations += 1
     if (provided?.[1] !== undefined) provides.push(provided[1])
-    else if (route?.[1] !== undefined && route[2] !== undefined) routes.push({ method: route[1], path: route[2] })
-    else if (used?.[1] !== undefined) middleware.push(used[1])
+    else if (mount?.[1] !== undefined) mounts.push(mount[1])
     else other.push(label)
   }
   return {
@@ -92,10 +100,10 @@ export function reportFiber(fiber: FiberView, adopted: readonly FiberView[] = []
     state: stateName(fiber.state),
     requires: Object.keys(fiber.inject).sort(),
     provides: provides.sort(),
+    mounts,
     routes,
-    middleware,
     other,
-    removedOnUnload: labels.length,
+    removedOnUnload: registrations,
   }
 }
 
@@ -108,7 +116,7 @@ export function explain(report: PluginReport): string {
     `  needs:     ${list(report.requires)}`,
     `  provides:  ${list(report.provides)}`,
     `  routes:    ${list(report.routes.map(route => `${route.method} ${route.path}`))}`,
-    `  middleware:${report.middleware.length === 0 ? ' nothing' : ` ${report.middleware.join(', ')}`}`,
+    `  mounts:    ${report.mounts.length === 0 ? 'nothing' : report.mounts.join(', ')}`,
   ]
   if (report.other.length > 0) lines.push(`  also:      ${report.other.join('; ')}`)
   lines.push(report.state === 'PENDING'

package/plugins/acryl-inspect/src/service.ts

@@ -6,7 +6,7 @@
 
 import { Context, Service } from '@deepseek-ai/cordis'
 import { loopbackOnly } from '../../acryl-router/src/middleware/index.ts'
-import type {} from '../../acryl-router/src/index.ts'
+import { App } from '../../acryl-router/src/index.ts'
 import { explain, ownerOf, renderReports, reportFiber, type FiberView, type PluginReport } from './report.ts'
 
 declare module '@deepseek-ai/cordis' {
@@ -54,12 +54,14 @@ export function apply(ctx: Context): void {
   // The same facts on the router, for any surface; present only where a router is. A request over a socket must come from this machine to this app;
   // the terminal calls the router in process and is the host's own code.
   ctx.inject(['router'], inner => {
-    const api = inner.router.group('/api/inspect', loopbackOnly({ inProcess: 'allow' }))
-    api.get('/plugins', c => c.json(inspect.plugins()))
-    api.get('/plugins/:name', c => {
-      const text = inspect.explain(c.param('name') ?? '')
-      return text === undefined ? c.json({ error: 'no such plugin' }, 404) : c.text(text)
-    })
+    const api = new App()
+      .use(loopbackOnly({ inProcess: 'allow' }))
+      .get('/plugins', c => c.json(inspect.plugins()))
+      .get('/plugins/:name', c => {
+        const text = inspect.explain(c.req.param('name'))
+        return text === undefined ? c.json({ error: 'no such plugin' }, 404) : c.text(text)
+      })
+    inner.router.route('/api/inspect', api)
     // Over HTTP only where an adapter exists (Web and Desktop); the terminal needs none.
     inner.inject(['routerHttp'], http => { http.routerHttp.mount('/api/inspect') })
   })

package/plugins/acryl-inspect/tests/report.spec.ts

@@ -7,14 +7,19 @@ function fiber(over: Partial<FiberView> & { effects?: FiberView['getEffects'] ex
 }
 
 describe('reportFiber', () => {
-  it('sorts effects into provides, routes, middleware and everything else, including nested ones', () => {
+  it('sorts effects into provides, mounts with their routes, and everything else, including nested ones', () => {
     const report = reportFiber(fiber({
       inject: { router: null, acrylSettings: null },
       effects: [
         { label: 'ctx.provide("things")', children: [] },
-        { label: 'acryl-router: GET /api/things/:id', children: [] },
-        { label: 'acryl-router: POST /api/things', children: [{ label: 'inner timer', children: [] }] },
-        { label: 'acryl-router: use /api', children: [] },
+        { label: 'acryl-router: route /api', children: [
+          { label: 'acryl-router: serves ALL /api/*', children: [] },
+          { label: 'acryl-router: serves GET /api/things/:id', children: [] },
+        ] },
+        { label: 'acryl-router: route /api/things', children: [
+          { label: 'acryl-router: serves POST /api/things', children: [] },
+          { label: 'inner timer', children: [] },
+        ] },
         { label: 'ctx.on("internal/status")', children: [] },
       ],
     }))
@@ -23,10 +28,10 @@ describe('reportFiber', () => {
       state: 'ACTIVE',
       requires: ['acrylSettings', 'router'],
       provides: ['things'],
-      routes: [{ method: 'GET', path: '/api/things/:id' }, { method: 'POST', path: '/api/things' }],
-      middleware: ['/api'],
+      mounts: ['/api', '/api/things'],
+      routes: [{ method: 'ALL', path: '/api/*' }, { method: 'GET', path: '/api/things/:id' }, { method: 'POST', path: '/api/things' }],
       other: ['inner timer', 'ctx.on("internal/status")'],
-      removedOnUnload: 6,
+      removedOnUnload: 5,
     })
   })
 
@@ -42,7 +47,7 @@ describe('explain', () => {
   it('says what a plugin needs, adds and removes on unload', () => {
     const text = explain(reportFiber(fiber({
       inject: { router: null },
-      effects: [{ label: 'acryl-router: GET /a', children: [] }],
+      effects: [{ label: 'acryl-router: route /', children: [{ label: 'acryl-router: serves GET /a', children: [] }] }],
     })))
     expect(text).toContain('demo (ACTIVE)')
     expect(text).toContain('needs:     router')

package/plugins/acryl-inspect/tests/service.spec.ts

@@ -4,7 +4,7 @@
  */
 
 import { Context } from '@deepseek-ai/cordis'
-import { apply as routerApply, name as routerName } from '../../acryl-router/src/index.ts'
+import { App, apply as routerApply, name as routerName } from '../../acryl-router/src/index.ts'
 import { afterEach, describe, expect, it } from 'vitest'
 import { apply, name, type PluginReport } from '../src/index.ts'
 
@@ -18,9 +18,10 @@ const market = {
   name: 'demo-market',
   inject: ['router'],
   apply(ctx: Context): void {
-    ctx.router.use('/api/demo', async (_c, next) => next())
-    ctx.router.get('/api/demo/state', c => c.json({ ok: true }))
-    ctx.router.post('/api/demo/sources', c => c.json({ ok: true }, 201))
+    ctx.router.route('/api/demo', new App()
+      .use(async (_c, next) => { await next() })
+      .get('/state', c => c.json({ ok: true }))
+      .post('/sources', c => c.json({ ok: true }, 201)))
   },
 }
 
@@ -45,7 +46,7 @@ describe('acryl-inspect', () => {
     ctx.plugin({
       name: 'demo-inline',
       apply(inner: Context): void {
-        inner.inject(['router'], deeper => { deeper.router.get('/api/inline', c => c.json({ ok: true })) })
+        inner.inject(['router'], deeper => { deeper.router.route('/', new App().get('/api/inline', c => c.json({ ok: true }))) })
       },
     })
     await settle()
@@ -67,9 +68,9 @@ describe('acryl-inspect', () => {
       state: 'ACTIVE',
       requires: ['router'],
       provides: [],
-      routes: [{ method: 'GET', path: '/api/demo/state' }, { method: 'POST', path: '/api/demo/sources' }],
-      middleware: ['/api/demo'],
-      removedOnUnload: 3,
+      mounts: ['/api/demo'],
+      routes: [{ method: 'ALL', path: '/api/demo/*' }, { method: 'GET', path: '/api/demo/state' }, { method: 'POST', path: '/api/demo/sources' }],
+      removedOnUnload: 1,
     })
   })
 
@@ -102,10 +103,10 @@ describe('acryl-inspect', () => {
     const list = await ctx.router.fetch(new Request('http://acryl.test/api/inspect/plugins'))
     expect(list.status).toBe(200)
     const reports = await list.json() as PluginReport[]
-    expect(byName(reports, 'demo-market').routes).toHaveLength(2)
+    expect(byName(reports, 'demo-market').routes).toHaveLength(3)
 
     const one = await ctx.router.fetch(new Request('http://acryl.test/api/inspect/plugins/demo-market'))
-    expect(await one.text()).toContain('removes 3 registrations and nothing else')
+    expect(await one.text()).toContain('removes 1 registration and nothing else')
     expect((await ctx.router.fetch(new Request('http://acryl.test/api/inspect/plugins/nope'))).status).toBe(404)
   })