acrylblends 1.1.0 → 1.3.0

package/templates/blank/src/app.ts

@@ -1,22 +1,39 @@
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { Context, type Fiber } from '@deepseek-ai/cordis'
+import * as door from '../plugins/acryl-door/src/index.ts'
 import * as nodeServer from '../plugins/acryl-node-server/src/index.ts'
 import * as router from '../plugins/acryl-router/src/index.ts'
+import { extensions } from '../plugins/extensions/index.ts'
+import * as home from '../plugins/home/index.ts'
 import { type AppInstance, instance } from '../plugins/instance/index.ts'
 import {
+  appPluginNames,
   blueprintsIn,
   compose,
+  loadAppPlugins,
   loadManifest,
   type ParameterValue,
 } from '../plugins/manifest/index.ts'
-import { routes } from './routes.ts'
+import { doorEnabled } from './door.ts'
+import { FRAME_MOUNT_PREFIX, routes } from './routes.ts'
 
-/** The plugins this app's code provides. `blend.yaml` chooses, orders and configures them. */
-export const registry = { 'acryl-router': router, 'acryl-node-server': nodeServer, routes }
+/** The plugins this app's code provides. `blend.yaml` chooses, orders and configures them, and adds the app's own plugins from `plugins/` by name. */
+export const registry = {
+  'acryl-router': router,
+  'acryl-node-server': nodeServer,
+  'acryl-door': door,
+  home,
+  extensions,
+  routes,
+}
+
+const projectRoot = fileURLToPath(new URL('..', import.meta.url))
 
 /** The manifest next to this app's source. */
-export const MANIFEST = join(fileURLToPath(new URL('..', import.meta.url)), 'blend.yaml')
+export const MANIFEST = join(projectRoot, 'blend.yaml')
+/** The app's plugins: the library copies `registry` imports, and the app's own plugins (a feature each), which `blend.yaml` mounts by their folder name. */
+const PLUGINS_DIR = join(projectRoot, 'plugins')
 
 /**
  * The app's manifest, resolved. A Blend finds its Blueprint in `blueprints/<id>.yaml`; an app that is itself a Blueprint never looks.
@@ -24,18 +41,21 @@ export const MANIFEST = join(fileURLToPath(new URL('..', import.meta.url)), 'ble
  */
 export function readManifest(values?: Readonly<Record<string, ParameterValue>>) {
   return loadManifest(MANIFEST, {
-    known: Object.keys(registry),
-    getBlueprint: blueprintsIn(join(fileURLToPath(new URL('..', import.meta.url)), 'blueprints')),
+    known: [...Object.keys(registry), ...appPluginNames(PLUGINS_DIR)],
+    getBlueprint: blueprintsIn(join(projectRoot, 'blueprints')),
     ...(values ? { values } : {}),
   })
 }
 
-/** The manifest without its server row: the app is then reached in process, through `root.router.request`. */
-function withoutServer<M extends { plugins: readonly { use: string }[] }>(manifest: M): M {
+/** The manifest without some rows: without its server (and so its door) the app is reached in process, through `root.router.request`; the door is also left out in production. */
+function without<M extends { plugins: readonly { use: string }[] }>(
+  manifest: M,
+  ...uses: string[]
+): M {
   return {
     ...manifest,
     plugins: manifest.plugins.map((row) =>
-      row.use === 'acryl-node-server' ? { ...row, disabled: true } : row,
+      uses.includes(row.use) ? { ...row, disabled: true } : row,
     ),
   }
 }
@@ -47,30 +67,81 @@ export interface App {
   stop(): Promise<void>
 }
 
-/** The app: `instance` first (where it lives, chosen at run time), then the manifest's rows in order. */
-export async function createApp(
+export interface AppOptions {
+  readonly values?: Readonly<Record<string, ParameterValue>>
+  /** The path the app is mounted at; absent on its own server, where it keeps the root, and {@link FRAME_MOUNT_PREFIX} in the frame. */
+  readonly prefix?: string
+  /** Start the HTTP server (default). Tests pass `false` and call `app.root.router.request(path)`: it needs no port, so it also runs where a sandbox forbids listening. */
+  readonly listen?: boolean
+}
+
+/** The rows the frame host provides: the app contributes only the plugins that are its own. */
+const HOST_ROWS = [
+  'instance',
+  'acryl-router',
+  'acryl-node-server',
+  'acryl-web-server',
+  'acryl-page',
+  'manifest',
+  'save',
+  'acryl-door',
+]
+
+/**
+ * The app's rows, composed into `ctx`: the app's own server calls this from `createApp`, and the generated frame layer mounts it as one row, so the frame
+ * runs the app exactly as the app's own server does (same rows, same order, same config). `host: true` leaves the infrastructure rows to the frame host,
+ * which is where the door lives too, and mounts the app at {@link FRAME_MOUNT_PREFIX}.
+ */
+export async function composeInto(
+  ctx: Context,
   chosen: AppInstance,
-  options: {
-    values?: Readonly<Record<string, ParameterValue>>
-    /** Start the HTTP server (default). Tests pass `false` and call `app.root.router.request(path)`: it needs no port, so it also runs where a sandbox forbids listening. */
-    listen?: boolean
-  } = {},
-): Promise<App> {
-  const manifest = readManifest(options.values)
+  options: AppOptions & { readonly host?: boolean } = {},
+): Promise<Fiber[]> {
+  const read = readManifest(options.values)
+  const own = options.host !== true && options.listen !== false
+  // The frame host mounts the app under its own prefix; the app's own server keeps the root.
+  const prefix = options.prefix ?? (options.host === true ? FRAME_MOUNT_PREFIX : undefined)
+  // Rows left out: the server (and the door, which needs it) when the app is reached in process or inside the frame host; the door when it is switched
+  // off.
+  const leaveOut = new Set<string>(options.host === true ? HOST_ROWS : [])
+  if (!own) leaveOut.add('acryl-node-server').add('acryl-door')
+  if (!doorEnabled()) leaveOut.add('acryl-door')
+  const manifest = without(read, ...leaveOut)
+  // The rows that name one of the app's own plugin folders (a feature: plugins/<name>/ and its row) rather than a registry import. Each one that runs
+  // is imported here; all of them, off or on, belong to their row, so the extensions row never starts them a second time.
+  const ownRows = [
+    ...new Set(read.plugins.map((row) => row.use).filter((use) => !Object.hasOwn(registry, use))),
+  ]
+  const ownPlugins = await loadAppPlugins(
+    PLUGINS_DIR,
+    ownRows.filter((use) => manifest.plugins.some((row) => row.use === use && !row.disabled)),
+  )
+  return compose(
+    ctx,
+    manifest,
+    { ...registry, ...ownPlugins },
+    {
+      // The routes row mounts the pages (and the client modules) at the prefix the frame host chose.
+      routes: { ...(prefix === undefined ? {} : { prefix }) },
+      // The app's own plugins live in plugins/, next to the plugins copied from the library (plugins/library.json lists those, so they are not installed twice).
+      // In production they start read-only from where they are deployed: the app keeps its features, and nothing can be installed while it runs.
+      extensions: {
+        ...(process.env.NODE_ENV === 'production' ? { readOnly: true } : {}),
+        sources: [{ dir: PLUGINS_DIR, trust: 'install' }],
+        rows: ownRows,
+      },
+      // Only the app's own server listens; the frame host owns the server and its port.
+      ...(own ? { server: { port: chosen.port.start, scan: chosen.port.scan ? 20 : 0 } } : {}),
+    },
+  )
+}
+
+/** The app: `instance` first (where it lives, chosen at run time), then the manifest's rows in order. */
+export async function createApp(chosen: AppInstance, options: AppOptions = {}): Promise<App> {
   const root = new Context()
   const first = root.plugin(instance, chosen)
   await first.await()
-  const fibers: Fiber[] = [
-    first,
-    ...(await compose(
-      root,
-      options.listen === false ? withoutServer(manifest) : manifest,
-      registry,
-      {
-        server: { port: chosen.port.start, scan: chosen.port.scan ? 20 : 0 },
-      },
-    )),
-  ]
+  const fibers: Fiber[] = [first, ...(await composeInto(root, chosen, options))]
   return {
     root,
     url: options.listen === false ? '' : root.nodeServer.url,

package/templates/blank/src/door.ts

@@ -0,0 +1,7 @@
+/**
+ * The door (`plugins/acryl-door`) lets an agent working in this folder look at the running page and act on it, through `.acryl/bin/acryl`. It is on in development
+ * and off in production (`NODE_ENV=production`) and when `ACRYL_DOOR=off`: `src/app.ts` leaves its row out then, and the pages leave its script tag out. One process
+ * at a time serves a folder's door, so the tests that start the real server set `ACRYL_DOOR=off` and a second `npm start` beside a running one does not fail on it.
+ */
+export const doorEnabled = (): boolean =>
+  process.env.NODE_ENV !== 'production' && process.env.ACRYL_DOOR !== 'off'

package/templates/blank/src/first-page.ts

@@ -0,0 +1,5 @@
+/**
+ * The sentence the first screen carries. The desktop door's frame probe imports this same value, so the page's text and the probe's expectation can never
+ * drift apart again (the probe outlived the JSON root it was written for by one template change).
+ */
+export const FIRST_PAGE_MARKER = 'This is the page the ACRYL frame opens first'

package/templates/blank/src/frame.ts

@@ -0,0 +1,17 @@
+/**
+ * The app as the ACRYL frame hosts it (`npm run dev`): the generated layer mounts this row, which claims {@link FRAME_MOUNT_PREFIX} on the frame's web
+ * server. The app's own rows (the generated `app-plugins` row, which calls `composeInto`) mount the app at that prefix, so its pages and its client
+ * component answer at `/app`. Nothing here runs in production: `npm start` composes the app on its own server (no `routerHttp` service, so this row is not
+ * mounted there), where the app keeps the root as it always did.
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import { FRAME_MOUNT_PREFIX } from './routes.ts'
+
+export const name = 'app-routes'
+
+/** The frame always has it: its layer carries the router and the web adapter. */
+export const inject = ['routerHttp']
+
+export function apply(ctx: Context): void {
+  ctx.routerHttp.mount(FRAME_MOUNT_PREFIX)
+}

package/templates/blank/src/routes.ts

@@ -1,18 +1,75 @@
 import type { Context } from '@deepseek-ai/cordis'
 import { Acryl } from '../plugins/acryl-router/src/index.ts'
+import { type Home, renderWidgets } from '../plugins/home/index.ts'
 import { aboutPage } from './about.tsx'
+import { FIRST_PAGE_MARKER } from './first-page.ts'
 
 export const APP_NAME = '__APP_NAME__'
 
-/** The app's own routes: an `App` mounted on the router. The mount is removed when this plugin is disposed. */
-export const routes = {
-  name: 'routes',
-  inject: ['router'],
-  apply(ctx: Context) {
-    const app = new Acryl()
-      .get('/', (c) => c.json({ app: APP_NAME, ok: true }))
+/**
+ * The only place the app's mount prefix is named. On its own server (production, `npm start`) the app mounts at the root and
+ * its public URLs are `/`, `/about`, `/health`; when the ACRYL frame hosts it (`npm run dev`) the routes mount here, and the
+ * frame opens its tile at `/app/`. Every page link and asset URL this template writes is derived from the prefix it is
+ * mounted at, so the same source serves both.
+ */
+export const FRAME_MOUNT_PREFIX = '/app'
+
+/** The scaffold's name comes from the folder, so the first screen escapes it like any other user text. */
+const escapeHtml = (text: string): string =>
+  text
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+
+/**
+ * The first screen: the page a browser gets at the root, which is what the ACRYL frame's first tile shows. A blank app whose root answered JSON to
+ * every client gave the tile Chrome's JSON viewer, nearly invisible in the frame's dark surface (owner review, 2026-11-02); the root now answers a page
+ * to a browser and the JSON hello to everything else, the way the agent template does. The About link is relative, so it works under the frame's /app
+ * mount and on the app's own server alike.
+ */
+const homePage = (name: string, widgets: string): string => `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>${escapeHtml(name)}</title>
+    <style>:root{color-scheme:light dark;background:Canvas;color:CanvasText}body{margin:2rem auto;max-width:44rem;padding:0 1rem;font:15px/1.55 system-ui,-apple-system,"Segoe UI",sans-serif}h1{font-size:1.6rem;margin:0 0 .5rem}a{color:#5468ff}code{font:.9em ui-monospace,"SF Mono",Menlo,monospace}</style>
+  </head>
+  <body>
+    <main>
+      <h1>${escapeHtml(name)}</h1>
+      <p>Your app is running. ${FIRST_PAGE_MARKER}; edit <code>src/routes.ts</code> to change it.</p>
+      <p><a href="./about">About</a></p>
+      ${widgets}
+    </main>
+  </body>
+</html>`
+
+/**
+ * The app's own pages and routes, mountable at any prefix: the standalone server mounts it at the root, the frame host at {@link FRAME_MOUNT_PREFIX}.
+ * The first screen shows the widgets of the app's plugins (`ctx.home`), read at each request, so a plugin switched on or off shows at the next load.
+ */
+export function makeApp(home: Home): Acryl {
+  return (
+    new Acryl()
+      // A browser gets the first screen; an API client gets the JSON hello.
+      .get('/', async (c) =>
+        (c.req.header('accept') ?? '').includes('text/html')
+          ? c.html(homePage(APP_NAME, await renderWidgets(home)))
+          : c.json({ app: APP_NAME, ok: true }),
+      )
       .get('/health', (c) => c.json({ ok: true }))
       .get('/about', (c) => c.html(aboutPage()))
-    ctx.router.route('/', app)
+  )
+}
+
+/** The app's own routes: an `App` mounted on the router at `options.prefix` (empty or absent: the root). The mount is removed when this plugin is disposed. */
+export const routes = {
+  name: 'routes',
+  inject: ['router', 'home'],
+  apply(ctx: Context, options: { readonly prefix?: string } = {}) {
+    const prefix = options.prefix ?? ''
+    ctx.router.route(prefix === '' ? '/' : prefix, makeApp(ctx.home))
   },
 }

package/templates/blank/template.json

@@ -1 +1,14 @@
-{ "plugins": ["instance", "acryl-router", "acryl-node-server", "manifest", "save"] }
+{
+  "plugins": [
+    "instance",
+    "acryl-router",
+    "acryl-node-server",
+    "manifest",
+    "save",
+    "home",
+    "extensions",
+    "acryl-door",
+    "acryl-web-server",
+    "acryl-page"
+  ]
+}

package/templates/blank/test/app.test.ts

@@ -6,8 +6,8 @@ import { join } from 'node:path'
 import { test } from 'node:test'
 import { fileURLToPath } from 'node:url'
 import { pinnedInstance, withPort } from '../plugins/instance/index.ts'
-import { type App, createApp } from '../src/app.ts'
-import { APP_NAME } from '../src/routes.ts'
+import { type App, type AppOptions, createApp } from '../src/app.ts'
+import { APP_NAME, FRAME_MOUNT_PREFIX } from '../src/routes.ts'
 
 /** Throwaway homes live inside the project (`.acrylblends/` is ignored by git): a sandboxed agent may not write to the system temp folder. */
 const scratch = join(fileURLToPath(new URL('..', import.meta.url)), '.acrylblends', 'test')
@@ -16,9 +16,10 @@ mkdirSync(scratch, { recursive: true })
 const projectRoot = fileURLToPath(new URL('..', import.meta.url))
 
 /** Boot the app in a throwaway home on any free port, run the test, always stop it and remove the home. */
-async function withApp(run: (app: App) => Promise<void>) {
+async function withApp(run: (app: App) => Promise<void>, options: AppOptions = {}) {
   const home = await mkdtemp(join(scratch, 'app-test-'))
   const app = await createApp(withPort(pinnedInstance(home, { root: projectRoot }), 0), {
+    ...options,
     listen: false,
   })
   try {
@@ -29,11 +30,20 @@ async function withApp(run: (app: App) => Promise<void>) {
   }
 }
 
-test('serves the index route', () =>
+test('serves the index route: the first screen to a browser, the JSON hello to an API client', () =>
   withApp(async (app) => {
-    const response = await app.root.router.request(`/`)
-    assert.equal(response.status, 200)
-    assert.deepEqual(await response.json(), { app: APP_NAME, ok: true })
+    const api = await app.root.router.request(`/`)
+    assert.equal(api.status, 200)
+    assert.deepEqual(await api.json(), { app: APP_NAME, ok: true })
+    const page = await app.root.router.request(`/`, {
+      headers: { accept: 'text/html,application/xhtml+xml,*/*;q=0.8' },
+    })
+    assert.equal(page.status, 200)
+    assert.match(page.headers.get('content-type') ?? '', /text\/html/)
+    const html = await page.text()
+    // The ACRYL frame's first tile asks for a page: the root must never hand it JSON (Chrome's viewer is nearly invisible in the dark frame).
+    assert.ok(html.includes(`<h1>${APP_NAME}</h1>`), 'the page names the app')
+    assert.ok(html.includes('href="./about"'), 'the page links to About relatively')
   }))
 
 test('renders a .tsx page, and an error in it names the .tsx line', () =>
@@ -59,11 +69,78 @@ test('answers health checks and 404 for unknown paths', () =>
     await missing.body?.cancel()
   }))
 
+test('the frame mounts the same app under /app; the app on its own server keeps its old URLs', async () => {
+  // Standalone (production, `npm start`): the public URLs do not move.
+  await withApp(async (app) => {
+    for (const path of ['/', '/about', '/health']) {
+      const response = await app.root.router.request(path)
+      assert.equal(response.status, 200, path)
+      await response.body?.cancel()
+    }
+  })
+  // The frame composes the same blend.yaml rows at the one prefix the app names; src/frame.ts only claims that prefix on the frame's web server.
+  const frame = await import('../src/frame.ts')
+  assert.deepEqual([...frame.inject], ['routerHttp'])
+  await withApp(
+    async (app) => {
+      for (const path of ['', '/about', '/health']) {
+        const response = await app.root.router.request(`${FRAME_MOUNT_PREFIX}${path}`)
+        assert.equal(response.status, 200, path)
+        await response.body?.cancel()
+      }
+      const missing = await app.root.router.request(`${FRAME_MOUNT_PREFIX}/nope`)
+      assert.equal(missing.status, 404)
+      await missing.body?.cancel()
+    },
+    { prefix: FRAME_MOUNT_PREFIX },
+  )
+})
+
+test('a plugin puts its widget on the first screen, and the widget leaves with the plugin', () =>
+  withApp(async (app) => {
+    const page = async () =>
+      (await app.root.router.request('/', { headers: { accept: 'text/html' } })).text()
+    const feature = app.root.plugin({
+      name: 'hello-widget',
+      inject: ['home'],
+      apply(ctx: typeof app.root) {
+        ctx.effect(() =>
+          ctx.home.widget({
+            id: 'hello-widget',
+            title: 'Hello',
+            render: () => '<p id="hello">hi</p>',
+          }),
+        )
+      },
+    })
+    await feature.await()
+    assert.match(
+      await page(),
+      /<section class="widget" data-widget="hello-widget">[\s\S]*<p id="hello">hi<\/p>/,
+    )
+    await feature.dispose()
+    assert.doesNotMatch(await page(), /data-widget="hello-widget"/)
+  }))
+
 /** A sandbox may forbid listening on a port (Codex's workspace-write does); the one test that starts the real server is skipped there, and says so. */
+/**
+ * Whether this environment forbids listening at all: only a sandbox's refusal (EPERM/EACCES) means the real-server test must skip. A loaded
+ * machine can fail a bind transiently, so that is retried briefly; any other outcome lets the real test run, where a host that truly cannot
+ * listen fails loudly instead of hiding behind a skip.
+ */
 const canListen = await new Promise<boolean>((done) => {
-  const probe = createServer()
-  probe.once('error', () => done(false))
-  probe.listen(0, '127.0.0.1', () => probe.close(() => done(true)))
+  let attempts = 0
+  const probeOnce = (): void => {
+    attempts += 1
+    const probe = createServer()
+    probe.once('error', (error: NodeJS.ErrnoException) => {
+      if (error.code === 'EPERM' || error.code === 'EACCES') done(false)
+      else if (attempts < 3) setTimeout(probeOnce, 100)
+      else done(true)
+    })
+    probe.listen(0, '127.0.0.1', () => probe.close(() => done(true)))
+  }
+  probeOnce()
 })
 const skip = canListen ? false : 'this environment does not allow listening on a port'
 if (!canListen)
@@ -72,19 +149,29 @@ if (!canListen)
   )
 
 test('stops listening when stopped', { skip }, async () => {
+  // One process at a time serves a folder's door, and in the frame the frame's own door serves this folder: this server starts without one.
+  const door = process.env.ACRYL_DOOR
+  process.env.ACRYL_DOOR = 'off'
   const home = await mkdtemp(join(scratch, 'app-test-'))
-  const app = await createApp(withPort(pinnedInstance(home, { root: projectRoot }), 0))
-  await app.stop()
-  await assert.rejects(fetch(`${app.url}/health`))
-  await rm(home, { recursive: true, force: true })
+  try {
+    const app = await createApp(withPort(pinnedInstance(home, { root: projectRoot }), 0))
+    await app.stop()
+    await assert.rejects(fetch(`${app.url}/health`))
+  } finally {
+    if (door === undefined) delete process.env.ACRYL_DOOR
+    else process.env.ACRYL_DOOR = door
+    await rm(home, { recursive: true, force: true })
+  }
 })
 
 test('the manifest decides what is mounted: a parameter changes the server, an unknown value is refused', async () => {
   const { readManifest } = await import('../src/app.ts')
   const manifest = readManifest()
+  // The template's rows, in their order; a feature's row (plugins/<name>/) may sit between them.
+  const library = ['router', 'home', 'routes', 'extensions', 'server', 'acryl-door']
   assert.deepEqual(
-    manifest.plugins.map((row) => row.id),
-    ['router', 'routes', 'server'],
+    manifest.plugins.map((row) => row.id).filter((id) => library.includes(id)),
+    library,
   )
   assert.throws(() => readManifest({ nothing: 1 }), /parameter-override-unknown/)
 })

package/templates/chat/.gitattributes

@@ -0,0 +1,2 @@
+# Every checkout has the same line endings, on every OS. A plugin's digest counts every byte, so a CRLF checkout would make it a different plugin.
+* text=auto eol=lf

package/templates/chat/blend.yaml

@@ -20,7 +20,8 @@ spec:
       name: acryl-db-sqlite
     - id: routes
       name: routes
-    # Plugins installed while the app runs (the door's `plugin add`): development only, src/app.ts leaves it out when NODE_ENV=production.
+    # Plugin folders without a row of their own (a live install with the door's `plugin add`); a folder with a row is the app's and starts by it.
+    # Read-only when NODE_ENV=production.
     - id: extensions
       name: extensions
     - id: server

package/templates/chat/gitignore

@@ -4,3 +4,4 @@ node_modules/
 data/
 *.sqlite
 *.sqlite-*
+package-lock.json

package/templates/chat/package.json

@@ -17,6 +17,7 @@
     "check": "tsc --noEmit && tsc --noEmit -p src/client && acrylblends check-deps",
     "build": "acrylblends build-client",
     "lock": "node plugins/manifest/lock.ts",
+    "snapshot": "node plugins/manifest/snapshot.ts",
     "save": "node plugins/save/cli.ts",
     "upgrade": "node plugins/manifest/upgrade-cli.ts"
   },

package/templates/chat/src/app.ts

@@ -8,13 +8,15 @@ import * as router from '../plugins/acryl-router/src/index.ts'
 import { extensions } from '../plugins/extensions/index.ts'
 import { type AppInstance, instance } from '../plugins/instance/index.ts'
 import {
+  appPluginNames,
   blueprintsIn,
   compose,
+  loadAppPlugins,
   loadManifest,
   type ParameterValue,
 } from '../plugins/manifest/index.ts'
 import { doorEnabled } from './door.ts'
-import { routes } from './routes.ts'
+import { FRAME_MOUNT_PREFIX, routes } from './routes.ts'
 
 /** The plugins this app's code provides. `blend.yaml` chooses, orders and configures them. */
 export const registry = {
@@ -30,11 +32,13 @@ const projectRoot = fileURLToPath(new URL('..', import.meta.url))
 
 /** The manifest next to this app's source. */
 export const MANIFEST = join(projectRoot, 'blend.yaml')
+/** The app's plugins: the library copies `registry` imports, and the app's own plugins (a feature each), which `blend.yaml` mounts by their folder name. */
+const PLUGINS_DIR = join(projectRoot, 'plugins')
 
 /** The manifest, resolved. `createApp` and the tests read it the same way. */
 export function readManifest(values?: Readonly<Record<string, ParameterValue>>) {
   return loadManifest(MANIFEST, {
-    known: Object.keys(registry),
+    known: [...Object.keys(registry), ...appPluginNames(PLUGINS_DIR)],
     getBlueprint: blueprintsIn(join(projectRoot, 'blueprints')),
     ...(values ? { values } : {}),
   })
@@ -64,42 +68,88 @@ export interface AppOptions {
   readonly values?: Readonly<Record<string, ParameterValue>>
   /** The SQLite file, relative to the app folder; an absolute path is used as it is (tests give a file in a throwaway home). Default: `data/chat.sqlite`. */
   readonly database?: string
+  /** The path the app is mounted at; absent on its own server, where it keeps the root, and {@link FRAME_MOUNT_PREFIX} in the frame. */
+  readonly prefix?: string
   /** Start the HTTP server (default). Tests pass `false` and call `app.root.router.request(path)`: it needs no port, so it also runs where a sandbox forbids listening. */
   readonly listen?: boolean
 }
 
+/** The rows the frame host provides: the app contributes only the plugins that are its own. */
+const HOST_ROWS = [
+  'instance',
+  'acryl-router',
+  'acryl-node-server',
+  'acryl-web-server',
+  'acryl-page',
+  'manifest',
+  'save',
+  'acryl-door',
+]
+
 /**
- * The app: `instance` first (where it lives, chosen at run time), then the manifest's rows in order. The `db` row opens the database and applies
- * `migrations/`; the one place that names the SQLite provider is this file (`acrylblends check-deps`), so a different provider is a change here.
+ * The app's rows, composed into `ctx`: the app's own server calls this from `createApp`, and the generated frame layer mounts it as one row, so the frame
+ * runs the app exactly as the app's own server does (same rows, same order, same config). `host: true` leaves the infrastructure rows to the frame host,
+ * which is where the door lives too, and mounts the app at {@link FRAME_MOUNT_PREFIX}. The `db` row opens the database and applies `migrations/`; the one
+ * place that names the SQLite provider is this file (`acrylblends check-deps`), so a different provider is a change here.
  */
-export async function createApp(chosen: AppInstance, options: AppOptions = {}): Promise<App> {
+export async function composeInto(
+  ctx: Context,
+  chosen: AppInstance,
+  options: AppOptions & { readonly host?: boolean } = {},
+): Promise<Fiber[]> {
   const read = readManifest(options.values)
-  const listen = options.listen
-  // Rows left out: the server (and the door, which needs it) when the app is reached in process; the door when it is switched off; live plugin installs in production.
-  const leaveOut = new Set<string>()
-  if (listen === false) leaveOut.add('acryl-node-server').add('acryl-door')
+  const own = options.host !== true && options.listen !== false
+  // The frame host mounts the app under its own prefix; the app's own server keeps the root.
+  const prefix = options.prefix ?? (options.host === true ? FRAME_MOUNT_PREFIX : undefined)
+  // Rows left out: the server (and the door, which needs it) when the app is reached in process or inside the frame host; the door when it is switched
+  // off.
+  const leaveOut = new Set<string>(options.host === true ? HOST_ROWS : [])
+  if (!own) leaveOut.add('acryl-node-server').add('acryl-door')
   if (!doorEnabled()) leaveOut.add('acryl-door')
-  if (process.env.NODE_ENV === 'production') leaveOut.add('extensions')
   const manifest = without(read, ...leaveOut)
+  // The rows that name one of the app's own plugin folders (a feature: plugins/<name>/ and its row) rather than a registry import. Each one that runs
+  // is imported here; all of them, off or on, belong to their row, so the extensions row never starts them a second time.
+  const ownRows = [
+    ...new Set(read.plugins.map((row) => row.use).filter((use) => !Object.hasOwn(registry, use))),
+  ]
+  const ownPlugins = await loadAppPlugins(
+    PLUGINS_DIR,
+    ownRows.filter((use) => manifest.plugins.some((row) => row.use === use && !row.disabled)),
+  )
   const file = options.database ?? 'data/chat.sqlite'
-  const root = new Context()
-  const first = root.plugin(instance, chosen)
-  await first.await()
-  const fibers: Fiber[] = [
-    first,
-    ...(await compose(root, manifest, registry, {
+  return compose(
+    ctx,
+    manifest,
+    { ...registry, ...ownPlugins },
+    {
       db: {
         path: isAbsolute(file) ? file : resolve(projectRoot, file),
         migrations: join(projectRoot, 'migrations'),
       },
-      // What is installed while the app runs lives in plugins/, next to the plugins copied from the library (plugins/library.json lists those, so they are not installed twice).
-      extensions: { sources: [{ dir: join(projectRoot, 'plugins'), trust: 'install' }] },
-      server: { port: chosen.port.start, scan: chosen.port.scan ? 20 : 0 },
-    })),
-  ]
+      // The routes row mounts the app (and its client modules) at the prefix the frame host chose.
+      routes: { ...(prefix === undefined ? {} : { prefix }) },
+      // The app's own plugins live in plugins/, next to the plugins copied from the library (plugins/library.json lists those, so they are not installed twice).
+      // In production they start read-only from where they are deployed: the app keeps its features, and nothing can be installed while it runs.
+      extensions: {
+        ...(process.env.NODE_ENV === 'production' ? { readOnly: true } : {}),
+        sources: [{ dir: PLUGINS_DIR, trust: 'install' }],
+        rows: ownRows,
+      },
+      // Only the app's own server listens; the frame host owns the server and its port.
+      ...(own ? { server: { port: chosen.port.start, scan: chosen.port.scan ? 20 : 0 } } : {}),
+    },
+  )
+}
+
+/** The app: `instance` first (where it lives, chosen at run time), then the manifest's rows in order. */
+export async function createApp(chosen: AppInstance, options: AppOptions = {}): Promise<App> {
+  const root = new Context()
+  const first = root.plugin(instance, chosen)
+  await first.await()
+  const fibers: Fiber[] = [first, ...(await composeInto(root, chosen, options))]
   return {
     root,
-    url: listen === false ? '' : root.nodeServer.url,
+    url: options.listen === false ? '' : root.nodeServer.url,
     async stop() {
       for (const fiber of [...fibers].reverse()) await fiber.dispose()
     },