acrylblends 0.7.6 → 0.7.8

package/plugins/acryl-router/src/helpers/read-sse.ts

@@ -0,0 +1,111 @@
+/**
+ * `readSSE(response)`: the events of a `text/event-stream` answer from `fetch`, for the browser. `EventSource` reads GET streams only; a chat
+ * or any stream that needs a POST body, a header or an `AbortSignal` is read with `fetch`, and this is the loop every such page otherwise writes by
+ * hand. It follows the parsing rules of the HTML standard (lines end in LF, CRLF or CR; the `data` lines of one event join with LF; a line that
+ * starts with a colon is a comment; an event ends at a blank line; an event with no `data` line is not dispatched; the last event is dispatched
+ * only if its blank line arrived), and it is one module with no imports, so it also runs in a service worker and on a fetch runtime.
+ *
+ * ACRYL's own addition, not part of the upstream port.
+ */
+
+/** One event of the stream. */
+export interface SSEEvent {
+  /** The `event:` name; `message` when the event has none. */
+  readonly event: string
+  /** The `data:` lines of the event, joined with a line feed. */
+  readonly data: string
+  /** The `id:` of the event, when it had one. */
+  readonly id?: string
+  /** The `retry:` of the event in milliseconds, when it had one. */
+  readonly retry?: number
+}
+
+export interface ReadSSEOptions {
+  /** Stops the loop and cancels the response body when it aborts. (Abort the `fetch` itself with the signal you pass to it.) */
+  readonly signal?: AbortSignal
+}
+
+/**
+ * Read the events of a `text/event-stream` response as they arrive. Leaving the loop early (`break`, a thrown error) cancels the body, so the
+ * request to the server ends.
+ * @throws when the response is not `ok` (the status is in the message; the body is cancelled, not parsed), has no body, or fails while it is read.
+ */
+export async function* readSSE(response: Response, options: ReadSSEOptions = {}): AsyncGenerator<SSEEvent, void, undefined> {
+  if (!response.ok) {
+    await response.body?.cancel().catch(() => undefined)
+    throw new Error(`readSSE: the request failed with ${String(response.status)}${response.statusText === '' ? '' : ` ${response.statusText}`}`)
+  }
+  if (response.body === null) throw new Error('readSSE: the response has no body to read')
+  const { signal } = options
+  if (signal?.aborted === true) {
+    await response.body.cancel().catch(() => undefined)
+    return
+  }
+
+  const reader = response.body.getReader()
+  const onAbort = (): void => {
+    void reader.cancel().catch(() => undefined)
+  }
+  signal?.addEventListener('abort', onAbort, { once: true })
+  const decoder = new TextDecoder('utf-8')
+
+  let buffer = ''
+  let skipLineFeed = false
+  let name = ''
+  let data: string[] = []
+  let id: string | undefined
+  let retry: number | undefined
+
+  /** Apply one line; returns the event when this line completes one. */
+  const apply = (line: string): SSEEvent | undefined => {
+    if (line === '') {
+      const event = data.length === 0 ? undefined : { event: name === '' ? 'message' : name, data: data.join('\n'), ...(id === undefined ? {} : { id }), ...(retry === undefined ? {} : { retry }) }
+      name = ''
+      data = []
+      id = undefined
+      retry = undefined
+      return event
+    }
+    if (line.startsWith(':')) return undefined
+    const colon = line.indexOf(':')
+    const field = colon === -1 ? line : line.slice(0, colon)
+    let value = colon === -1 ? '' : line.slice(colon + 1)
+    if (value.startsWith(' ')) value = value.slice(1)
+    if (field === 'event') name = value
+    else if (field === 'data') data.push(value)
+    else if (field === 'id') {
+      if (!value.includes('\u0000')) id = value
+    } else if (field === 'retry' && /^\d+$/u.test(value)) retry = Number(value)
+    return undefined
+  }
+
+  try {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) break
+      let text = decoder.decode(value, { stream: true })
+      // A CR at the end of the last chunk already ended its line; the LF that completes the CRLF may open this one.
+      if (skipLineFeed && text.startsWith('\n')) text = text.slice(1)
+      if (text !== '') skipLineFeed = false
+      buffer += text
+      let start = 0
+      for (let index = 0; index < buffer.length; index += 1) {
+        const code = buffer.charCodeAt(index)
+        if (code !== 10 && code !== 13) continue
+        const line = buffer.slice(start, index)
+        if (code === 13) {
+          if (index + 1 < buffer.length) {
+            if (buffer.charCodeAt(index + 1) === 10) index += 1
+          } else skipLineFeed = true
+        }
+        start = index + 1
+        const event = apply(line)
+        if (event !== undefined) yield event
+      }
+      buffer = buffer.slice(start)
+    }
+  } finally {
+    signal?.removeEventListener('abort', onAbort)
+    await reader.cancel().catch(() => undefined)
+  }
+}

package/plugins/acryl-router/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-router",
-    "commit": "8e23e14336647943d4232047e3ea253e434535d3"
+    "commit": "f132283c43337f5e1d58dfbbbc15786efb5e756c"
   },
   "vendored": [
     "src",
@@ -10,7 +10,7 @@
     "LICENSE"
   ],
   "rewrittenSpecifiers": 6,
-  "digest": "sha256:07772b7e7a2cfe416e4566bebdec7e85fb4abc30466bf104e80342b9fc4ab007",
+  "digest": "sha256:5f07e873992fa2f0a178e029a1fe3d8c99cb4ce3ae8c07445d75431f95125417",
   "testsNotRun": {
     "tests/loader.spec.ts": "loads the built lib/ entry through the real Loader; the library ships source and has no build"
   },

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

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-router-http",
-    "commit": "8e23e14336647943d4232047e3ea253e434535d3"
+    "commit": "f132283c43337f5e1d58dfbbbc15786efb5e756c"
   },
   "vendored": [
     "src",

package/plugins/acryl-state/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-state",
-    "commit": "8e23e14336647943d4232047e3ea253e434535d3"
+    "commit": "f132283c43337f5e1d58dfbbbc15786efb5e756c"
   },
   "vendored": [
     "src",

package/plugins/builder/index.ts

@@ -14,7 +14,7 @@ import type {} from '../instance/index.ts'
 import { builderRules } from './script.ts'
 
 export interface BuilderConfig {
-  /** Where the agent writes extensions. Defaults to `<project>/extensions`. Must be one of the extensions sources. */
+  /** Where the agent writes extensions. Defaults to `<project>/plugins`. Must be one of the extensions sources. */
   dir?: string
   /** Where `package_plugin` writes standalone packages. Defaults to `<project>/plugin-packages`. */
   packagesDir?: string
@@ -64,7 +64,7 @@ export const builder = {
   name: 'builder',
   inject: ['extensions', 'tools', 'appInstance'],
   apply(ctx: Context, config: BuilderConfig) {
-    const dir = resolve(config?.dir ?? join(ctx.appInstance.root, 'extensions'))
+    const dir = resolve(config?.dir ?? join(ctx.appInstance.root, 'plugins'))
     if (!ctx.extensions.sources.some((source) => resolve(source.dir) === dir)) {
       throw new BuilderError(
         `the builder writes into ${dir}, which is not an extensions source; add it to the extensions plugin's sources`,

package/plugins/builder/plugin.json

@@ -7,5 +7,5 @@
   "dependencies": {
     "@deepseek-ai/cordis": "4.0.4"
   },
-  "mount": "mount it after agent and extensions: root.plugin(builder, { dir: join(root, 'extensions') }); dir must be an extensions source"
+  "mount": "mount it after agent and extensions: root.plugin(builder, { dir: join(root, 'plugins') }); dir must be an extensions source"
 }

package/plugins/desktop/main.ts

@@ -10,14 +10,14 @@ import { mkdirSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { app, BrowserWindow, shell } from 'electron'
-import type { App } from '../../app.ts'
+import type { App } from '../../src/app.ts'
 import '../acryl-node-server/src/register.ts'
 import { selectInstance } from '../instance/index.ts'
 import { createDesktopShutdown, installShutdownRequests } from './shutdown.ts'
 import { resolveDesktopUserDataOverride } from './user-data.ts'
 import { windowOptions } from './window.ts'
 
-const projectRoot = fileURLToPath(new URL('../../..', import.meta.url))
+const projectRoot = fileURLToPath(new URL('../..', import.meta.url))
 const chosen = selectInstance({ projectRoot, env: process.env })
 
 /** Where the window opens: `acrylblends.desktopPath` in package.json (the todo template sets `/todo`), else the root. */
@@ -65,7 +65,7 @@ if (!app.requestSingleInstanceLock()) {
 
   void app.whenReady().then(async () => {
     // The hook above is registered before the app's modules are loaded, so the app may have .tsx pages: they are loaded here, not as a static import.
-    const { createApp } = await import('../../app.ts')
+    const { createApp } = await import('../../src/app.ts')
     running = await createApp(chosen)
     const origin = new URL(running.url).origin
     window = new BrowserWindow(windowOptions({ title: chosen.name }))

package/plugins/desktop/plugin.json

@@ -9,8 +9,8 @@
     "electron": "44.9.3"
   },
   "scripts": {
-    "desktop": "electron src/plugins/desktop/main.ts"
+    "desktop": "electron plugins/desktop/main.ts"
   },
   "omit": ["**/*.test.*"],
-  "mount": "nothing to mount: run `npm install`, then `npm run desktop` (the window opens on the app's own server; every electron call is in src/plugins/desktop)"
+  "mount": "nothing to mount: run `npm install`, then `npm run desktop` (the window opens on the app's own server; every electron call is in plugins/desktop)"
 }

package/plugins/desktop/upstream.json

@@ -5,7 +5,7 @@
       "apps/acryl-desktop/src/shell/desktop-user-data.ts": "user-data.ts",
       "apps/acryl-desktop/src/shell/shutdown.ts": "shutdown.ts"
     },
-    "commit": "8e23e14336647943d4232047e3ea253e434535d3"
+    "commit": "f132283c43337f5e1d58dfbbbc15786efb5e756c"
   },
   "rewrittenSpecifiers": 0,
   "digest": "sha256:7dfe960a8bbb476c35540d2202a7aaa62b33492c2ac3e34314e2ecfca45f32f2"

package/plugins/desktop-web/main.ts

@@ -17,7 +17,7 @@ import { createDesktopShutdown, installShutdownRequests } from './shutdown.ts'
 import { resolveDesktopUserDataOverride } from './user-data.ts'
 import { windowOptions } from './window.ts'
 
-const projectRoot = fileURLToPath(new URL('../../..', import.meta.url))
+const projectRoot = fileURLToPath(new URL('../..', import.meta.url))
 const manifest = JSON.parse(readFileSync(join(projectRoot, 'package.json'), 'utf8')) as {
   name?: string
   acrylblends?: { desktopPath?: string }
@@ -73,7 +73,7 @@ if (!app.requestSingleInstanceLock()) {
 
   void app.whenReady().then(async () => {
     // The hook above is registered before the app's modules are loaded, so the app may have .tsx pages: they are loaded here, not as a static import.
-    const { default: acrylApp, close } = (await import('../../app.ts')) as {
+    const { default: acrylApp, close } = (await import('../../src/app.ts')) as {
       default: { fetch: Parameters<typeof serve>[0]['fetch'] }
       close?: () => Promise<void>
     }

package/plugins/desktop-web/plugin.json

@@ -9,9 +9,9 @@
     "electron": "44.9.3"
   },
   "scripts": {
-    "desktop": "electron src/plugins/desktop-web/main.ts"
+    "desktop": "electron plugins/desktop-web/main.ts"
   },
   "gitignore": [".acrylblends/"],
   "omit": ["**/*.test.*"],
-  "mount": "nothing to mount: run `npm install`, then `npm run desktop` (the window opens on the app's own server; every electron call is in src/plugins/desktop-web)"
+  "mount": "nothing to mount: run `npm install`, then `npm run desktop` (the window opens on the app's own server; every electron call is in plugins/desktop-web)"
 }

package/plugins/desktop-web/upstream.json

@@ -5,7 +5,7 @@
       "apps/acryl-desktop/src/shell/desktop-user-data.ts": "user-data.ts",
       "apps/acryl-desktop/src/shell/shutdown.ts": "shutdown.ts"
     },
-    "commit": "8e23e14336647943d4232047e3ea253e434535d3"
+    "commit": "f132283c43337f5e1d58dfbbbc15786efb5e756c"
   },
   "rewrittenSpecifiers": 0,
   "digest": "sha256:7dfe960a8bbb476c35540d2202a7aaa62b33492c2ac3e34314e2ecfca45f32f2"

package/plugins/extensions/index.ts

@@ -55,8 +55,24 @@ export interface ExtensionSource {
   readonly trust: Trust
 }
 
+/** The library copies a plugins folder holds (`library.json`, written by `acrylblends add`): the app mounts them itself, so they are not extensions. */
+function libraryCopies(dir: string): ReadonlySet<string> {
+  try {
+    const listed = (
+      JSON.parse(readFileSync(join(dir, 'library.json'), 'utf8')) as { plugins?: unknown }
+    ).plugins
+    return new Set(
+      Array.isArray(listed)
+        ? listed.filter((name): name is string => typeof name === 'string')
+        : [],
+    )
+  } catch {
+    return new Set()
+  }
+}
+
 export interface ExtensionsConfig {
-  /** Where extension folders may come from. Defaults to `<app home>/extensions`, trusted to install. */
+  /** Where extension folders may come from. An app passes its `plugins/` folder (library copies listed in its `library.json` are skipped). Defaults to `<app home>/extensions`, trusted to install, for a service used without an app folder. */
   sources?: readonly ExtensionSource[]
   /** When true, every source that would install by itself asks for approval instead (`ask`). */
   approval?: boolean
@@ -373,11 +389,13 @@ export class Extensions extends Service {
     const found: Array<{ name: string; dir: string; trust: Trust }> = []
     for (const source of this.sources) {
       if (!existsSync(source.dir)) continue
+      const library = libraryCopies(source.dir)
       for (const entry of readdirSync(source.dir, { withFileTypes: true })) {
         const dir = join(source.dir, entry.name)
         if (
           entry.isDirectory() &&
           NAME.test(entry.name) &&
+          !library.has(entry.name) &&
           ENTRIES.some((file) => existsSync(join(dir, file)))
         ) {
           if (!found.some((other) => other.name === entry.name))

package/plugins/extensions/plugin.json

@@ -8,5 +8,5 @@
     "@deepseek-ai/cordis": "4.0.4",
     "@webboxes/blends-core": "0.4.0"
   },
-  "mount": "mount it after instance: root.plugin(extensions, { sources: [{ dir: join(root, 'extensions'), trust: 'install' }] })"
+  "mount": "mount it after instance: root.plugin(extensions, { sources: [{ dir: join(root, 'plugins'), trust: 'install' }] })"
 }

package/plugins/extensions/resolve.ts

@@ -4,7 +4,7 @@
  * 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
+ * The framework plugins are not packages in an app (they are source under `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 { existsSync, mkdirSync, realpathSync } from 'node:fs'

package/plugins/manifest/lock.ts

@@ -1,7 +1,7 @@
 /**
  * `npm run lock`: write `blend.lock.json` (formatVersion 3, the lock ACRYL writes too) next to the manifest, recording what the app is
  * built from: the manifest's identity and digest, the Blueprint it was resolved over, its resolved parameters and rows, and a content
- * digest of every plugin folder in `src/plugins/` and every extension in `extensions/`. Commit it; a diff of the lock is a review of
+ * digest of every plugin folder in `plugins/`. Commit it; a diff of the lock is a review of
  * what changed.
  */
 import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
@@ -69,7 +69,11 @@ export function writeLock(appRoot: string): LockV3 {
       version: document.metadata.version,
       digest: manifestDigest(text),
     },
-    modules: [...localModules(appRoot, 'src/plugins'), ...localModules(appRoot, 'extensions')],
+    modules: [
+      ...localModules(appRoot, 'plugins'),
+      ...localModules(appRoot, 'src/plugins'),
+      ...localModules(appRoot, 'extensions'),
+    ],
     ...(lineage
       ? {
           lineage: {
@@ -86,7 +90,7 @@ export function writeLock(appRoot: string): LockV3 {
 }
 
 if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-  const appRoot = resolve(fileURLToPath(new URL('../../..', import.meta.url)))
+  const appRoot = resolve(fileURLToPath(new URL('../..', import.meta.url)))
   const locked = writeLock(appRoot)
   console.log(
     `wrote ${LOCK_FILE}: ${locked.rows.length} rows, ${locked.modules.length} local plugins`,

package/plugins/manifest/upgrade-cli.ts

@@ -65,6 +65,6 @@ const parse = (argv: readonly string[]) =>
 if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
   process.exitCode = runUpgrade(
     process.argv.slice(2),
-    resolve(fileURLToPath(new URL('../../..', import.meta.url))),
+    resolve(fileURLToPath(new URL('../..', import.meta.url))),
   )
 }

package/plugins/save/cli.ts

@@ -4,7 +4,7 @@ import { fileURLToPath } from 'node:url'
 import { saveFolder } from './index.ts'
 
 if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-  const appRoot = fileURLToPath(new URL('../../..', import.meta.url))
+  const appRoot = fileURLToPath(new URL('../..', import.meta.url))
   const result = saveFolder(appRoot, process.argv.slice(2).join(' ').trim() || 'save the app')
   if (result.status === 'refused') {
     console.error(`not saved: ${result.reason}`)

package/plugins/save/plugin.json

@@ -8,5 +8,5 @@
     "@deepseek-ai/cordis": "4.0.4",
     "@webboxes/app-persistence": "0.1.1"
   },
-  "mount": "add a script \"save\": \"node src/plugins/save/cli.ts\" to package.json; mount the plugin to give the agent a save_app tool"
+  "mount": "add a script \"save\": \"node plugins/save/cli.ts\" to package.json; mount the plugin to give the agent a save_app tool"
 }

package/plugins/tsconfig.json

@@ -24,6 +24,8 @@
     "acryl-node-server/tests/adapter",
     "acryl-router/tests/loader.spec.ts",
     "acryl-db-sqlite/tests/loader.spec.ts",
+    "acryl-kv-json/tests/loader.spec.ts",
+    "acryl-kv-db/tests/loader.spec.ts",
     "acryl-state/src/react.ts",
     "acryl-state/tests/react.spec.ts",
     "acryl-router-http/tests/adapter.spec.ts",

package/shared/AGENTS.core.md

@@ -9,17 +9,17 @@ Start at `docs/framework/README.md`; `api/summary.md` is the one-page summary. R
 `api/context.md` (`c`), `cordis/validation.md` and `guides/validation.md`, `guides/helpers.md` (`streamSSE`), `concepts/middleware.md`, `cordis/plugin-lifecycle.md` (what a plugin
 owns and when it is unloaded), `cordis/mounting.md` and `cordis/node-server.md`. Pages marked "not yet available" describe parts that are not in this app.
 
-The docs write `import { Acryl } from 'acrylblends'` and `from 'acrylblends/<subpath>'`. In this app the framework is the vendored plugin source in `src/plugins/acryl-router/src`
+The docs write `import { Acryl } from 'acrylblends'` and `from 'acrylblends/<subpath>'`. In this app the framework is the vendored plugin source in `plugins/acryl-router/src`
 (read it, do not edit it: a change belongs in ACRYL, upstream), so from a file in `src/` import:
 
-- `./plugins/acryl-router/src/index.ts` for `Acryl`, `Context`, `HTTPException`, `connectionOf`, `getConnInfo` and the types;
-- `./plugins/acryl-router/src/middleware/index.ts` for every middleware (`cors`, `bodyLimit`, `trimTrailingSlash`, `loopbackOnly`, ...);
-- `./plugins/acryl-router/src/helpers/index.ts` for the helpers and validators (`streamSSE`, `schemaValidator`, `validator`, cookies, `testClient`, ...).
-- `./plugins/acryl-router/src/core/jsx/index.ts` for `acrylblends/jsx` (`jsx`, `Fragment`, the types), and `.../core/jsx/streaming.ts` for `acrylblends/jsx/streaming`.
+- `../plugins/acryl-router/src/index.ts` for `Acryl`, `Context`, `HTTPException`, `connectionOf`, `getConnInfo` and the types;
+- `../plugins/acryl-router/src/middleware/index.ts` for every middleware (`cors`, `bodyLimit`, `trimTrailingSlash`, `loopbackOnly`, ...);
+- `../plugins/acryl-router/src/helpers/index.ts` for the helpers and validators (`streamSSE`, `schemaValidator`, `validator`, cookies, `testClient`, ...).
+- `../plugins/acryl-router/src/core/jsx/index.ts` for `acrylblends/jsx` (`jsx`, `Fragment`, the types), and `.../core/jsx/streaming.ts` for `acrylblends/jsx/streaming`.
 
-**JSX: write `.tsx`.** The scripts in `package.json` run Node.js with `--import ./src/plugins/acryl-node-server/src/register.ts`, which compiles `.tsx` files with this app's own `typescript`; `tsconfig.json` sets `jsx: react-jsx` and `jsxImportSource: #acryl-jsx`, which `package.json`'s `imports` maps to the vendored runtime in `src/plugins/acryl-router`. See `src/about.tsx` (blank template) for a page and `test/app.test.ts` for how it is tested. Render a component with `.toString()` and return it with `c.html(...)`; import `jsx`, `Fragment` and the types from `./plugins/acryl-router/src/core/jsx/index.ts` when you need them. A command that starts the app without those scripts (a bare `node src/main.ts`) cannot load a `.tsx` file. Without a build step you can write the call JSX compiles to instead: `jsx('h1', { class: 'title' }, 'Hello')`, children after the props.
+**JSX: write `.tsx`.** The scripts in `package.json` run Node.js with `--import ./plugins/acryl-node-server/src/register.ts`, which compiles `.tsx` files with this app's own `typescript`; `tsconfig.json` sets `jsx: react-jsx` and `jsxImportSource: #acryl-jsx`, which `package.json`'s `imports` maps to the vendored runtime in `plugins/acryl-router`. See `src/about.tsx` (blank template) for a page and `test/app.test.ts` for how it is tested. Render a component with `.toString()` and return it with `c.html(...)`; import `jsx`, `Fragment` and the types from `../plugins/acryl-router/src/core/jsx/index.ts` when you need them. A command that starts the app without those scripts (a bare `node src/main.ts`) cannot load a `.tsx` file. Without a build step you can write the call JSX compiles to instead: `jsx('h1', { class: 'title' }, 'Hello')`, children after the props.
 
-A plugin written into `extensions/` while the app runs may use the docs' own names instead: `acrylblends` and `acrylblends/<subpath>` resolve to the same files. `App` is the
+A plugin written into `plugins/` while the app runs may use the docs' own names instead: `acrylblends` and `acrylblends/<subpath>` resolve to the same files. `App` is the
 deprecated name of `Acryl`.
 
 ## How a feature is built
@@ -28,8 +28,8 @@ Routes are an ordinary `Acryl` app that a plugin mounts once with `ctx.router.ro
 
 ```ts
 import type { Context } from '@deepseek-ai/cordis'
-import { Acryl, HTTPException } from './plugins/acryl-router/src/index.ts'
-import { schemaValidator, type StandardSchema } from './plugins/acryl-router/src/helpers/index.ts'
+import { Acryl, 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
@@ -44,7 +44,7 @@ export function apply(ctx: Context) {
 
 - 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
+- State, when `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`.

package/shared/DEFAULTS.md

@@ -0,0 +1,40 @@
+
+## Defaults you can swap
+
+The framework is not rigid. Every choice is a plugin behind a port, and what the app starts with is only a fallback. Name the default before you change it,
+and swap it at the one place that mounts it.
+
+| Choice | Default | To swap it |
+| --- | --- | --- |
+| Records | none until you add one: `npx acrylblends add db` mounts the `db` port on SQLite | mount another provider of `db` in `src/app.ts`; plugins use `ctx.db` and do not change |
+| Small state | none until you add one: `npx acrylblends add kv` mounts the `kv` port on one JSON file | mount `acryl-kv-db` (the same port over `db`) or a provider of your own |
+| Server | Node (`acryl-node-server`) | mount the adapter of another runtime in `src/app.ts` |
+| Window | the browser | `npx acrylblends add desktop` adds an Electron window on the same server |
+
+- **An outside tool** (a database server, a bundler, a router such as Vike) joins the app as a provider: a plugin in `plugins/<name>/` that implements a port and
+  passes that port's conformance tests, then `src/app.ts` mounts it. Postgres is such a provider and is not part of this package; add it when the app needs it.
+- **The dependency rule:** only the file that mounts a provider imports it; everything else takes the port as an argument or injects it. `npx acrylblends check-deps` enforces it.
+
+## Plugins
+
+There is one plugin folder: `plugins/` at the root of the app. A plugin is a folder `plugins/<name>/` with an `index.ts`. `npx acrylblends add <name>` copies a library
+plugin there; a plugin you or an agent write goes there too (the `extensions` plugin installs it into the running app, and `plugins/library.json` lists the copies it must not
+install a second time). Do not create `src/plugins/` or `extensions/`.
+
+## The door
+
+The door is a command in this folder, `.acryl/bin/acryl`, that lets you look at and change the running app; it reaches only the app running from this folder. Its state (a secret and an audit log) lives under `.acryl/`, which git ignores: never commit it. If `.acryl/bin/acryl` is not here, this app has no door yet: run it with its scripts and check it with `npm test`.
+
+```
+.acryl/bin/acryl brief                      what this app is: its plugins, where the docs are, the verbs
+.acryl/bin/acryl look                       a snapshot of the page, with refs (r1, r2, ...)
+.acryl/bin/acryl act click --ref <r>
+.acryl/bin/acryl act type --ref <r> --text <t> [--submit] [--no-clear]
+.acryl/bin/acryl act select --ref <r> --option <o>
+.acryl/bin/acryl act press --key <Enter|Escape|...>
+.acryl/bin/acryl act scroll [--ref <r>] --direction up|down [--amount <n>]
+.acryl/bin/acryl act wait (--text <t> | --role <role> [--name <n>]) [--gone] [--timeout-ms <ms>]
+.acryl/bin/acryl plugin list | add <folder> | remove <name> | reload
+.acryl/bin/acryl tool list | call --tool <name> --args '<json>'
+```
+Every verb takes `--json`. `plugin add plugins/<name>` checks the plugin, installs it and makes it live without a restart. `tool call` reaches only the tools on the door's allowlist (empty by default). On Windows the command is `.acryl\bin\acryl.cmd`.

package/shared/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: app-guide
+description: How to change, run and check the __APP_NAME__ app. Use it before adding a feature, a route, a plugin or a dependency to this app, and before saying the work is done.
+---
+
+# Working in __APP_NAME__
+
+1. **Read first.** `AGENTS.md` in this folder says how the app is laid out. The framework's API is in `docs/framework/`: start at `docs/framework/README.md`, and
+   `docs/framework/api/summary.md` is the one-page summary. Parts the docs mark "not yet available" are not in this app.
+2. **Make the change small.** Your own routes are a plugin (`src/routes.ts`) that builds an `Acryl` app and mounts it; test a route with `await app.request('/path')`.
+3. **One plugin folder.** A plugin lives in `plugins/<name>/` (`npx acrylblends add <name>` copies a library plugin there). There is no `src/plugins/` and no `extensions/`.
+4. **Defaults are swappable.** The database, the key-value store, the server and the window are plugins behind ports. The table "Defaults you can swap" in `AGENTS.md` names each default and where it is swapped. Never reach around a port to a driver: `npx acrylblends check-deps` fails the check.
+5. **Look at the running app.** The door is a command in this folder, `.acryl/bin/acryl`, that lets you look at and change the running app; it reaches only the app running from this folder. Its state (a secret and an audit log) lives under `.acryl/`, which git ignores: never commit it. If `.acryl/bin/acryl` is not here, this app has no door yet: run it with its scripts and check it with `npm test`. Start with `.acryl/bin/acryl brief`, then `look` for the page and `act` to click or type on it; the full list is in `AGENTS.md`.
+6. **Done means checked.** `npm test` passes, and the change shows in the running app after a restart. No secret goes in a file or in `git status`: keys come from environment variables.

package/templates/agent/AGENTS.md

@@ -1,6 +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
+Besides `src/routes.ts`, the app runs an agent (`POST /ask`) that can write plugins into `plugins/` 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

@@ -13,14 +13,14 @@ curl -X POST <url>/ask -H 'content-type: application/json' -d '{"question":"add
 # {"status":"completed","output":"The answer is 5.","steps":2}
 ```
 
-- `src/main.ts` chooses where the app lives (`src/plugins/instance`) and starts it.
+- `src/main.ts` chooses where the app lives (`plugins/instance`) and starts it.
 - `blend.yaml` is the app as data: which plugins it mounts, in what order, with what config and parameters. Switch
   one off with `disabled: true`. `npm run lock` writes `blend.lock.json`: the manifest's digest and a digest of
   every plugin folder, so a diff of the lock shows what changed.
 - `src/app.ts` holds the registry of plugins the code provides, and mounts the manifest's rows.
-- `src/plugins/agent` is the offline agent: a scripted model, a tool registry, memory, and one child fiber per run.
-- `src/plugins/extensions` installs, updates and removes plugins while the app runs; a failed update keeps the previous
-  version running. `src/plugins/builder` gives the agent tools to do that itself, writing into `extensions/`.
+- `plugins/agent` is the offline agent: a scripted model, a tool registry, memory, and one child fiber per run.
+- `plugins/extensions` installs, updates and removes plugins while the app runs; a failed update keeps the previous
+  version running. `plugins/builder` gives the agent tools to do that itself, writing into `plugins/`.
 
 Give it a real model and it builds any Cordis plugin you describe (any OpenAI-compatible API; nothing is installed):
 
@@ -40,9 +40,9 @@ 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.
+`list plugins`. What the agent writes lands in `plugins/`, is part of your app, and starts again at the next start.
 - `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.
+- `plugins/` holds the plugins copied from the ACRYLBLENDS library. They are yours now; edit them freely.
   Add more with `acrylblends add <plugin>`.
 
 `npm run save -- "message"` commits the app with git (and pushes when it has a remote). It refuses a file that looks like

package/templates/agent/gitignore

@@ -1,2 +1,3 @@
 node_modules/
 .acrylblends/
+.acryl/

package/templates/agent/package.json

@@ -4,20 +4,20 @@
   "private": true,
   "type": "module",
   "imports": {
-    "#acryl-jsx/jsx-runtime": "./src/plugins/acryl-router/src/core/jsx/jsx-runtime.ts",
-    "#acryl-jsx/jsx-dev-runtime": "./src/plugins/acryl-router/src/core/jsx/jsx-dev-runtime.ts"
+    "#acryl-jsx/jsx-runtime": "./plugins/acryl-router/src/core/jsx/jsx-runtime.ts",
+    "#acryl-jsx/jsx-dev-runtime": "./plugins/acryl-router/src/core/jsx/jsx-dev-runtime.ts"
   },
   "engines": {
     "node": ">=22.19.0"
   },
   "scripts": {
-    "start": "node --import ./src/plugins/acryl-node-server/src/register.ts src/main.ts",
-    "dev": "node --watch --import ./src/plugins/acryl-node-server/src/register.ts src/main.ts",
-    "test": "node --import ./src/plugins/acryl-node-server/src/register.ts --test \"test/**/*.test.{ts,tsx}\"",
+    "start": "node --import ./plugins/acryl-node-server/src/register.ts src/main.ts",
+    "dev": "node --watch --import ./plugins/acryl-node-server/src/register.ts src/main.ts",
+    "test": "node --import ./plugins/acryl-node-server/src/register.ts --test \"test/**/*.test.{ts,tsx}\"",
     "check": "tsc --noEmit",
-    "lock": "node src/plugins/manifest/lock.ts",
-    "save": "node src/plugins/save/cli.ts",
-    "upgrade": "node src/plugins/manifest/upgrade-cli.ts"
+    "lock": "node plugins/manifest/lock.ts",
+    "save": "node plugins/save/cli.ts",
+    "upgrade": "node plugins/manifest/upgrade-cli.ts"
   },
   "dependencies": {
     "typescript": "6.0.3"