acrylblends 1.1.0 → 1.2.0

package/templates/notes/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/notes/gitignore

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

package/templates/notes/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/notes/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/notes.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/notes.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()
     },

package/templates/notes/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
+ * modules 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/notes/src/notes-app.ts

@@ -24,6 +24,8 @@ export interface AppOptions {
   trustProxy?: boolean
   /** The address people use in the browser, for example `https://notes.example.com`. Behind a proxy the app sees `http://127.0.0.1:3000`, so csrf needs it. Default: PUBLIC_ORIGIN. */
   publicOrigin?: string
+  /** The path the app is mounted at: '' on its own server, `/app` in the ACRYL frame. Every link, form action and redirect is written from it. */
+  prefix?: string
 }
 
 export function createApi(db: Db) {
@@ -74,11 +76,14 @@ export function createApp(
   {
     trustProxy = process.env.TRUST_PROXY === '1',
     publicOrigin = process.env.PUBLIC_ORIGIN,
+    prefix = '',
   }: AppOptions = {},
 ) {
   const auth = authStore(db)
   const notes = notesStore(db)
   const app = new Acryl<Env>()
+  // Every URL the pages and redirects write starts at the path the app is mounted at.
+  const at = (path: string): string => `${prefix}${path}`
   // Refuses a form POST that does not come from this site (checks Origin and Sec-Fetch-Site); JSON requests are not form-shaped and pass.
   app.use(csrf(publicOrigin ? { origin: [publicOrigin] } : undefined))
   // A secure cookie is only sent over HTTPS: set when the request is HTTPS, or a proxy we trust says it was.
@@ -100,14 +105,14 @@ export function createApp(
 
   const requireUser = createMiddleware<Env>(async (c, next) => {
     const user = await auth.userFor(getCookie(c, COOKIE))
-    if (!user) return c.redirect('/login')
+    if (!user) return c.redirect(at('/login'))
     c.set('user', user)
     await next()
   })
 
-  app.get('/', (c) => c.redirect('/notes'))
-  app.get('/signup', (c) => c.html(authPage('signup')))
-  app.get('/login', (c) => c.html(authPage('login')))
+  app.get('/', (c) => c.redirect(at('/notes')))
+  app.get('/signup', (c) => c.html(authPage('signup', [], '', prefix)))
+  app.get('/login', (c) => c.html(authPage('login', [], '', prefix)))
 
   app.post('/signup', async (c) => {
     const form = await c.req.parseBody()
@@ -117,10 +122,10 @@ export function createApp(
     const errors = checkCredentials(email, form.password, true)
     if (errors.length === 0 && (await auth.findUser(email)))
       errors.push('That email already has an account. Log in instead.')
-    if (errors.length > 0) return c.html(authPage('signup', errors, email), 400)
+    if (errors.length > 0) return c.html(authPage('signup', errors, email, prefix), 400)
     const id = await auth.createUser(email, String(form.password))
     setCookie(c, COOKIE, await auth.startSession(id), session(c))
-    return c.redirect('/notes', 303)
+    return c.redirect(at('/notes'), 303)
   })
 
   app.post('/login', async (c) => {
@@ -129,19 +134,19 @@ export function createApp(
       .trim()
       .toLowerCase()
     const errors = checkCredentials(email, form.password, false)
-    if (errors.length > 0) return c.html(authPage('login', errors, email), 400)
+    if (errors.length > 0) return c.html(authPage('login', errors, email, prefix), 400)
     const user = await auth.findUser(email)
     if (!user || !(await verifyPassword(String(form.password), user.password_hash)))
-      return c.html(authPage('login', ['Wrong email or password.'], email), 401)
+      return c.html(authPage('login', ['Wrong email or password.'], email, prefix), 401)
     setCookie(c, COOKIE, await auth.startSession(user.id), session(c))
-    return c.redirect('/notes', 303)
+    return c.redirect(at('/notes'), 303)
   })
 
   app.post('/logout', async (c) => {
     const token = getCookie(c, COOKIE)
     if (token) await auth.endSession(token)
     deleteCookie(c, COOKIE, { path: '/' })
-    return c.redirect('/login', 303)
+    return c.redirect(at('/login'), 303)
   })
 
   app.use('/notes/*', requireUser)
@@ -149,10 +154,10 @@ export function createApp(
 
   app.get('/notes', async (c) => {
     const q = (c.req.query('q') ?? '').trim()
-    return c.html(listPage(c.get('user').email, await notes.list(c.get('user').id, q), q))
+    return c.html(listPage(c.get('user').email, await notes.list(c.get('user').id, q), q, prefix))
   })
   app.get('/notes/new', (c) =>
-    c.html(formPage(c.get('user').email, '/notes', { title: '', body: '' })),
+    c.html(formPage(c.get('user').email, '/notes', { title: '', body: '' }, [], prefix)),
   )
   app.post('/notes', async (c) => {
     const form = await c.req.parseBody()
@@ -164,17 +169,18 @@ export function createApp(
           '/notes',
           { title: String(form.title ?? ''), body: String(form.body ?? '') },
           checked.issues.map((i) => i.message),
+          prefix,
         ),
         400,
       )
     await notes.create(c.get('user').id, checked.value.title, checked.value.body)
-    return c.redirect('/notes', 303)
+    return c.redirect(at('/notes'), 303)
   })
   app.get('/notes/:id/edit', async (c) => {
     const note = await notes.get(c.get('user').id, Number(c.req.param('id')))
     return note
-      ? c.html(formPage(c.get('user').email, `/notes/${note.id}`, note))
-      : c.html(listPage(c.get('user').email, [], ''), 404)
+      ? c.html(formPage(c.get('user').email, `/notes/${note.id}`, note, [], prefix))
+      : c.html(listPage(c.get('user').email, [], '', prefix), 404)
   })
   app.post('/notes/:id', async (c) => {
     const id = Number(c.req.param('id'))
@@ -187,17 +193,18 @@ export function createApp(
           `/notes/${id}`,
           { title: String(form.title ?? ''), body: String(form.body ?? '') },
           checked.issues.map((i) => i.message),
+          prefix,
         ),
         400,
       )
     if (!(await notes.update(c.get('user').id, id, checked.value.title, checked.value.body)))
       return c.text('No such note.', 404)
-    return c.redirect('/notes', 303)
+    return c.redirect(at('/notes'), 303)
   })
   app.post('/notes/:id/delete', async (c) => {
     if (!(await notes.remove(c.get('user').id, Number(c.req.param('id')))))
       return c.text('No such note.', 404)
-    return c.redirect('/notes', 303)
+    return c.redirect(at('/notes'), 303)
   })
 
   app.route('/api/notes', createApi(db))

package/templates/notes/src/routes.ts

@@ -3,12 +3,19 @@ import type {} from '../plugins/acryl-db/src/cordis.ts'
 import { createApp } from './notes-app.ts'
 import { createClient } from './runtime.ts'
 
-/** The app's own plugin: it builds the app on the `db` port and mounts it on the router. The mount is removed when the plugin is disposed. */
+/**
+ * The only place the app's mount prefix is named: the root on its own server (`npm start`), `/app` when the ACRYL frame hosts it (`npm run dev`). Every
+ * URL the pages write is derived from the prefix the app is mounted at, so the standalone URLs do not move.
+ */
+export const FRAME_MOUNT_PREFIX = '/app'
+
+/** The app's own plugin: it builds the app on the `db` port and mounts it on the router at `options.prefix` (the root when absent). The mounts are removed when the plugin is disposed. */
 export const routes = {
   name: 'routes',
   inject: ['router', 'db'],
-  apply(ctx: Context) {
-    ctx.router.route('/', createApp(ctx.db))
-    ctx.router.route('/client', createClient())
+  apply(ctx: Context, options: { prefix?: string } = {}) {
+    const prefix = options.prefix ?? ''
+    ctx.router.route(prefix === '' ? '/' : prefix, createApp(ctx.db, { prefix }))
+    ctx.router.route(`${prefix}/client`, createClient(prefix))
   },
 }

package/templates/notes/src/runtime.ts

@@ -11,7 +11,13 @@ const runtimeDir = join(
 
 /**
  * Client components without a bundler: `src/client` is compiled when the browser asks; `npm run build` compiles it once for production
- * (`NODE_ENV=production` then serves only `dist/client`). `src/routes.ts` mounts it at `/client` on the router, next to the app.
+ * (`NODE_ENV=production` then serves only `dist/client`). `src/routes.ts` mounts it at `<prefix>/client` on the router, next to the app; the explicit
+ * mount is the path below which its modules are found, so the same app works at the root and under the frame's prefix.
  */
-export const createClient = () =>
-  clientModules({ root: 'src/client', compiled: 'dist/client', runtimeDir })
+export const createClient = (prefix = '') =>
+  clientModules({
+    root: 'src/client',
+    compiled: 'dist/client',
+    runtimeDir,
+    mount: `${prefix}/client`,
+  })

package/templates/notes/src/views.tsx

@@ -11,13 +11,16 @@ if (filter) filter.addEventListener('input', () => {
 })
 `
 
+/** `base` is the path the app is mounted at: an empty string on its own server, `/app` when the ACRYL frame hosts it. Every URL here starts there. */
 const Layout = ({
   title,
   user,
+  base,
   children,
 }: {
   title: string
   user?: string
+  base: string
   children?: unknown
 }) => (
   <html lang="en">
@@ -37,23 +40,23 @@ const Layout = ({
         <strong>Notes</strong>
         {user ? (
           <>
-            <a href="/notes">All notes</a>
-            <a href="/notes/new">New note</a>
-            <form method="post" action="/logout">
+            <a href={`${base}/notes`}>All notes</a>
+            <a href={`${base}/notes/new`}>New note</a>
+            <form method="post" action={`${base}/logout`}>
               <span>{user} </span>
               <button type="submit">Log out</button>
             </form>
           </>
         ) : (
           <>
-            <a href="/login">Log in</a>
-            <a href="/signup">Sign up</a>
+            <a href={`${base}/login`}>Log in</a>
+            <a href={`${base}/signup`}>Sign up</a>
           </>
         )}
       </nav>
       {children}
       <script dangerouslySetInnerHTML={{ __html: counterScript }} />
-      <script type="module" src="/client/counter.tsx" />
+      <script type="module" src={`${base}/client/counter.tsx`} />
       {doorEnabled() ? <script type="module" src="/api/acryl-door/page.js" /> : null}
     </body>
   </html>
@@ -68,12 +71,17 @@ const Errors = ({ errors }: { errors: string[] }) =>
     </ul>
   ) : null
 
-export const authPage = (mode: 'login' | 'signup', errors: string[] = [], email = ''): string =>
+export const authPage = (
+  mode: 'login' | 'signup',
+  errors: string[] = [],
+  email = '',
+  base = '',
+): string =>
   (
-    <Layout title={mode === 'login' ? 'Log in' : 'Sign up'}>
+    <Layout title={mode === 'login' ? 'Log in' : 'Sign up'} base={base}>
       <h1>{mode === 'login' ? 'Log in' : 'Sign up'}</h1>
       <Errors errors={errors} />
-      <form method="post" action={`/${mode}`}>
+      <form method="post" action={`${base}/${mode}`}>
         <label for="email">Email</label>
         <input id="email" name="email" type="email" value={email} />
         <label for="password">Password</label>
@@ -85,11 +93,11 @@ export const authPage = (mode: 'login' | 'signup', errors: string[] = [], email
     </Layout>
   ).toString()
 
-export const listPage = (user: string, notes: Note[], q: string): string =>
+export const listPage = (user: string, notes: Note[], q: string, base = ''): string =>
   (
-    <Layout title="Notes" user={user}>
+    <Layout title="Notes" user={user} base={base}>
       <h1>Your notes</h1>
-      <form method="get" action="/notes">
+      <form method="get" action={`${base}/notes`}>
         <label for="filter">Search</label>
         <input id="filter" name="q" type="search" value={q} />
         <button type="submit">Search</button>
@@ -98,8 +106,8 @@ export const listPage = (user: string, notes: Note[], q: string): string =>
       <ul>
         {notes.map((n) => (
           <li data-note>
-            <a href={`/notes/${n.id}/edit`}>{n.title}</a>
-            <form method="post" action={`/notes/${n.id}/delete`} style="display:inline">
+            <a href={`${base}/notes/${n.id}/edit`}>{n.title}</a>
+            <form method="post" action={`${base}/notes/${n.id}/delete`} style="display:inline">
               <button type="submit">Delete</button>
             </form>
           </li>
@@ -113,12 +121,13 @@ export const formPage = (
   action: string,
   note: { title: string; body: string },
   errors: string[] = [],
+  base = '',
 ): string =>
   (
-    <Layout title="Note" user={user}>
+    <Layout title="Note" user={user} base={base}>
       <h1>{action === '/notes' ? 'New note' : 'Edit note'}</h1>
       <Errors errors={errors} />
-      <form method="post" action={action}>
+      <form method="post" action={`${base}${action}`}>
         <label for="title">Title</label>
         <input id="title" name="title" value={note.title} />
         <label for="body">Note</label>
@@ -127,7 +136,7 @@ export const formPage = (
         </textarea>
         <small id="count" aria-live="polite" data-island="counter" />
         <p>
-          <button type="submit">Save</button> <a href="/notes">Cancel</a>
+          <button type="submit">Save</button> <a href={`${base}/notes`}>Cancel</a>
         </p>
       </form>
     </Layout>

package/templates/notes/template.json

@@ -7,6 +7,8 @@
     "manifest",
     "save",
     "extensions",
-    "acryl-door"
+    "acryl-door",
+    "acryl-web-server",
+    "acryl-page"
   ]
 }

package/templates/notes/test/notes.test.ts

@@ -23,11 +23,12 @@ const projectRoot = fileURLToPath(new URL('..', import.meta.url))
  */
 const stops: (() => Promise<void>)[] = []
 after(() => Promise.all(stops.map((stop) => stop())))
-async function booted() {
+async function booted(options: { prefix?: string } = {}) {
   const home = await mkdtemp(join(scratch, 'notes-test-'))
   const app = await boot(withPort(pinnedInstance(home, { root: projectRoot }), 0), {
     database: join(home, 'test.sqlite'),
     listen: false,
+    ...options,
   })
   stops.push(async () => {
     await app.stop()
@@ -278,3 +279,40 @@ test('the note form loads the character counter, a client component compiled for
   assert.equal((await running.root.router.request('/client/@acrylblends/jsx-dom.js')).status, 200)
   assert.equal((await running.root.router.request('/client/../src/db.ts')).status, 404)
 })
+
+test('the frame mounts the app at /app: the login page, its links and redirects follow the prefix, and the client module is served there', async () => {
+  const running = await booted({ prefix: '/app' })
+  const root = running.root
+  const home = await root.router.request('/app')
+  assert.equal(home.status, 302)
+  assert.equal(home.headers.get('location'), '/app/notes')
+  const notes = await root.router.request('/app/notes')
+  assert.equal(notes.status, 302)
+  assert.equal(notes.headers.get('location'), '/app/login')
+  const login = await root.router.request('/app/login')
+  assert.equal(login.status, 200)
+  const loginHtml = await login.text()
+  assert.match(loginHtml, /action="\/app\/login"/u)
+  assert.match(loginHtml, /href="\/app\/signup"/u)
+  assert.match(loginHtml, /src="\/app\/client\/counter\.tsx"/u)
+  // Signing up through the framed path lands on the framed notes page, and its links stay under the prefix.
+  const signup = await root.router.request(
+    '/app/signup',
+    form({ email: 'framed@example.com', password: 'correct horse' }),
+  )
+  assert.equal(signup.status, 303)
+  assert.equal(signup.headers.get('location'), '/app/notes')
+  const cookie = (signup.headers.get('set-cookie') ?? '').split(';')[0] ?? ''
+  const list = await root.router.request('/app/notes', { headers: { cookie } })
+  assert.equal(list.status, 200)
+  const listHtml = await list.text()
+  assert.match(listHtml, /href="\/app\/notes\/new"/u)
+  assert.match(listHtml, /action="\/app\/notes"/u)
+  // The client component is compiled and served below the app's prefix.
+  const module = await root.router.request('/app/client/counter.tsx')
+  assert.equal(module.status, 200)
+  assert.match(module.headers.get('content-type') ?? '', /javascript/u)
+  assert.equal((await root.router.request('/app/client/@acrylblends/jsx-dom.js')).status, 200)
+  // The app's own URLs are not mounted in the frame; its own server keeps them (the tests above).
+  assert.equal((await root.router.request('/login')).status, 404)
+})

package/templates/notes/test/server.test.ts

@@ -12,10 +12,24 @@ const scratch = join(fileURLToPath(new URL('..', import.meta.url)), '.acrylblend
 mkdirSync(scratch, { recursive: true })
 
 /** A sandbox may forbid listening on a port (Codex's workspace-write does); the tests that start the real server are skipped there, and every other test runs in process. */
+/**
+ * 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)

package/templates/todo/blend.yaml

@@ -23,3 +23,6 @@ spec:
       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/todo/gitignore

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

package/templates/todo/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"
   },