acrylblends 1.0.10 → 1.2.0

package/shared/skills/cordis-plugin/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: cordis-plugin
+description: Add a Cordis plugin to __APP_NAME__ - a plugins/<name>/ folder with name, inject, apply and an optional check, its routes as an Acryl app, how its blend.yaml row mounts it, and how to verify it. Use when a feature should be its own plugin, or when asked to extend the app.
+---
+
+# Adding a Cordis plugin
+
+A plugin is a folder `plugins/<name>/` with an `index.ts` exporting `name` (its id), `inject` (the services it needs) and `apply(ctx)`. Everything it acquires belongs to one `ctx.effect(...)`, so unloading the plugin or stopping the app releases it.
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import { Acryl } from 'acrylblends'
+
+export const name = 'due-dates'
+export const inject = ['router']
+
+export function apply(ctx: Context): void {
+  const app = new Acryl().get('/due-dates', (c) => c.json({ ok: true }))
+  ctx.router.route('/due-dates', app)
+}
+```
+
+- **Routes** are an `Acryl` app mounted with `ctx.router.route('/due-dates', app)`; removing the plugin removes them. Write the app's own path: the frame that hosts the app in development adds its canvas prefix, so the same route answers `/due-dates` under `npm start` and `/app/due-dates` in the canvas. Never put the frame's prefix in a plugin's route. Import the framework by name (`acrylblends`, `acrylblends/body-limit`); never guess a relative path into another plugin.
+- **State** lives in cells: `ctx.state.cell('due-dates.tasks', [])`. A page follows one with `watch` from `/api/state/client.js`, never with an `EventSource`, and never by polling what `watch` already pushes.
+- **Its row starts it.** Add a row to `blend.yaml` (`- id: <name>` and `name: <name>`, before the `acryl-node-server` row); `src/app.ts` finds the folder by that name, so it is never imported there. `disabled: true` on the row switches it off (Settings > Plugins does the same). `.acryl/bin/acryl plugin add plugins/<name>` installs a folder without a row live, for trying it; a folder with a row is the app's.
+- **Check it.** `npm test` and `npm run check` must pass. With the app running, use the door: `.acryl/bin/acryl look` reads the page as text with refs and `acryl act ...` acts on it; an install or reload shows the new feature in the page.

package/templates/agent/AGENTS.md

@@ -5,10 +5,12 @@ Besides `src/routes.ts`, the app runs an agent (`POST /ask`) that can write plug
 rollback; `GET /extensions` and `GET /tasks` show what it did. A plugin there is a folder with an `index.ts` exporting `name`, `inject`, `apply(ctx)`
 and an optional `check(ctx)` that receives the plugin's own context (so `ctx.router` reads as in `apply`). It may import `acryl-router`.
 
-**Write an extension, not a row.** A feature you build while the app runs is a folder `plugins/<name>/` installed with `.acryl/bin/acryl plugin add plugins/<name>` (the `extensions` plugin loads it again at every start). Add a row to `blend.yaml` and an entry to the `registry` of `src/app.ts` only when the person asks for a plugin that is part of the app itself. Both kinds may import the framework by name (`acrylblends`, `acrylblends/body-limit`, `acryl-router`); a row's relative imports of its sibling plugins also work.
+**Write an extension, not a row.** A feature you build while the app runs is a folder `plugins/<name>/` installed with `.acryl/bin/acryl plugin add plugins/<name>` (the `extensions` plugin loads it again at every start). Add a row to `blend.yaml` (`- id: <name>` / `name: <name>`; `src/app.ts` finds the folder by that name) only when the person asks for a plugin that is part of the app itself. Both kinds may import the framework by name (`acrylblends`, `acrylblends/body-limit`, `acryl-router`); a row's relative imports of its sibling plugins also work.
 
 **Drive the app you build.** `.acryl/bin/acryl look` reads the open page as text with refs, and `acryl act click|type|press|scroll|wait --ref <ref>` presses its buttons, opens its sidebars and fills its forms (look again before each act: the refs change). `act navigate --path /settings` goes to another page of the app; a path the app does not serve answers `404 at /nope` and the window shows a 404 page, so navigate on from there. In the desktop app (`npm run desktop`) the app's windows and menu are verbs too: `acryl window list`, `acryl window open --path /settings`, `acryl look --window <id>` (and `act ... --window <id>`) to drive that window's page, `acryl window resize|focus|close --id <id>`, `acryl menu list` and `acryl menu click --path "File>New Note"`. Closing the last window and Quit end the desktop app, so they need `--force`: do not use it unless the person asks. The app has a `/settings` page already (the appearance: system, light or dark, kept in the browser) and the desktop app's menu has a Settings item that opens it; add a person's other settings to that page, not to a new one, so `acryl menu click --path "File>Settings..."` and `acryl window open --path /settings` keep opening them (on macOS the item is in the application menu). Without a desktop app these answer "no desktop window is attached; run npm run desktop".
 
-**Keep to two event streams a page.** A browser lets a page hold six connections to one host, across all the windows of the app, and an `EventSource` holds one for as long as the page is open. The door and the panel use none (they are WebSockets), but a page you build that streams several things in two windows can fill all six, and then every request waits. Give a page at most two streams: share one stream for several cells, or fetch what changes now and then instead.
+**Pages you build follow the app's appearance.** The person chooses System, Light or Dark in `/settings`, and every open window follows it at once. A page you build gets that by putting `<script src="/appearance.js"></script>` in its `<head>` (before any other script) and colouring itself with the custom properties the script defines: `var(--bg)` for the page, `var(--fg)` for text, `var(--surface)` for cards and sidebars, `var(--border)`, `var(--muted)` for secondary text and `var(--accent)`. Do not write fixed colours (`#fff`, `white`, `#111`), `color-scheme`, or a `@media (prefers-color-scheme)` of your own: they ignore the person's choice (a page that does so stays light in a window set to Dark, or the other way round). `look` reports structure and text, not colours: check a page's colours by its CSS (every colour is a `var(--...)`), and tell the person what you did.
+
+**Follow state with `watch`, not an `EventSource`.** A browser lets a page hold six connections to one host, across all the windows of the app, and an `EventSource` holds one for as long as the page is open: a page that streams a few things in two windows fills all six, and then every request waits. A cell of `ctx.state` (`ctx.state.cell('board.cards', [])`) is followed in the page with `import { watch } from '/api/state/client.js'` and `const stop = watch('board.cards', (cards) => { render(cards) })`: one WebSocket for the whole page carries every key (a WebSocket is not one of the six), the callback gets the value now and after every change, and `stop()` ends it. Without a WebSocket it falls back to one event stream per key and prints one warning in the console; then keep to two keys a page. Do not open an `EventSource` on `/api/state/<key>/events` yourself, and do not poll in a loop what `watch` already pushes.
 
 **Production.** The agent, the builder and the extensions are development tools: `POST /ask` spends the model key and runs tools, a plugin installed live runs in this process, and none of it is behind a login. With `NODE_ENV=production` `src/app.ts` leaves the agent and the builder out, so `/ask`, `/extensions*` and `/tasks*` are not mounted; the page and `GET /health` stay. The extensions you installed (the folders of `plugins/`, committed with the app) still run in production, read-only: nothing can be installed or changed there. `ACRYL_PRODUCTION_KEEP=agent,builder,extensions` keeps the named rows, and each one kept prints a `WARNING` line at start.

package/templates/agent/blend.yaml

@@ -24,10 +24,13 @@ spec:
       name: tasks
       config:
         store: "{{parameters.taskStore}}"
+    # The model the agent asks at each step: a scripted offline one until a provider key is set.
     - id: model
       name: model
+    # The tools the agent can call, each with what it does and the input it takes.
     - id: tools
       name: tools
+    # Long-term memory for the agent.
     - id: memory
       name: memory
     - id: agent
@@ -51,6 +54,7 @@ spec:
     # The panel: a chat button on every page in development (the app's own agent, or Codex, Claude or pi started in this folder). It starts nothing in production.
     - id: agent-panel
       name: agent-panel
+    # The app's own pages and API.
     - id: routes
       name: routes
     - id: server

package/templates/agent/gitignore

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

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

@@ -6,22 +6,24 @@ 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 * as state from '../plugins/acryl-state/src/index.ts'
-import { agent, memory, model, tools } from '../plugins/agent/index.ts'
+import { agent, memory, model, scripted, tools } from '../plugins/agent/index.ts'
 import * as panel from '../plugins/agent-panel/index.ts'
 import { builder } from '../plugins/builder/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 { type OpenAIConfig, openai } from '../plugins/openai/index.ts'
+import { ASSISTANT_PROMPT, type OpenAIConfig, openai } from '../plugins/openai/index.ts'
 import { sandboxPlugin } from '../plugins/sandbox/index.ts'
 import { save } from '../plugins/save/index.ts'
 import { tasks } from '../plugins/tasks/index.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 = {
@@ -44,6 +46,8 @@ export const registry = {
 
 /** The manifest next to this app's source. */
 export const MANIFEST = join(fileURLToPath(new URL('..', import.meta.url)), 'blend.yaml')
+/** The app's own plugins (a feature each), which `blend.yaml` mounts by their folder name next to the library copies `registry` imports. */
+const PLUGINS_DIR = join(fileURLToPath(new URL('..', import.meta.url)), 'plugins')
 
 /**
  * The app's manifest, resolved. A Blend finds its Blueprint in `blueprints/<id>.yaml`; an app that is itself a Blueprint never looks.
@@ -51,7 +55,7 @@ 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),
+    known: [...Object.keys(registry), ...appPluginNames(PLUGINS_DIR)],
     getBlueprint: blueprintsIn(join(fileURLToPath(new URL('..', import.meta.url)), 'blueprints')),
     ...(values ? { values } : {}),
   })
@@ -77,28 +81,61 @@ const DEVELOPMENT_ROWS: Record<string, string> = {
     'a plugin installed live runs in this process, and POST /extensions/approve decides installs',
 }
 
+/** The only tools the production Assistant's agent may call: look at the page and act on it. */
+const ASSISTANT_TOOLS = ['door_look', 'door_act']
+
+/** The most tokens one answer of the Assistant's model may use: with the step budget, what one visitor's question can cost at most. */
+const ASSISTANT_MAX_TOKENS = 1024
+
+/** Model calls per visitor question: look, open a page, look, filter, look and answer is six, with room for one wrong turn. */
+const ASSISTANT_STEPS = 10
+
+/** What the Assistant says while the app has no model: the scripted one cannot use the page. */
+export const ASSISTANT_NO_MODEL =
+  "This assistant is not set up yet: the app's owner has not chosen a model for it."
+
 /**
- * The app: `instance` first (where it lives, chosen at run time), then the manifest's rows in order. The app's `plugins/`
- * folder is trusted to install at start, and is where the builder writes.
+ * The app's rows in the manifest's order, 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 server and the
+ * door to the frame host, which mounts its own.
  */
-export async function createApp(
+export async function composeInto(
+  ctx: Context,
   chosen: AppInstance,
   options: {
     values?: Readonly<Record<string, ParameterValue>>
-    /** A real model (any OpenAI-compatible API) in place of the offline scripted one. */
     model?: OpenAIConfig
-    /** 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
+    host?: boolean
   } = {},
-): Promise<App> {
+): Promise<Fiber[]> {
   const read = readManifest(options.values)
   // Rows left out: the server (and so the door, which needs it) when the app is reached in process; the door in production and with ACRYL_DOOR=off (one process at a time
   // serves a folder's door, so the tests that start several apps set it).
-  const listen = options.listen !== false
+  const listen = options.listen !== false && options.host !== true
   const leaveOut = new Set<string>()
   let extensionsReadOnly = false
-  if (!listen) leaveOut.add('acryl-node-server').add('acryl-door')
-  if (process.env.NODE_ENV === 'production' || process.env.ACRYL_DOOR === 'off')
+  // In the frame host the infrastructure rows are the host's own (its server, its web-server port, its router, the app instance, the door): the app
+  // contributes only the plugins that are its own.
+  if (!listen || options.host === true) leaveOut.add('acryl-node-server').add('acryl-door')
+  if (options.host === true)
+    for (const row of [
+      'instance',
+      'acryl-router',
+      'acryl-web-server',
+      'acryl-page',
+      'manifest',
+      'save',
+    ])
+      leaveOut.add(row)
+  // The Assistant (production, ACRYL_ASSISTANT=on): the agent panel docked for the app's visitors. Its agent keeps only the page tools and the door only the page,
+  // so it uses the app for a visitor (opens pages, filters, fills in forms) and cannot change the app, its code or its secrets. Not in the frame host.
+  const assistant =
+    process.env.NODE_ENV === 'production' &&
+    process.env.ACRYL_ASSISTANT === 'on' &&
+    process.env.ACRYL_DOOR !== 'off' &&
+    listen
+  if (!assistant && (process.env.NODE_ENV === 'production' || process.env.ACRYL_DOOR === 'off'))
     leaveOut.add('acryl-door')
   // Production: the rows that give a visitor power over the running app or the owner's model key are left out too. The agent (`POST /ask` spends the model key and runs tools),
   // the builder and the extensions (live plugin install runs code in this process, and `POST /extensions/approve` decides it) are development tools. `ACRYL_PRODUCTION_KEEP`
@@ -121,7 +158,7 @@ export async function createApp(
           `WARNING: the "${row}" row runs in production because ACRYL_PRODUCTION_KEEP names it: ${danger}. Nothing here is behind a login; put the app behind your own.`,
         )
       else if (row === 'extensions') extensionsReadOnly = true
-      else leaveOut.add(row)
+      else if (!(assistant && row === 'agent')) leaveOut.add(row)
     }
   }
   const manifest = {
@@ -136,31 +173,111 @@ export async function createApp(
     console.warn(
       'warning: extensions/ is the old folder for plugins the agent writes; move them to plugins/ ("git mv extensions/<name> plugins/<name>"). extensions/ is read for this release only.',
     )
-  const root = new Context()
-  const first = root.plugin(instance, chosen)
-  await first.await()
+  // The Assistant's model is told it helps a visitor through the page alone, and each answer is capped, unless the app's model configuration says otherwise.
+  const modelConfig =
+    options.model && assistant
+      ? {
+          ...options.model,
+          system: options.model.system ?? ASSISTANT_PROMPT,
+          maxTokens: options.model.maxTokens ?? ASSISTANT_MAX_TOKENS,
+        }
+      : options.model
+  if (assistant && !options.model)
+    console.warn(
+      `WARNING: the Assistant has no model, so it answers every visitor "${ASSISTANT_NO_MODEL}" Set the app's model (ACRYLBLENDS_MODEL_URL and ACRYLBLENDS_MODEL, or model.json in the app's home).`,
+    )
+  // 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 fibers: Fiber[] = [
-    first,
     // The `model` row mounts the scripted model, or the real one when a model is configured.
-    ...(await compose(root, manifest, options.model ? { ...registry, model: openai } : registry, {
-      ...(options.model ? { model: { ...options.model } } : {}),
-      // Runtime values the manifest cannot hold: the manifest's own digest (every task records it), and who may install.
-      tasks: { manifest: `sha256:${manifest.digest}` },
-      // The `approval` parameter in blend.yaml (the extensions row) turns this source into one that asks.
-      extensions: {
-        ...(extensionsReadOnly ? { readOnly: true } : {}),
-        sources: [
-          { dir: extensionsDir, trust: 'install' },
-          ...(legacy ? [{ dir: legacyDir, trust: 'install' as const }] : []),
-        ],
+    ...(await compose(
+      ctx,
+      manifest,
+      { ...registry, ...ownPlugins, ...(modelConfig ? { model: openai } : {}) },
+      {
+        ...(modelConfig ? { model: { ...modelConfig } } : {}),
+        // Runtime values the manifest cannot hold: the manifest's own digest (every task records it), and who may install.
+        tasks: { manifest: `sha256:${manifest.digest}` },
+        // The `approval` parameter in blend.yaml (the extensions row) turns this source into one that asks.
+        extensions: {
+          ...(extensionsReadOnly ? { readOnly: true } : {}),
+          sources: [
+            { dir: extensionsDir, trust: 'install' },
+            ...(legacy ? [{ dir: legacyDir, trust: 'install' as const }] : []),
+          ],
+          rows: ownRows,
+        },
+        builder: { dir: extensionsDir },
+        ...(assistant
+          ? {
+              // Every answer comes right after a look, so it says what the visitor's page shows now.
+              agent: { tools: ASSISTANT_TOOLS, steps: ASSISTANT_STEPS, answerAfter: 'door_look' },
+              'acryl-door': { pageOnly: true },
+              'agent-panel': { assistant: true },
+              // The visitor reaches the agent through the panel only: no /ask, /tasks or /extensions routes.
+              routes: { agentRoutes: false },
+            }
+          : {}),
+        // The rows that serve routes of their own mount them under the app's prefix, as makeApp does. On the app's own server that prefix is the root (the
+        // row's default); the frame host serves the app at FRAME_MOUNT_PREFIX, and its own `/api` routes would answer for a row left at the root. The
+        // app's own routes row takes the same prefix for its mount and for the absolute URLs its pages write, so the page and its assets answer at `/app`.
+        ...(options.host === true
+          ? {
+              'agent-panel': { mount: FRAME_MOUNT_PREFIX },
+              'driver-pty': { mount: FRAME_MOUNT_PREFIX },
+              feedback: { mount: FRAME_MOUNT_PREFIX },
+              routes: { prefix: FRAME_MOUNT_PREFIX, ...(assistant ? { agentRoutes: false } : {}) },
+            }
+          : {}),
+        // The frame host runs the server itself and its app instance carries no port; only the app's own server configures one.
+        ...(options.host === true
+          ? {}
+          : {
+              server: {
+                port: chosen.port.start,
+                scan: chosen.port.scan ? 20 : 0,
+                hostname: chosen.host,
+              },
+            }),
       },
-      builder: { dir: extensionsDir },
-      server: { port: chosen.port.start, scan: chosen.port.scan ? 20 : 0, hostname: chosen.host },
-    })),
+    )),
   ]
+  // Without a model the scripted one would echo the visitor's words back: it says in one sentence that the Assistant is not set up.
+  if (assistant && !options.model)
+    scripted(ctx.get('model') as Parameters<typeof scripted>[0])?.teach(() => ({
+      text: ASSISTANT_NO_MODEL,
+    }))
+  return fibers
+}
+
+/**
+ * The app: `instance` first (where it lives, chosen at run time), then the manifest's rows in order. The app's `plugins/`
+ * folder is trusted to install at start, and is where the builder writes.
+ */
+export async function createApp(
+  chosen: AppInstance,
+  options: {
+    values?: Readonly<Record<string, ParameterValue>>
+    /** A real model (any OpenAI-compatible API) in place of the offline scripted one. */
+    model?: OpenAIConfig
+    /** 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 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 ? root.nodeServer.url : '',
+    url: options.listen === false ? '' : root.nodeServer.url,
     async stop() {
       for (const fiber of [...fibers].reverse()) await fiber.dispose()
     },

package/templates/agent/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 routes
+ * 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 routes are at the root as they always were.
+ */
+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 web adapter. */
+export const inject = ['routerHttp']
+
+export function apply(ctx: Context): void {
+  ctx.routerHttp.mount(FRAME_MOUNT_PREFIX)
+}

package/templates/agent/src/main.ts

@@ -1,16 +1,18 @@
+import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { selectInstance } from '../plugins/instance/index.ts'
-import { modelConfigFrom } from '../plugins/openai/index.ts'
+import { MODEL_FILE, modelConfigFrom, modelConfigFromFile } from '../plugins/openai/index.ts'
 import { createApp } from './app.ts'
 import { APP_NAME } from './routes.ts'
 
 // The composition root: the one place that reads the environment. selectInstance chooses where the app lives;
-// modelConfigFrom picks a real model when ACRYLBLENDS_MODEL_URL and ACRYLBLENDS_MODEL are set (ACRYLBLENDS_MODEL_KEY for hosted APIs).
+// modelConfigFrom picks a real model when ACRYLBLENDS_MODEL_URL and ACRYLBLENDS_MODEL are set (ACRYLBLENDS_MODEL_KEY for hosted APIs); without them, the model kept in the app's
+// home (model.json, readable by its owner only) is used, so a started app needs no flag.
 const chosen = selectInstance({
   projectRoot: fileURLToPath(new URL('..', import.meta.url)),
   env: process.env,
 })
-const model = modelConfigFrom(process.env)
+const model = modelConfigFrom(process.env) ?? modelConfigFromFile(join(chosen.home, MODEL_FILE))
 const app = await createApp(chosen, model ? { model } : {})
 console.log(
   `${APP_NAME} listening on ${app.url} (data in ${chosen.home}; model: ${model ? `${model.model} at ${model.baseUrl}` : 'offline scripted'})`,

package/templates/agent/src/routes.ts

@@ -7,6 +7,9 @@ import type {} from '../plugins/tasks/index.ts'
 
 export const APP_NAME = '__APP_NAME__'
 
+/** 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`). */
+export const FRAME_MOUNT_PREFIX = '/app'
+
 /** The door's page script (`.acryl/bin/acryl look` and `act`), in development only: `src/app.ts` leaves the door out in production and with ACRYL_DOOR=off. */
 const DOOR_TAG =
   process.env.NODE_ENV !== 'production' && process.env.ACRYL_DOOR !== 'off'
@@ -16,22 +19,80 @@ const DOOR_TAG =
 /**
  * The app's own routes on the router. Always: the page and `GET /health`. While the agent, the extensions and the task recorder run: `POST /ask` for the agent; `GET /extensions`
  * (and `POST /extensions/approve` and `/deny`) and `GET /tasks` to observe and steer what it did (every run is a durable task owning one task per tool call); `POST /tasks/cancel`.
- * What changes is also streamed: `GET /api/state/tasks/events` and `GET /api/state/extensions/events`. In production `src/app.ts` leaves the agent and builder rows out
+ * What changes is also streamed: `GET /api/state/tasks/events` and `GET /api/state/extensions/events` (a page follows them with `watch` of `/api/state/client.js`, over one WebSocket). In production `src/app.ts` leaves the agent and builder rows out
  * and starts the extensions read-only (unless `ACRYL_PRODUCTION_KEEP` names them), and then those routes are not mounted at all. The mounts are removed when the plugin is disposed.
  */
-/** The page's look: the person's choice from /settings (kept in this browser), applied before the page paints. */
+/**
+ * The app's look: the person's choice from /settings (kept in this browser), as `GET /appearance.js`. One script tag in a page's head (`<script src="/appearance.js"></script>`) applies it
+ * before the page paints, again whenever another window of the app changes it (the `storage` event), and defines the colours as custom properties for the page to use:
+ * `--bg`, `--fg`, `--muted`, `--surface`, `--border`, `--accent` (`html[data-theme=dark|light]` is set when the person chose one, and the system's choice decides otherwise). A page the agent builds
+ * carries the tag and colours itself with `var(--bg)` and the rest, and so follows Dark and Light.
+ */
+const APPEARANCE_JS = `(function () {
+  var root = document.documentElement
+  function apply() {
+    var saved
+    try { saved = localStorage.getItem('theme') } catch (e) { /* storage blocked: follow the system */ }
+    if (saved === 'dark' || saved === 'light') root.dataset.theme = saved
+    else delete root.dataset.theme
+  }
+  apply()
+  addEventListener('storage', function (event) { if (event.key === null || event.key === 'theme') apply() })
+  var light = '--bg:#ffffff;--fg:#111827;--muted:#6b7280;--surface:#f3f4f6;--border:#d1d5db;--accent:#2563eb'
+  var dark = '--bg:#111827;--fg:#f9fafb;--muted:#9ca3af;--surface:#1f2937;--border:#374151;--accent:#60a5fa'
+  var style = document.createElement('style')
+  style.id = 'appearance'
+  style.textContent = ':root{color-scheme:light dark;' + light + '}'
+    + '@media (prefers-color-scheme:dark){html:not([data-theme]){' + dark + '}}'
+    + 'html[data-theme=dark]{color-scheme:dark;' + dark + '}'
+    + 'html[data-theme=light]{color-scheme:light;' + light + '}'
+    + 'html{background:var(--bg);color:var(--fg)}'
+  ;(document.head || root).appendChild(style)
+})()
+`
+/** The home and settings pages' own layout; their colours come from /appearance.js. */
 const APPEARANCE_STYLE =
-  '<style>:root{color-scheme:light dark}html[data-theme=dark]{color-scheme:dark;background:#111827;color:#f9fafb}html[data-theme=light]{color-scheme:light;background:#fff;color:#111827}body{font:16px system-ui,sans-serif;margin:2rem auto;max-width:42rem;padding:0 1rem}a{color:inherit}</style>'
-const APPEARANCE_SCRIPT =
-  "<script>(function(){try{var t=localStorage.getItem('theme');if(t==='dark'||t==='light')document.documentElement.dataset.theme=t}catch(e){}})()</script>"
+  '<style>body{font:16px system-ui,sans-serif;margin:2rem auto;max-width:42rem;padding:0 1rem}a{color:inherit}</style>'
+const appearanceScript = (prefix: string) => `<script src="${prefix}/appearance.js"></script>`
 
 /** `/settings`: the one setting the template has, the appearance. The desktop app's Settings menu item opens this page. */
-const settingsPage = `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>Settings - ${APP_NAME}</title>${APPEARANCE_STYLE}${APPEARANCE_SCRIPT}</head><body><h1>Settings</h1><p><label for="theme">Appearance</label> <select id="theme" name="theme"><option value="system">Match the system</option><option value="light">Light</option><option value="dark">Dark</option></select></p><p id="saved" role="status"></p><p><a href="/">Back to ${APP_NAME}</a></p><script>(function(){var select=document.getElementById('theme'),saved=document.getElementById('saved');try{select.value=localStorage.getItem('theme')||'system'}catch(e){}select.addEventListener('change',function(){var value=select.value;try{if(value==='system'){localStorage.removeItem('theme');delete document.documentElement.dataset.theme}else{localStorage.setItem('theme',value);document.documentElement.dataset.theme=value}saved.textContent='Saved: '+select.options[select.selectedIndex].text}catch(e){saved.textContent='This browser would not keep the setting.'}})})()</script></body></html>`
+const settingsPage = (prefix: string) =>
+  `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>Settings - ${APP_NAME}</title>${APPEARANCE_STYLE}${appearanceScript(prefix)}</head><body><h1>Settings</h1><p><label for="theme">Appearance</label> <select id="theme" name="theme"><option value="system">Match the system</option><option value="light">Light</option><option value="dark">Dark</option></select></p><p id="saved" role="status"></p><p><a href="${prefix}/">Back to ${APP_NAME}</a></p><script>(function(){var select=document.getElementById('theme'),saved=document.getElementById('saved');try{select.value=localStorage.getItem('theme')||'system'}catch(e){}select.addEventListener('change',function(){var value=select.value;try{if(value==='system'){localStorage.removeItem('theme');delete document.documentElement.dataset.theme}else{localStorage.setItem('theme',value);document.documentElement.dataset.theme=value}saved.textContent='Saved: '+select.options[select.selectedIndex].text}catch(e){saved.textContent='This browser would not keep the setting.'}})})()</script></body></html>`
 
+/**
+ * The app's own pages and routes, mountable at any prefix: the standalone server mounts it at the root, the frame row at {@link FRAME_MOUNT_PREFIX}.
+ * Every absolute URL a page writes is derived from the prefix it is mounted at.
+ */
+export function makeApp(prefix = ''): Acryl {
+  const limit = bodyLimit({ maxSize: 64 * 1024 })
+  return (
+    new Acryl()
+      .use(limit)
+      // A browser gets a page (the door's and the agent panel's script tags are added where they are mounted); everything else gets the JSON.
+      .get('/', (c) =>
+        (c.req.header('accept') ?? '').includes('text/html')
+          ? c.html(
+              `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>${APP_NAME}</title>${APPEARANCE_STYLE}${appearanceScript(prefix)}</head><body><h1>${APP_NAME}</h1><p>This app runs an agent unless it is switched off (production switches it off, see ACRYL_PRODUCTION_KEEP in AGENTS.md). In ACRYL, ask it for a change in the chat beside the app (or with <code>POST /ask</code>); published with the assistant on, it helps visitors use the app without changing it.</p>${DOOR_TAG}</body></html>`,
+            )
+          : c.json({ app: APP_NAME, ok: true }),
+      )
+      .get('/health', (c) => c.json({ ok: true }))
+      .get('/settings', (c) => c.html(settingsPage(prefix)))
+      .get('/appearance.js', (c) =>
+        c.body(APPEARANCE_JS, 200, {
+          'content-type': 'text/javascript; charset=utf-8',
+          'cache-control': 'no-cache',
+        }),
+      )
+  )
+}
+
+/** The app's own routes: an `App` mounted on the router at `options.prefix` (empty or absent: the root). */
 export const routes = {
   name: 'routes',
   inject: ['router'],
-  apply(ctx: Context) {
+  apply(ctx: Context, options: { readonly prefix?: string; readonly agentRoutes?: boolean } = {}) {
+    const prefix = options.prefix ?? ''
     // A body here is a name, an id or a question; anything bigger is refused before it is read.
     const json = async (c: {
       req: { json(): Promise<unknown> }
@@ -40,20 +101,11 @@ export const routes = {
       return typeof body === 'object' && body !== null ? (body as Record<string, unknown>) : {}
     }
     const limit = bodyLimit({ maxSize: 64 * 1024 })
-    const base = new Acryl()
-      .use(limit)
-      // A browser gets a page (the door's and the agent panel's script tags are added where they are mounted); everything else gets the JSON.
-      .get('/', (c) =>
-        (c.req.header('accept') ?? '').includes('text/html')
-          ? c.html(
-              `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>${APP_NAME}</title>${APPEARANCE_STYLE}${APPEARANCE_SCRIPT}</head><body><h1>${APP_NAME}</h1><p>This app runs an agent unless it is switched off (production switches it off, see ACRYL_PRODUCTION_KEEP in AGENTS.md). Ask it for a feature in the agent panel on this page (or with <code>POST /ask</code>).</p>${DOOR_TAG}</body></html>`,
-            )
-          : c.json({ app: APP_NAME, ok: true }),
-      )
-      .get('/health', (c) => c.json({ ok: true }))
-      .get('/settings', (c) => c.html(settingsPage))
-    ctx.router.route('/', base)
+    // The app's own page and routes at the one prefix; the agent routes below mount at the same prefix.
+    ctx.router.route(prefix === '' ? '/' : prefix, makeApp(prefix))
     // The routes that give a visitor the agent: mounted only while the agent, the extensions and the tasks run (see the header).
+    // `agentRoutes: false` (the production Assistant) keeps them unmounted although the agent runs.
+    if (options.agentRoutes === false) return
     ctx.inject(['agent', 'extensions', 'tasks'], (inner) => {
       const app = new Acryl().use(limit).get('/extensions', (c) =>
         c.json({
@@ -87,7 +139,7 @@ export const routes = {
             return c.json({ error: 'question must be a string' }, 400)
           return c.json(await inner.agent.run(question))
         })
-      inner.router.route('/', app)
+      inner.router.route(prefix === '' ? '/' : prefix, app)
     })
   },
 }

package/templates/agent/template.json

@@ -4,6 +4,8 @@
     "acryl-router",
     "acryl-state",
     "acryl-node-server",
+    "acryl-page",
+    "acryl-web-server",
     "tasks",
     "agent",
     "openai",