acrylblends 1.1.0 → 1.3.0

package/templates/chat/src/chat-app.ts

@@ -33,8 +33,16 @@ const ChatSchema: StandardSchema<ChatInput> = {
   },
 }
 
-/** `access` is who may use the chat (default: anyone, as in development and in the tests); see `src/access.ts`. */
-export function createApp(db: Db, llm: Llm = openAiCompatible, access: Access = { kind: 'open' }) {
+/**
+ * `access` is who may use the chat (default: anyone, as in development and in the tests); see `src/access.ts`. `prefix` is the path the app is mounted at:
+ * '' on its own server, `/app` in the ACRYL frame. Every URL the page writes is derived from it.
+ */
+export function createApp(
+  db: Db,
+  llm: Llm = openAiCompatible,
+  access: Access = { kind: 'open' },
+  { prefix = '' }: { prefix?: string } = {},
+) {
   const store = chatStore(db)
   const app = new Acryl()
   const gate = accessGate(access)
@@ -50,6 +58,7 @@ export function createApp(db: Db, llm: Llm = openAiCompatible, access: Access =
         await store.conversations(),
         current,
         current ? await store.messages(current.id) : [],
+        prefix,
       ),
     )
   })

package/templates/chat/src/client/chat.tsx

@@ -47,7 +47,7 @@ const Chat = ({ start }: { start: number | undefined }) => {
     setBusy(true)
     controller.current = new AbortController()
     try {
-      const response = await fetch('/api/chat', {
+      const response = await fetch(`${base}/api/chat`, {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify({ message, conversation: conversation.current }),
@@ -65,7 +65,7 @@ const Chat = ({ start }: { start: number | undefined }) => {
       await readEvents(response.body, (name, data) => {
         if (name === 'meta') {
           conversation.current = (JSON.parse(data) as { conversation: number }).conversation
-          history.replaceState(null, '', `/?c=${conversation.current}`)
+          history.replaceState(null, '', `${base}/?c=${conversation.current}`)
         } else if (name === 'token') {
           soFar += JSON.parse(data) as string
           setAnswer(soFar)
@@ -111,5 +111,7 @@ const Chat = ({ start }: { start: number | undefined }) => {
 }
 
 const root = document.getElementById('chat')!
+/** The path the app is mounted at: '' on its own server, `/app` in the ACRYL frame. The page writes it on the element. */
+const base = root.dataset.base ?? ''
 const start = root.dataset.conversation ? Number(root.dataset.conversation) : undefined
 render(<Chat start={start} />, root)

package/templates/chat/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 page, its streaming API
+ * 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/chat/src/page.tsx

@@ -1,10 +1,12 @@
 import type { Conversation, Message } from './db.ts'
 import { doorEnabled } from './door.ts'
 
+/** `base` is the path the app is mounted at ('' on its own server, `/app` in the ACRYL frame): every URL here, and the client's own, starts there. */
 export const chatPage = (
   conversations: Conversation[],
   current: Conversation | undefined,
   messages: Message[],
+  base = '',
 ): string =>
   (
     <html lang="en">
@@ -22,9 +24,9 @@ export const chatPage = (
       <body>
         <h1>Chat</h1>
         <nav>
-          <a href="/">New chat</a>
+          <a href={`${base}/`}>New chat</a>
           {conversations.map((c) => (
-            <a href={`/?c=${c.id}`}>{c.title}</a>
+            <a href={`${base}/?c=${c.id}`}>{c.title}</a>
           ))}
         </nav>
         <div id="log">
@@ -32,8 +34,8 @@ export const chatPage = (
             <p class={`row ${m.role}`}>{m.content}</p>
           ))}
         </div>
-        <div id="chat" data-conversation={current ? String(current.id) : ''} />
-        <script type="module" src="/client/chat.tsx" />
+        <div id="chat" data-conversation={current ? String(current.id) : ''} data-base={base} />
+        <script type="module" src={`${base}/client/chat.tsx`} />
         {doorEnabled() ? <script type="module" src="/api/acryl-door/page.js" /> : null}
       </body>
     </html>

package/templates/chat/src/routes.ts

@@ -5,15 +5,25 @@ import { createApp } from './chat-app.ts'
 import { openAiCompatible } from './llm.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 page writes 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) {
+  apply(ctx: Context, options: { prefix?: string } = {}) {
+    const prefix = options.prefix ?? ''
     // In production the chat is closed unless it has a token or is made public on purpose: anyone who reaches it spends the model key.
     const { access, notices } = chatAccess(process.env)
     for (const line of notices) console.warn(line)
-    ctx.router.route('/', createApp(ctx.db, openAiCompatible, access))
-    ctx.router.route('/client', createClient())
+    ctx.router.route(
+      prefix === '' ? '/' : prefix,
+      createApp(ctx.db, openAiCompatible, access, { prefix }),
+    )
+    ctx.router.route(`${prefix}/client`, createClient(prefix))
   },
 }

package/templates/chat/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/chat/template.json

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

package/templates/chat/test/chat.test.ts

@@ -4,13 +4,16 @@ import { mkdtemp, rm } from 'node:fs/promises'
 import { join } from 'node:path'
 import { after, test } from 'node:test'
 import { fileURLToPath } from 'node:url'
+import { Context } from '@deepseek-ai/cordis'
 import type {} from '../plugins/acryl-db/src/cordis.ts'
 import type { Db } from '../plugins/acryl-db/src/index.ts'
+import * as router from '../plugins/acryl-router/src/index.ts'
 import { pinnedInstance, withPort } from '../plugins/instance/index.ts'
 import { chatAccess } from '../src/access.ts'
 import { createApp as boot } from '../src/app.ts'
 import { createApp } from '../src/chat-app.ts'
 import type { Llm } from '../src/llm.ts'
+import { FRAME_MOUNT_PREFIX } from '../src/routes.ts'
 
 /** Throwaway homes and databases live inside the project (`.acrylblends/` is ignored by git), because a sandboxed agent may not write to the system temp folder. */
 const scratch = join(fileURLToPath(new URL('..', import.meta.url)), '.acrylblends', 'test')
@@ -24,11 +27,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, 'chat-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()
@@ -261,3 +265,44 @@ test('ACRYL_PRODUCTION_KEEP=chat makes the chat public with a loud WARNING and a
   // Other routes are not counted.
   assert.equal((await app.request('/api/conversations')).status, 200)
 })
+
+test('the frame mounts the chat at /app: the page, the streaming API and the client follow the prefix', async () => {
+  const running = await booted({ prefix: FRAME_MOUNT_PREFIX })
+  const page = await running.root.router.request(FRAME_MOUNT_PREFIX)
+  assert.equal(page.status, 200)
+  const html = await page.text()
+  assert.match(html, /<h1>Chat<\/h1>/u)
+  assert.match(html, /data-base="\/app"/u)
+  assert.match(html, /src="\/app\/client\/chat\.tsx"/u)
+  assert.equal((await running.root.router.request(`${FRAME_MOUNT_PREFIX}/health`)).status, 200)
+  // The streaming API answers at the prefix, with a local model.
+  const { llm } = mock(['Hel', 'lo'])
+  const root = new Context()
+  try {
+    await root.plugin(router)
+    root.router.route(
+      FRAME_MOUNT_PREFIX,
+      createApp(running.root.db, llm, undefined, { prefix: FRAME_MOUNT_PREFIX }),
+    )
+    const res = await root.router.request(`${FRAME_MOUNT_PREFIX}/api/chat`, post({ message: 'hi' }))
+    assert.equal(res.status, 200)
+    const got = events(await res.text())
+    assert.deepEqual(
+      got.map(([e]) => e),
+      ['meta', 'token', 'token', 'done'],
+    )
+    // 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('/health')).status, 404)
+  } finally {
+    await root.fiber.dispose()
+  }
+  // The client component is compiled and served below the app's prefix.
+  const module = await running.root.router.request(`${FRAME_MOUNT_PREFIX}/client/chat.tsx`)
+  assert.equal(module.status, 200)
+  assert.match(module.headers.get('content-type') ?? '', /javascript/u)
+  assert.equal(
+    (await running.root.router.request(`${FRAME_MOUNT_PREFIX}/client/@acrylblends/jsx-dom.js`))
+      .status,
+    200,
+  )
+})

package/templates/chat/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/nodejs/.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/nodejs/blend.yaml

@@ -17,7 +17,8 @@ spec:
       name: acryl-router
     - 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/nodejs/gitignore

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

package/templates/nodejs/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/nodejs/src/app.ts

@@ -7,15 +7,17 @@ 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. */
+/** 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,
@@ -28,6 +30,8 @@ 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 app's manifest, resolved. A Blend finds its Blueprint in `blueprints/<id>.yaml`; an app that is itself a Blueprint never looks.
@@ -35,7 +39,7 @@ export const MANIFEST = join(projectRoot, 'blend.yaml')
  */
 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 } : {}),
   })
@@ -61,33 +65,84 @@ 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>>; listen?: boolean } = {},
-): Promise<App> {
+  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)),
+  )
+  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, manifest, registry, {
-      // 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 },
-    })),
-  ]
+  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/nodejs/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/nodejs/src/page.tsx

@@ -15,14 +15,14 @@ export const failingPage = (): string => {
   throw new Error('a page failed')
 }
 
-/** A page with one client component: `src/client/counter.tsx` runs in the browser, compiled on request by `clientModules` (see src/routes.ts). */
-export const counterPage = (): string =>
+/** A page with one client component: `src/client/counter.tsx` runs in the browser, compiled on request by `clientModules` (see src/routes.ts). `prefix` is the path the app is mounted at, so the script URL follows it. */
+export const counterPage = (prefix = ''): string =>
   (
     <html lang="en">
       <body>
         <h1>Counter</h1>
         <div id="counter" />
-        <script type="module" src="/client/counter.tsx" />
+        <script type="module" src={`${prefix}/client/counter.tsx`} />
         {doorEnabled() ? <script type="module" src="/api/acryl-door/page.js" /> : null}
       </body>
     </html>

package/templates/nodejs/src/routes.ts

@@ -14,27 +14,46 @@ const runtimeDir = join(
 
 export const APP_NAME = '__APP_NAME__'
 
-/** The routes, in a file that does not import the Node adapter's server, so browser code can import the type: `import type { AppType } from '../routes.ts'`. */
-export const pages = new Acryl()
-  .get('/', (c) => c.json({ app: APP_NAME, ok: true }))
-  .get('/health', (c) => c.json({ ok: true }))
-  .get('/about', (c) => c.html(aboutPage()))
-  .get('/counter', (c) => c.html(counterPage()))
+/**
+ * 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 pages, mountable at any prefix: the standalone server mounts it at the root, the frame row at {@link FRAME_MOUNT_PREFIX}.
+ * A page that carries a client component writes its URL from the prefix it is mounted at.
+ */
+export function makeApp(prefix = ''): Acryl {
+  return new Acryl()
+    .get('/', (c) => c.json({ app: APP_NAME, ok: true }))
+    .get('/health', (c) => c.json({ ok: true }))
+    .get('/about', (c) => c.html(aboutPage()))
+    .get('/counter', (c) => c.html(counterPage(prefix)))
+}
 
-export type AppType = typeof pages
+/** The routes, in a file that does not import the Node adapter's server, so browser code can import the type: `import type { AppType } from '../routes.ts'`. */
+export type AppType = ReturnType<typeof makeApp>
 
 /**
- * The app's own plugin: the routes above, and the client components without a bundler (`src/client` is compiled when the browser asks; `npm run build`
- * compiles it once for production, and `NODE_ENV=production` then serves only `dist/client`). The mounts are removed when the plugin is disposed.
+ * The app's own plugin: the pages above at `options.prefix` (the root when absent), and the client components without a bundler (`src/client` is compiled
+ * when the browser asks; `npm run build` compiles it once for production, and `NODE_ENV=production` then serves only `dist/client`). The mounts are
+ * removed when the plugin is disposed.
  */
 export const routes = {
   name: 'routes',
   inject: ['router'],
-  apply(ctx: Context) {
-    ctx.router.route('/', pages)
+  apply(ctx: Context, options: { prefix?: string } = {}) {
+    const prefix = options.prefix ?? ''
+    ctx.router.route(prefix === '' ? '/' : prefix, makeApp(prefix))
     ctx.router.route(
-      '/client',
-      clientModules({ root: 'src/client', compiled: 'dist/client', runtimeDir }),
+      `${prefix}/client`,
+      clientModules({
+        root: 'src/client',
+        compiled: 'dist/client',
+        runtimeDir,
+        mount: `${prefix}/client`,
+      }),
     )
   },
 }

package/templates/nodejs/template.json

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

package/templates/nodejs/test/app.test.ts

@@ -6,7 +6,7 @@ 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 { APP_NAME, FRAME_MOUNT_PREFIX } from '../src/routes.ts'
 
 /** Throwaway homes and databases live inside the project (`.acrylblends/` is ignored by git), because a sandboxed agent may not write to the system temp folder. */
 const scratch = join(fileURLToPath(new URL('..', import.meta.url)), '.acrylblends', 'test')
@@ -14,11 +14,12 @@ 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>) {
+/** Boot the app in a throwaway home on any free port, run the test, always stop it and remove the home. `prefix` mounts it where the frame does. */
+async function withApp(run: (app: App) => Promise<void>, options: { prefix?: string } = {}) {
   const home = await mkdtemp(join(scratch, 'app-test-'))
   const app = await createApp(withPort(pinnedInstance(home, { root: projectRoot }), 0), {
     listen: false,
+    ...options,
   })
   try {
     await run(app)
@@ -76,3 +77,37 @@ test('GET /counter serves a page with a client component, and the component is c
     const runtime = await app.root.router.request('/client/@acrylblends/jsx-dom.js')
     assert.equal(runtime.status, 200)
   }))
+
+test('the frame mounts the app at /app: its pages, health route and client component follow the prefix', () =>
+  withApp(
+    async (app) => {
+      const root = await app.root.router.request(FRAME_MOUNT_PREFIX)
+      assert.equal(root.status, 200)
+      assert.deepEqual(await root.json(), { app: APP_NAME, ok: true })
+      const about = await app.root.router.request(`${FRAME_MOUNT_PREFIX}/about`)
+      assert.equal(about.status, 200)
+      assert.match(await about.text(), /<main><h1>About<\/h1>/u)
+      const health = await app.root.router.request(`${FRAME_MOUNT_PREFIX}/health`)
+      assert.equal(health.status, 200)
+      assert.deepEqual(await health.json(), { ok: true })
+      const page = await app.root.router.request(`${FRAME_MOUNT_PREFIX}/counter`)
+      assert.equal(page.status, 200)
+      assert.match(
+        await page.text(),
+        new RegExp(`<script type="module" src="${FRAME_MOUNT_PREFIX}/client/counter\\.tsx">`, 'u'),
+      )
+      const module = await app.root.router.request(`${FRAME_MOUNT_PREFIX}/client/counter.tsx`)
+      assert.equal(module.status, 200)
+      assert.match(module.headers.get('content-type') ?? '', /javascript/u)
+      assert.doesNotMatch(await module.text(), /<Counter|<button/u)
+      // The component's import of the DOM renderer is served below the app's prefix too.
+      assert.equal(
+        (await app.root.router.request(`${FRAME_MOUNT_PREFIX}/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 app.root.router.request('/about')).status, 404)
+    },
+    { prefix: FRAME_MOUNT_PREFIX },
+  ))

package/templates/nodejs/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)