acrylblends 1.0.10 → 1.2.0

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)

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/main.ts

@@ -5,12 +5,7 @@ import { createApp } from './app.ts'
 // The composition root: the one place that reads the environment and chooses where the app lives.
 const chosen = selectInstance({
   projectRoot: fileURLToPath(new URL('..', import.meta.url)),
-  // PORT and HOST are the names hosting platforms set; ACRYLBLENDS_PORT and ACRYLBLENDS_HOST win when both are given.
-  env: {
-    ...(process.env.PORT ? { ACRYLBLENDS_PORT: process.env.PORT } : {}),
-    ...(process.env.HOST ? { ACRYLBLENDS_HOST: process.env.HOST } : {}),
-    ...process.env,
-  },
+  env: process.env,
 })
 const app = await createApp(chosen, {
   ...(process.env.NOTES_DB ? { database: process.env.NOTES_DB } : {}),

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`,
+  })