acrylblends 1.0.10 → 1.2.0

package/templates/agent/test/app.test.ts

@@ -45,10 +45,24 @@ test('answers health checks and 404 for unknown paths', () =>
   }))
 
 /** 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)
@@ -156,11 +170,75 @@ test('the app has a /settings page with the appearance setting, and the home pag
     assert.match(page, /<select id="theme"/)
     for (const option of ['System', 'Light', 'Dark'])
       assert.match(page, new RegExp(`>(?:Match the )?${option.toLowerCase()}|>${option}<`, 'i'))
-    // The setting is kept in the browser and applied to the home page before it paints.
+    // The setting is kept in the browser and applied to the home page before it paints, by the one script every page of the app can carry.
     const home = await (
       await app.root.router.request('/', { headers: { accept: 'text/html' } })
     ).text()
-    assert.match(home, /localStorage\.getItem\('theme'\)/)
+    assert.match(home, /<script src="\/appearance\.js"><\/script>/)
+    assert.match(page, /<script src="\/appearance\.js"><\/script>/)
     // ... without leaving a global behind for the page's own code to collide with.
     assert.doesNotMatch(home, /<script>\s*(?:var|let|const) /)
+    const script = await app.root.router.request('/appearance.js')
+    assert.equal(script.status, 200)
+    assert.match(script.headers.get('content-type') ?? '', /javascript/)
+    const code = await script.text()
+    assert.match(code, /localStorage\.getItem\('theme'\)/)
+    // A change made in another window of the app is applied here at once, and the colours are custom properties for a page to use.
+    assert.match(code, /addEventListener\('storage'/)
+    for (const token of ['--bg', '--fg', '--muted', '--surface', '--border', '--accent'])
+      assert.ok(code.includes(token), token)
+    assert.match(code, /prefers-color-scheme:dark/)
+    // Run against a stand-in page: it applies the saved choice, follows a change made in another window, and goes back to the system's choice when the setting is removed.
+    const storage = new Map<string, string>([['theme', 'dark']])
+    const dataset: Record<string, string> = {}
+    const appended: Array<{ id: string; textContent: string }> = []
+    const listeners: Array<(event: { key: string | null }) => void> = []
+    new Function('document', 'localStorage', 'addEventListener', code)(
+      {
+        documentElement: { dataset },
+        head: { appendChild: (style: { id: string; textContent: string }) => appended.push(style) },
+        createElement: () => ({ id: '', textContent: '' }),
+      },
+      { getItem: (key: string) => storage.get(key) ?? null },
+      (_type: string, listener: (event: { key: string | null }) => void) =>
+        listeners.push(listener),
+    )
+    assert.equal(dataset.theme, 'dark')
+    assert.equal(appended[0]?.id, 'appearance')
+    storage.set('theme', 'light')
+    for (const listener of listeners) listener({ key: 'theme' })
+    assert.equal(dataset.theme, 'light')
+    storage.delete('theme')
+    for (const listener of listeners) listener({ key: 'something-else' })
+    assert.equal(dataset.theme, 'light')
+    for (const listener of listeners) listener({ key: null })
+    assert.equal(dataset.theme, undefined)
+  }))
+
+test('the frame row mounts the same routes under /app; the app on its own server keeps its old URLs', () =>
+  inEnvironment({ NODE_ENV: 'test', ACRYL_PRODUCTION_KEEP: undefined }, async (app) => {
+    // The frame row claims that prefix on the frame's web adapter only; the app's own rows mount the routes there (the generated app-plugins row),
+    // so the frame row does not ask for the host router (127 app URLs).
+    const frame = await import('../src/frame.ts')
+    assert.deepEqual([...frame.inject].sort(), ['routerHttp'])
+    const { FRAME_MOUNT_PREFIX, routes } = await import('../src/routes.ts')
+    routes.apply(app.root, { prefix: FRAME_MOUNT_PREFIX })
+    for (const path of ['', '/health', '/settings', '/appearance.js']) {
+      const response = await app.root.router.request(`${FRAME_MOUNT_PREFIX}${path}`, {
+        headers: { accept: 'text/html' },
+      })
+      assert.equal(response.status, 200, path)
+      await response.body?.cancel()
+    }
+    // The page under the prefix writes its own URLs from it.
+    const page = await (
+      await app.root.router.request(`${FRAME_MOUNT_PREFIX}/settings`, {
+        headers: { accept: 'text/html' },
+      })
+    ).text()
+    assert.match(page, new RegExp(`src="${FRAME_MOUNT_PREFIX}/appearance.js"`, 'u'))
+    assert.match(page, new RegExp(`href="${FRAME_MOUNT_PREFIX}/"`, 'u'))
+    const missing = await app.root.router.request(`${FRAME_MOUNT_PREFIX}/nope`)
+    assert.equal(missing.status, 404)
+    await missing.body?.cancel()
   }))

package/templates/blank/AGENTS.md

@@ -1,5 +1,6 @@
 
 ## This app (blank)
 
-`src/routes.ts` is the app's own plugin: add routes to its `App`. `blend.yaml` lists the plugins that are mounted. `acrylblends add <plugin>` copies
-another library plugin (for example `acryl-state`) into `plugins/`.
+The first screen (`src/routes.ts`) shows the app's name and, below it, the widget of every plugin that registers one with `ctx.home.widget`
+(the `home` row). A new feature is a plugin of its own with its row in `blend.yaml`, never a change to `src/routes.ts`. `acrylblends add <plugin>`
+copies another library plugin (for example `acryl-state`) into `plugins/`.

package/templates/blank/blend.yaml

@@ -15,9 +15,20 @@ spec:
   rows:
     - id: router
       name: acryl-router
+    # The home page's widgets: a feature plugin puts its UI on the home page with ctx.home.widget, and it leaves with the plugin.
+    - id: home
+      name: home
     - id: routes
       name: routes
+    # A feature is a plugin: its folder plugins/<name>/ plus a row of its own above this one (`- id: notes` / `name: notes`), which Settings > Plugins
+    # switches with `disabled: true`. This row starts the folders that have no row yet (a live install with `.acryl/bin/acryl plugin add`); a folder with
+    # a row is never started twice. Read-only when NODE_ENV=production.
+    - id: extensions
+      name: extensions
     - id: server
       name: acryl-node-server
       config:
         hostname: "{{parameters.hostname}}"
+    # The door: an agent working in this folder looks at the page and acts on it through .acryl/bin/acryl. Development only: src/app.ts leaves it out when NODE_ENV=production.
+    - id: acryl-door
+      name: acryl-door

package/templates/blank/gitignore

@@ -1,3 +1,4 @@
 node_modules/
 .acrylblends/
 .acryl/
+package-lock.json

package/templates/blank/package.json

@@ -16,6 +16,7 @@
     "test": "node --import ./plugins/acryl-node-server/src/register.ts --test \"test/**/*.test.{ts,tsx}\"",
     "check": "tsc --noEmit",
     "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/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/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