acrylblends 0.3.0 → 0.4.1

package/plugins/acryl-router-http/tests/adapter.spec.ts

@@ -8,7 +8,8 @@ import { Context, type FiberState } from '@deepseek-ai/cordis'
 import WebServer from '@deepseek-ai/dsh-host-webserver'
 import { apply as routerApply, name as routerName } from '../../acryl-router/src/index.ts'
 import { afterEach, describe, expect, it } from 'vitest'
-import type { RouterHttpService } from '../../acryl-router/src/index.ts'
+import { App, connectionOf, type RouterHttpService } from '../../acryl-router/src/index.ts'
+import { methodNotAllowed } from '../../acryl-router/src/middleware/index.ts'
 import { apply, inject, name } from '../src/index.ts'
 
 const PENDING = 0 as FiberState.PENDING
@@ -39,25 +40,28 @@ async function stack(): Promise<{ ctx: Context, base: () => string }> {
   return { ctx, base: () => `http://127.0.0.1:${String((ctx as unknown as { webServer: { port: number } }).webServer.port)}` }
 }
 
-function demo(prefix: string, extra?: (ctx: Context) => void) {
+function demo(prefix: string, extra?: (app: App) => void) {
   return {
     name: `demo${prefix.replaceAll('/', '-')}`,
     inject: ['router', 'routerHttp'],
     apply(ctx: Context): void {
       ctx.routerHttp.mount(prefix)
-      ctx.router.get(`${prefix}/hello/:who`, c => c.json({ hello: c.params['who'], q: c.url.searchParams.get('q'), host: c.req.headers.get('host') !== null }))
-      ctx.router.post(`${prefix}/echo`, async c => c.json({ got: await c.req.text(), type: c.req.headers.get('content-type') }, 201))
-      ctx.router.get(`${prefix}/cookies`, () => {
+      const app = new App()
+      app.use(methodNotAllowed({ app }))
+      app.get('/hello/:who', c => c.json({ hello: c.req.param('who'), q: c.req.query('q') ?? null, host: c.req.header('host') !== undefined }))
+      app.post('/echo', async c => c.json({ got: await c.req.text(), type: c.req.header('content-type') ?? null }, 201))
+      app.get('/cookies', () => {
         const headers = new Headers()
         headers.append('set-cookie', 'a=1; Path=/')
         headers.append('set-cookie', 'b=2; Path=/')
         return new Response('ok', { headers })
       })
-      ctx.router.get(`${prefix}/stream`, () => new Response(new ReadableStream({
+      app.get('/stream', () => new Response(new ReadableStream({
         start(controller) { controller.enqueue(new TextEncoder().encode('one,')); controller.enqueue(new TextEncoder().encode('two')); controller.close() },
       })))
-      ctx.router.get(`${prefix}/peer`, c => c.json({ remote: c.connection.remoteAddress ?? null, localPort: c.connection.localPort ?? null }))
-      extra?.(ctx)
+      app.get('/peer', c => c.json({ remote: connectionOf(c).remoteAddress ?? null, localPort: connectionOf(c).localPort ?? null }))
+      extra?.(app)
+      ctx.router.route(prefix, app)
     },
   }
 }
@@ -106,7 +110,7 @@ describe('acryl-router-http against a real webServer', () => {
     await settle(20)
     const missing = await fetch(`${base()}/api/demo/none`)
     expect(missing.status).toBe(404)
-    expect(await missing.text()).toBe('Not Found')
+    expect(await missing.text()).toBe('404 Not Found')
     expect((await fetch(`${base()}/api/demo/echo`)).status).toBe(405)
     const head = await fetch(`${base()}/api/demo/hello/a`, { method: 'HEAD' })
     expect(head.status).toBe(200)
@@ -117,9 +121,9 @@ describe('acryl-router-http against a real webServer', () => {
   it('aborts the handler signal when the HTTP client disconnects', async () => {
     const { ctx, base } = await stack()
     let aborted = false
-    ctx.plugin(demo('/api/demo', c => {
-      c.router.get('/api/demo/slow', async r => {
-        await new Promise<void>((_resolve, reject) => { r.signal.addEventListener('abort', () => { aborted = true; reject(new Error('aborted')) }, { once: true }) })
+    ctx.plugin(demo('/api/demo', app => {
+      app.get('/slow', async r => {
+        await new Promise<void>((_resolve, reject) => { r.req.raw.signal.addEventListener('abort', () => { aborted = true; reject(new Error('aborted')) }, { once: true }) })
         return r.text('never')
       })
     }))

package/plugins/acryl-router-http/tests/surfaces.spec.ts

@@ -7,7 +7,7 @@
 
 import { Context } from '@deepseek-ai/cordis'
 import WebServer from '@deepseek-ai/dsh-host-webserver'
-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 as httpApply, inject as httpInject, name as httpName } from '../src/index.ts'
 
@@ -28,15 +28,17 @@ const notes = {
   inject: ['router'],
   apply(ctx: Context): void {
     const store = new Map<string, string>()
-    ctx.router.post('/api/notes/:id', async c => {
-      const text = await c.req.text()
-      store.set(c.params['id'] ?? '', text)
-      return c.json({ id: c.params['id'], saved: text.length }, 201)
-    })
-    ctx.router.get('/api/notes/:id', c => {
-      const text = store.get(c.params['id'] ?? '')
-      return text === undefined ? c.json({ error: 'not found' }, 404) : c.json({ id: c.params['id'], text })
-    })
+    const app = new App()
+      .post('/:id', async c => {
+        const text = await c.req.text()
+        store.set(c.req.param('id'), text)
+        return c.json({ id: c.req.param('id'), saved: text.length }, 201)
+      })
+      .get('/:id', c => {
+        const text = store.get(c.req.param('id'))
+        return text === undefined ? c.json({ error: 'not found' }, 404) : c.json({ id: c.req.param('id'), text })
+      })
+    ctx.router.route('/api/notes', app)
     ctx.inject(['routerHttp'], inner => { inner.routerHttp.mount('/api/notes') })
   },
 }

package/plugins/acryl-router-http/upstream.json

@@ -2,15 +2,15 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-router-http",
-    "commit": "11fed295161c0282d144b5ac62616988b58d8189"
+    "commit": "64e7c9d2e787f74b2da82492644fbbb46a601074"
   },
   "vendored": [
     "src",
     "tests",
     "LICENSE"
   ],
-  "rewrittenSpecifiers": 6,
-  "digest": "sha256:6a79e85a11bf61a13604736ef9776f878a024ef19e1282481bdfe13343916bc4",
+  "rewrittenSpecifiers": 7,
+  "digest": "sha256:29ba7834cf9d29e9af2f4fac265c7e5e220e06da3346e65c29bcbae41fdfaf9e",
   "testsNotRun": {
     "tests/adapter.spec.ts": "needs @deepseek-ai/dsh-host-webserver (the DSH web server); acryl-node-server has its own tests",
     "tests/stream.spec.ts": "needs @deepseek-ai/dsh-host-webserver (the DSH web server)",

package/plugins/acryl-state/NOTICE

@@ -0,0 +1,30 @@
+acryl-state
+
+Copyright (c) 2026 WebBoxes s.r.o.
+Licensed under the MIT License (see LICENSE).
+
+The cell and derived-cell shape follows VanJS (https://vanjs.org). The code is a new implementation; the notice of that work is kept here.
+
+---
+
+VanJS
+
+Copyright (c) 2023 VanJS (Vanilla JavaScript)
+
+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/plugins/acryl-state/plugin.json

@@ -8,5 +8,5 @@
     "@deepseek-ai/cordis": "4.0.4"
   },
   "mount": "root.plugin(state); ctx.state.cell('todos.count', 0), then count.update((n) => n + 1)",
-  "omit": ["src/react.ts"]
+  "omit": ["src/react.ts", "**/*.test.*", "**/*.case.ts"]
 }

package/plugins/acryl-state/src/cell.ts

@@ -1,6 +1,6 @@
 /**
  * Observable cells: the reactive core of the state service, with no Cordis and no DOM. A cell holds one value, tells its
- * subscribers when it changes, and can be derived from other cells. The shape is a writable cell and a derived cell
+ * subscribers when it changes, and can be derived from other cells. The shape follows VanJS's `state` and `derive`
  * (spec 046, M5): small enough to read in one sitting, and the same cell serves a React hook, a terminal component and a
  * server-sent stream.
  */

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

@@ -6,9 +6,9 @@
  */
 
 import { Context, Service } from '@deepseek-ai/cordis'
-import type { RouteContext } from '../../acryl-router/src/index.ts'
+import { App, type Context as RequestContext } from '../../acryl-router/src/index.ts'
 import { streamSSE } from '../../acryl-router/src/helpers/index.ts'
-import { loopbackOnly } from '../../acryl-router/src/middleware/index.ts'
+import { loopbackOnly, methodNotAllowed } from '../../acryl-router/src/middleware/index.ts'
 import { createCell, createDerived, type Cell, type ReadonlyCell } from './cell.ts'
 
 declare module '@deepseek-ai/cordis' {
@@ -17,6 +17,8 @@ declare module '@deepseek-ai/cordis' {
   }
 }
 
+const KEEP_ALIVE_MS = 15_000
+
 /** Stable Cordis plugin name, equal to the package name and the Loader row id. */
 export const name = 'acryl-state'
 
@@ -70,15 +72,29 @@ export class State extends Service {
   }
 
   /**
-   * The current value of `key` as a server-sent event stream: the value now, then one event per change, until the request is aborted, the client
-   * cancels, or the router is disposed. `streamSSE` holds the request in flight until then, so the router waits for the stream.
+   * The current value of `key` as a server-sent event stream: the value now, then one event per change, until the client cancels or the router
+   * is disposed (both abort the stream). A comment line goes out every 15 seconds so proxies and browsers keep an idle stream open.
    */
-  stream(key: string, c: RouteContext): Response | undefined {
+  stream(key: string, c: RequestContext): Response | undefined {
     const cell = this.find(key)
     if (cell === undefined) return undefined
-    return streamSSE(c, stream => {
-      stream.send(cell.get(), { event: 'value' })
-      return cell.subscribe(value => { stream.send(value, { event: 'value' }) })
+    return streamSSE(c, async stream => {
+      const ended = new Promise<void>(resolve => { stream.onAbort(resolve) })
+      // Writes are asynchronous; chaining them keeps events in the order the cell changed.
+      let queue: Promise<unknown> = Promise.resolve()
+      const send = (value: unknown): void => {
+        queue = queue.then(() => stream.writeSSE({ event: 'value', data: typeof value === 'string' ? value : JSON.stringify(value) })).catch(() => {})
+      }
+      send(cell.get())
+      const unsubscribe = cell.subscribe(send)
+      const keepAlive = setInterval(() => { queue = queue.then(() => stream.write(': keepalive\n\n')).catch(() => {}) }, KEEP_ALIVE_MS)
+      keepAlive.unref()
+      try {
+        await ended
+      } finally {
+        clearInterval(keepAlive)
+        unsubscribe()
+      }
     })
   }
 }
@@ -88,13 +104,15 @@ export function apply(ctx: Context): void {
   // The same cells on the router, read-only, 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/state', loopbackOnly({ inProcess: 'allow' }))
-    api.get('/', c => c.json({ keys: state.keys() }))
-    api.get('/:key', c => {
-      const cell = state.find(c.param('key') ?? '')
-      return cell === undefined ? c.json({ error: 'no such state' }, 404) : c.json({ key: cell.key, value: cell.get() })
-    })
-    api.get('/:key/events', c => state.stream(c.param('key') ?? '', c) ?? c.json({ error: 'no such state' }, 404))
+    const api = new App()
+    api.use(loopbackOnly({ inProcess: 'allow' }), methodNotAllowed({ app: api }))
+      .get('/', c => c.json({ keys: state.keys() }))
+      .get('/:key', c => {
+        const cell = state.find(c.req.param('key'))
+        return cell === undefined ? c.json({ error: 'no such state' }, 404) : c.json({ key: cell.key, value: cell.get() })
+      })
+      .get('/:key/events', c => state.stream(c.req.param('key'), c) ?? c.json({ error: 'no such state' }, 404))
+    inner.router.route('/api/state', api)
     // Over HTTP only where an adapter exists (Web and Desktop); the terminal needs none.
     inner.inject(['routerHttp'], http => { http.routerHttp.mount('/api/state') })
   })

package/plugins/acryl-state/upstream.json

@@ -2,19 +2,21 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-state",
-    "commit": "11fed295161c0282d144b5ac62616988b58d8189"
+    "commit": "64e7c9d2e787f74b2da82492644fbbb46a601074"
   },
   "vendored": [
     "src",
     "tests",
-    "LICENSE"
+    "LICENSE",
+    "NOTICE"
   ],
   "rewrittenSpecifiers": 4,
-  "digest": "sha256:528bdc35dbbe22dfae8822fe054cfbfccae9554b9e06089dd7e269f44e27add4",
+  "digest": "sha256:8feb067a67ea2628ff31a9fd2201361be4be5a8c217be3b7169277c0ce472b69",
   "testsNotRun": {
     "tests/react.spec.ts": "needs react and @testing-library/react, which generated apps do not install"
   },
   "notice": [
-    "LICENSE"
+    "LICENSE",
+    "NOTICE"
   ]
 }

package/plugins/builder/script.ts

@@ -18,22 +18,19 @@ const PATH = /^\/[a-z0-9/-]*$/
 
 export function routeSource(name: string, path: string, text: string): string {
   return `import type { Context } from '@deepseek-ai/cordis'
+import { App } from 'acryl-router'
 
 /** Written by the builder: answers GET ${path}, and checks that it does before the install counts. */
 export const name = '${name}'
 export const inject = ['router']
 
-interface Router {
-  get(path: string, handler: (c: { json(body: unknown, status?: number): Response }) => Response): unknown
-  request(path: string): Promise<Response>
-}
 export function apply(ctx: Context) {
-  // A route registered through this plugin's context is removed when the plugin is unloaded.
-  (ctx as unknown as { router: Router }).router.get(${JSON.stringify(path)}, (c) => c.json({ text: ${JSON.stringify(text)} }))
+  // The app is mounted through this plugin's context, so the route is removed when the plugin is unloaded.
+  ctx.router.route('/', new App().get(${JSON.stringify(path)}, (c) => c.json({ text: ${JSON.stringify(text)} })))
 }
 
 export async function check(ctx: Context) {
-  const reply = await (ctx.get('router') as Router).request(${JSON.stringify(path)})
+  const reply = await ctx.router.request(${JSON.stringify(path)})
   if (!reply.ok) throw new Error(\`GET ${path} answered \${reply.status}\`)
 }
 `

package/plugins/extensions/index.ts

@@ -32,7 +32,7 @@ import { type Context, type Fiber, Service } from '@deepseek-ai/cordis'
 import type {} from '../instance/index.ts'
 import type { Sandbox } from '../sandbox/index.ts'
 import { appendLedger, type LedgerEntry, readLedger } from './ledger.ts'
-import { resolveFromApp } from './resolve.ts'
+import { resolveFromApp, routerAliases } from './resolve.ts'
 import { hashFolder, prune, stage } from './stage.ts'
 
 /** A fiber's lifecycle state, by name (Cordis's own enum is a `const enum`, which does not exist at run time). */
@@ -109,7 +109,7 @@ interface PluginModule {
   readonly name?: unknown
   readonly inject?: unknown
   readonly apply: (...args: unknown[]) => unknown
-  /** Optional self-check, run after the plugin starts: it throws (or rejects) when the plugin does not work. */
+  /** Optional self-check, run after the plugin starts with the plugin's own context (so `ctx.router` reads as in `apply`): it throws (or rejects) when the plugin does not work. */
   readonly check?: (ctx: Context) => unknown
 }
 
@@ -221,7 +221,7 @@ export class Extensions extends Service {
     this.ledgerFile = join(home, 'extensions-ledger.jsonl')
     // Effects run their disposers newest first: settle pending operations, then dispose every mounted extension, then drop the hook.
     ctx.effect(
-      () => resolveFromApp(this.stageRoot, root),
+      () => resolveFromApp(this.stageRoot, root, routerAliases()),
       'extensions: resolve staged imports from the app',
     )
     ctx.effect(
@@ -507,6 +507,7 @@ export class Extensions extends Service {
   /** Run the extension's own `check`, if it has one, with a time limit. Returns the failure, or `undefined` when it passes. */
   private async verify(
     module: PluginModule,
+    ctx: Context,
   ): Promise<{ stage: 'verify'; error: string } | undefined> {
     if (typeof module.check !== 'function') return undefined
     let timer: ReturnType<typeof setTimeout> | undefined
@@ -517,7 +518,7 @@ export class Extensions extends Service {
           CHECK_TIMEOUT_MS,
         )
       })
-      await Promise.race([Promise.resolve(module.check(this.ctx)), limit])
+      await Promise.race([Promise.resolve(module.check(ctx)), limit])
       return undefined
     } catch (error) {
       return { stage: 'verify', error: `its check failed: ${message(error)}` }
@@ -615,7 +616,7 @@ export class Extensions extends Service {
             error: message(mounted.error ?? 'the plugin failed to start'),
           }
         : state === 'active'
-          ? await this.verify(module)
+          ? await this.verify(module, mounted.fiber.ctx)
           : undefined
     if (failure) {
       await mounted.fiber.dispose().catch(() => undefined)

package/plugins/extensions/resolve.ts

@@ -3,20 +3,45 @@
  * `@deepseek-ai/cordis` would not find the app's `node_modules`. This resolve hook leaves resolution alone, and only when it fails for a
  * module inside the staging folder, resolves the same name from the app's project folder. Uses Node's public `module.registerHooks`
  * (ACRYL needed the same fallback on Deno); the returned function removes the hook.
+ *
+ * The framework plugins are not packages in an app (they are source under `src/plugins/`), so `aliases` names the files a framework specifier such as
+ * `acryl-router` stands for. A staged plugin then imports the same module the app itself runs, so `App` is the very class the router mounts.
  */
-import { mkdirSync, realpathSync } from 'node:fs'
+import { existsSync, mkdirSync, realpathSync } from 'node:fs'
 import { registerHooks } from 'node:module'
 import { join } from 'node:path'
-import { pathToFileURL } from 'node:url'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 
 const isBare = (specifier: string) => !/^[./]/.test(specifier) && !specifier.includes(':')
 
-export function resolveFromApp(stageRoot: string, appRoot: string): () => void {
+/** The router's specifiers, as files of the vendored plugin that sits beside this one; empty when the app has no router. */
+export function routerAliases(): Record<string, string> {
+  const src = new URL('../acryl-router/src/', import.meta.url)
+  const files = {
+    'acryl-router': 'index.ts',
+    'acryl-router/middleware': 'middleware/index.ts',
+    'acryl-router/helpers': 'helpers/index.ts',
+  }
+  return Object.fromEntries(
+    Object.entries(files)
+      .map(([specifier, file]) => [specifier, fileURLToPath(new URL(file, src))] as const)
+      .filter(([, path]) => existsSync(path)),
+  )
+}
+
+export function resolveFromApp(
+  stageRoot: string,
+  appRoot: string,
+  aliases: Record<string, string> = {},
+): () => void {
   mkdirSync(stageRoot, { recursive: true })
   const staged = pathToFileURL(`${realpathSync(stageRoot)}/`).href
   const parentURL = pathToFileURL(join(realpathSync(appRoot), 'package.json')).href
   const hook = registerHooks({
     resolve(specifier, context, nextResolve) {
+      const alias = aliases[specifier]
+      if (alias !== undefined && context.parentURL?.startsWith(staged))
+        return nextResolve(pathToFileURL(alias).href, context)
       try {
         return nextResolve(specifier, context)
       } catch (error) {

package/plugins/openai/prompt.ts

@@ -10,26 +10,28 @@ To add a capability:
 A plugin's index.ts is TypeScript that Node runs directly (erasable syntax only: no enums, no parameter properties):
 
   import type { Context } from '@deepseek-ai/cordis'
+  import { App } from 'acryl-router'
   export const name = 'hello'            // must equal the folder name
   export const inject = ['router']        // services it needs; it waits (pending) until they exist
-  interface Router { get(path: string, handler: (c: { json(body: unknown, status?: number): Response }) => Response): unknown; request(path: string): Promise<Response> }
   export function apply(ctx: Context) {
-    ;(ctx as unknown as { router: Router }).router.get('/hello', (c) => c.json({ text: 'Hello' }))   // removed when the plugin is unloaded
+    ctx.router.route('/', new App().get('/hello', (c) => c.json({ text: 'Hello' })))   // removed when the plugin is unloaded
   }
   export async function check(ctx: Context) {   // optional: must pass, or the install is rolled back
-    const reply = await (ctx.get('router') as Router).request('/hello')
+    const reply = await ctx.router.request('/hello')
     if (!reply.ok) throw new Error('GET /hello failed')
   }
 
-The router: router.get/post/put/delete(path, handler), a path parameter is :id and is read with c.param('id'), c.json(body, status)
-answers JSON, c.text(...) answers text, c.req.json() reads a JSON body, and router.request('/path', { method: 'POST', body: ... }) calls a route in
-process (use it in check). Every registration made from a plugin's own context goes away when the plugin is unloaded.
+The router: build an App (import { App } from 'acryl-router'), register routes on it with app.get/post/put/patch/delete(path, handler) and mount it with
+ctx.router.route(prefix, app). A path parameter is :id and is read with c.req.param('id'); c.json(body, status) answers JSON, c.text(...) answers text,
+await c.req.json() reads a JSON body, throw new HTTPException(404, { message }) (also from 'acryl-router') answers an error. Routes added to an app
+after route() are not served: build the whole app first. ctx.router.request('/path', { method: 'POST', body: ... }) calls a route in process (use it in
+check). The mount goes away when the plugin is unloaded.
 
 For a capability that is a pure function of data (parse, convert, compute), write a sandboxed TOOL instead of a plugin. It cannot touch the
 host: it runs in a separate process that can read only its own folder. Files: index.ts exporting  run(input)  and  tool.json:
   { "description": "what it does and its input", "examples": [ { "input": {...}, "output": {...} } ] }
 The examples are run in the sandbox at install and must match exactly, or the install is refused. Use write_plugin and install_plugin for tools too.
 
-Rules: import only relative files, node: built-ins and @deepseek-ai/cordis. Provide services with ctx.provide(name, value) and
+Rules: import only relative files, node: built-ins, @deepseek-ai/cordis and acryl-router. Provide services with ctx.provide(name, value) and
 use others with ctx.get(name). Put timers, listeners and routes inside ctx.effect(() => cleanup). Use list_plugins and
 read_plugin to see what exists. When you are done, answer in one or two plain sentences saying what you built.`

package/plugins/tsconfig.json

@@ -1,12 +1,10 @@
 {
   "compilerOptions": {
-    "target": "ES2023",
-    "lib": ["ES2023"],
+    "target": "ES2024",
+    "lib": ["ES2024", "DOM", "DOM.Iterable"],
     "module": "NodeNext",
     "moduleResolution": "NodeNext",
     "strict": true,
-    "noUncheckedIndexedAccess": true,
-    "exactOptionalPropertyTypes": true,
     "noImplicitOverride": true,
     "verbatimModuleSyntax": true,
     "erasableSyntaxOnly": true,
@@ -17,6 +15,9 @@
   },
   "include": ["*/**/*.ts"],
   "exclude": [
+    "acryl-*/src/**/*.test.ts",
+    "acryl-*/src/**/*.case.ts",
+    "acryl-node-server/tests/adapter",
     "acryl-router/tests/loader.spec.ts",
     "acryl-state/src/react.ts",
     "acryl-state/tests/react.spec.ts",

package/shared/AGENTS.core.md

@@ -0,0 +1,54 @@
+# __APP_NAME__
+
+A Cordis app on the ACRYL framework: TypeScript that Node 22.19 or newer runs directly (no build step; erasable syntax only, so no enums and no
+parameter properties). Every part of it is a Cordis plugin.
+
+## The framework's API is in `docs/framework/`
+
+Start at `docs/framework/README.md`; `api-summary.md` is the one-page summary. Read before you write routes: `routing.md` (the `App`), `request.md` (`c.req`), `context.md` (`c`),
+`validation.md`, `helpers.md` (`streamSSE`), `middleware.md`, `plugin-lifecycle.md` (what a plugin owns and when it is unloaded) and
+`node-server.md`. The framework's source is vendored in `src/plugins/acryl-*/src`: read it, do not edit it (a change belongs in ACRYL, upstream).
+The docs write `from 'acryl-router'`; in this app that is `./plugins/acryl-router/src/index.ts` (relative to `src/`), `acryl-router/middleware`
+is `./plugins/acryl-router/src/middleware/index.ts` and `acryl-router/helpers` is `./plugins/acryl-router/src/helpers/index.ts`.
+A plugin written into `extensions/` while the app runs can import `acryl-router`, `acryl-router/middleware` and `acryl-router/helpers` by those names.
+
+## How a feature is built
+
+Routes are an ordinary `App` that a plugin mounts once with `ctx.router.route(prefix, app)`. The mount belongs to the plugin and goes away when it unloads.
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import { App, HTTPException } from './plugins/acryl-router/src/index.ts'
+import { schemaValidator, type StandardSchema } from './plugins/acryl-router/src/helpers/index.ts'
+
+export const name = 'notes'               // a plugin's name; blend.yaml refers to it
+export const inject = ['router']          // services it needs
+export function apply(ctx: Context) {
+  const app = new App()
+    .get('/', (c) => c.json({ ok: true }))
+    .get('/:id', (c) => c.json({ id: c.req.param('id') }))
+    .post('/', schemaValidator('json', NewNote), (c) => c.json(c.req.valid('json'), 201))   // NewNote is a Standard Schema
+  ctx.router.route('/notes', app)         // build the whole app first: routes added after route() are not served
+}
+```
+
+- A small route goes on the `App` in `src/routes.ts`. A new feature is a new plugin file: add it to `registry` in `src/app.ts`, add a row
+  (`- id: notes` / `name: notes`) to `blend.yaml` before the `acryl-node-server` row, and pass runtime values (a data file) as its config in `createApp`.
+- State, when `src/plugins/acryl-state` exists: `const cell = ctx.state.cell<T>('notes.list', initial)` (add `'state'` to `inject`), then
+  `cell.get()`, `cell.set(value)`, `cell.update(fn)` and `cell.subscribe(fn)` (returns the unsubscribe). Every cell is also served as JSON at `/api/state/<key>`
+  and streamed at `/api/state/<key>/events`.
+- Test a route without a socket: `await ctx.router.request('/notes')`, or boot the app as `test/app.test.ts` does and use `fetch`.
+
+## Things that surprise people
+
+- A page mounted at `/x` answers `/x`, not `/x/` (trailing slashes are strict); `trimTrailingSlash()` (middleware) redirects `/x/` to `/x` for GET and HEAD.
+- `schemaValidator('json', ...)` needs a JSON `Content-Type`; without it the schema sees `{}`. A failure answers 400 with
+  `{ "error": "invalid json", "issues": [{ "message", "path" }] }`: the human text is `issues[0].message`. A `jsonOnly` recipe in `docs/framework/validation.md` answers 415 instead.
+- Throw `new HTTPException(404, { message })` for an error response; the body is the message as plain text (use `c.json({ error }, status)` when a page expects JSON).
+- Handlers get the request as `c.req`: `c.req.param('id')`, `c.req.query('q')`, `await c.req.json()`, `c.req.raw` for the Web `Request`.
+- A server-sent stream is `streamSSE(c, async (stream) => { await stream.writeSSE({ data: JSON.stringify(x) }) ... })`; call `stream.onAbort(cleanup)`.
+- `npm run dev` restarts the app whenever a file changes.
+
+## Before you say you are done
+
+`npm test` and `npm run check` (type-check) both pass. Put tests in `test/`, written with `node:test` like `test/app.test.ts`.

package/templates/agent/AGENTS.md

@@ -0,0 +1,6 @@
+
+## This app (agent)
+
+Besides `src/routes.ts`, the app runs an agent (`POST /ask`) that can write plugins into `extensions/` while the app runs and install them with
+rollback; `GET /extensions` and `GET /tasks` show what it did. A plugin there is a folder with an `index.ts` exporting `name`, `inject`, `apply(ctx)`
+and an optional `check(ctx)` that receives the plugin's own context (so `ctx.router` reads as in `apply`). It may import `acryl-router`.

package/templates/agent/README.md

@@ -5,7 +5,7 @@ Cordis plugin.
 
 ```sh
 npm install
-npm run dev        # prints its URL; data lives in .acrylblends/
+npm run dev        # prints its URL; data lives in .acrylblends/; it restarts when a file changes (a new port if ACRYLBLENDS_PORT=0)
 npm test
 npm run check      # type-check
 
@@ -41,7 +41,7 @@ curl <url>/tasks              # every run as a durable task, with the tool calls
 
 Other commands: `update route <name> <path> <text>`, `break plugin <name>` (shows the rollback), `remove plugin <name>`,
 `list plugins`. What the agent writes lands in `extensions/`, is part of your app, and starts again at the next start.
-- `src/routes.ts` is your own plugin: routes added inside `ctx.effect`.
+- `src/routes.ts` is your own plugin: it builds an `App` (`import { App } from './plugins/acryl-router/src/index.ts'`) and mounts it with `ctx.router.route(prefix, app)`. Routes added to the app after it is mounted are not served. A page mounted at `/x` answers `/x`, not `/x/` (trailing slashes are strict). The router API is documented at https://acrylblends.github.io/docs/framework/the-acryl-framework and in `docs/framework` of the acrylblends repository.
 - `src/plugins/` holds the plugins copied from the ACRYLBLENDS library. They are yours now; edit them freely.
   Add more with `acrylblends add <plugin>`.
 

package/templates/agent/blend.yaml

@@ -1,6 +1,6 @@
 # The app as data, in ACRYL's Blend format (blends.acryl.dev/v1alpha1): which plugins it mounts, in what order, with what config.
 # Edit this, not app.ts, to switch a plugin off (disabled: true) or change its config. `npm run lock` records what the app is built from.
-# Order matters: http comes before extensions, because installed extensions start again at boot and may add routes.
+# Order matters: acryl-router comes before extensions, because installed extensions start again at boot and may add routes.
 apiVersion: blends.acryl.dev/v1alpha1
 kind: Blueprint
 metadata: