acrylblends 1.0.10 → 1.1.0

package/plugins/acryl-state/src/socket.ts

@@ -0,0 +1,96 @@
+/**
+ * State over a WebSocket. A server-sent event stream holds one of the browser's six connections per host for as long as the page lives, and an app that follows a few keys in
+ * several windows uses them all; a WebSocket is not one of those six, and one socket carries every key of a page.
+ *
+ * `GET /api/state/ws` upgrades. Up, one JSON message per frame: `{ "t": "sub", "key": "<key>" }` and `{ "t": "unsub", "key": "<key>" }`. Down: `{ "key": "<key>", "value": <json> }` once on
+ * `sub` and after every change, `{ "key": "<key>", "error": "<why>" }` for a key that cannot be followed, and `{ "t": "ping" }` every {@link SOCKET_HEARTBEAT_MS} so a page can tell a quiet
+ * socket from a dead one. `GET /api/state/client.js` is the browser module that speaks this (`watch(key, callback)`), with the event stream as its fallback.
+ *
+ * A WebSocket has no CORS, so the upgrade is checked here ({@link refuseStranger}): a loopback peer on this port with a loopback `Host`, and an `Origin` that, when the request has one,
+ * is exactly this app's own origin. A program on this machine that sends no `Origin` (a script, a test) is let in, as it is for the JSON and stream routes; a web page of another
+ * origin, and a name that only resolves to this machine (DNS rebinding), are not.
+ */
+
+import type { Context, MiddlewareHandler } from 'acryl-router'
+import type { UpgradeWebSocket } from 'acryl-router/helpers'
+import { loopbackAuthority } from 'acryl-router/middleware'
+import type { ReadonlyCell } from './cell.ts'
+
+/** How often the server writes a `ping`; a page gives up on a socket that is silent for three of these. */
+export const SOCKET_HEARTBEAT_MS = 15_000
+
+/** How many keys one socket may follow; a page watches a handful. */
+export const MAX_KEYS_PER_SOCKET = 256
+
+/** What the socket needs of the state service. */
+export interface Cells {
+  find(key: string): ReadonlyCell<unknown> | undefined
+}
+
+export interface StateSocketOptions {
+  readonly upgrade: UpgradeWebSocket
+  readonly heartbeatMs?: number
+}
+
+/** A refusal (403) unless the upgrade comes from this machine to this app, and from its own page when it comes from a page at all. */
+export function refuseStranger(c: Context): Response | undefined {
+  const authority = loopbackAuthority(c)
+  if (authority === undefined) return c.json({ error: 'request authority rejected' }, 403)
+  const origin = c.req.header('origin')
+  const site = c.req.header('sec-fetch-site')
+  if ((origin !== undefined && origin !== authority.origin) || (site !== undefined && site !== 'same-origin')) {
+    return c.json({ error: 'only this app\'s own page may follow its state' }, 403)
+  }
+  return undefined
+}
+
+/** The route handler that upgrades and follows keys of `cells` for as long as the socket is open. */
+export function stateSocket(cells: Cells, options: StateSocketOptions): MiddlewareHandler {
+  const heartbeatMs = options.heartbeatMs ?? SOCKET_HEARTBEAT_MS
+  return options.upgrade(() => {
+    const following = new Map<string, () => void>()
+    let beat: NodeJS.Timeout | undefined
+    return {
+      onOpen(_event, ws) {
+        beat = setInterval(() => {
+          try { ws.send(JSON.stringify({ t: 'ping' })) } catch { /* the close event follows */ }
+        }, heartbeatMs)
+        beat.unref()
+      },
+      onMessage(event, ws) {
+        if (typeof event.data !== 'string') return
+        let message: { t?: unknown, key?: unknown }
+        try { message = JSON.parse(event.data) as typeof message } catch { return }
+        if (typeof message.key !== 'string') return
+        const key = message.key
+        const tell = (frame: object): void => {
+          try { ws.send(JSON.stringify(frame)) } catch { /* the close event follows */ }
+        }
+        const value = (current: unknown): void => {
+          let text: string
+          try { text = JSON.stringify({ key, value: current === undefined ? null : current }) } catch { tell({ key, error: 'the value cannot be sent as JSON' }); return }
+          try { ws.send(text) } catch { /* the close event follows */ }
+        }
+        if (message.t === 'unsub') {
+          following.get(key)?.()
+          following.delete(key)
+          return
+        }
+        if (message.t !== 'sub') return
+        const cell = cells.find(key)
+        if (cell === undefined) { tell({ key, error: 'no such state' }); return }
+        const known = following.has(key)
+        if (!known && following.size >= MAX_KEYS_PER_SOCKET) { tell({ key, error: 'too many keys on one socket' }); return }
+        // A key asked for twice is answered again with its value, and followed once.
+        if (known) { value(cell.get()); return }
+        value(cell.get())
+        following.set(key, cell.subscribe(value))
+      },
+      onClose() {
+        if (beat !== undefined) clearInterval(beat)
+        for (const stop of following.values()) stop()
+        following.clear()
+      },
+    }
+  }, { textOnly: true })
+}

package/plugins/agent-panel/client/main.ts

@@ -42,70 +42,90 @@ interface RunSource {
   readonly events: AsyncIterable<PanelEvent>
 }
 
+/** The door's id for this page, when the door is in it: sent with a question so the agent's calls (which name no window) drive this page and not another open one. */
+function doorPage(): { page?: string } {
+  const published = (window as unknown as Record<symbol, { windowId?: unknown } | undefined>)[
+    Symbol.for('acryl.door.page')
+  ]
+  return typeof published?.windowId === 'string' ? { page: published.windowId } : {}
+}
+
 /** A WebSocket is not one of the browser's six connections per host, so the panel's Stop and a run still work when two windows stream their own state. */
 let socketBroken = false
 let activeSocket: WebSocket | undefined
 
-/** Open the run socket and send the token and the first action. Rejects when the page cannot upgrade (a proxy, a server without `ws`): the caller falls back to the stream. */
-function openSocket(token: string, action: Record<string, unknown>): Promise<WebSocket> {
+/** The server did not accept the token: it is not the one this page was given (the app restarted since, which `node --watch` does at every change of a file). */
+class Refused extends Error {}
+
+/**
+ * Open the run socket and send the token and the first action. Resolves once the server has accepted the token (its `accepted` frame), with the socket and its events: the
+ * frames of the run as panel events, until the socket closes. One set of handlers serves the socket for its whole life, so a frame is never handed to a handler that was
+ * replaced. Rejects with `Refused` when the token is not accepted, and with another error when the page cannot upgrade (a proxy, a server without `ws`): the caller falls back
+ * to the stream.
+ */
+function openSocket(
+  token: string,
+  action: Record<string, unknown>,
+): Promise<{ socket: WebSocket; events: AsyncGenerator<PanelEvent> }> {
   return new Promise((resolve, reject) => {
     const socket = new WebSocket(
       `${location.protocol === 'https:' ? 'wss' : 'ws'}://${location.host}${PREFIX}/run/ws`,
     )
+    const queue: PanelEvent[] = []
+    let wake: (() => void) | undefined
+    let closed = false
+    let accepted = false
     const timer = setTimeout(() => {
       socket.close()
-      reject(new Error('the socket did not open in time'))
+      reject(new Error('the socket was not accepted in time'))
     }, 4000)
     socket.onopen = () => {
-      clearTimeout(timer)
       socket.send(JSON.stringify({ t: 'hello', token }))
       socket.send(JSON.stringify(action))
-      resolve(socket)
     }
-    socket.onerror = () => {
-      clearTimeout(timer)
-      reject(new Error('the server refused the upgrade'))
+    socket.onmessage = (message) => {
+      try {
+        const frame = JSON.parse(String(message.data)) as { e?: unknown; d?: unknown }
+        if (frame.e === 'accepted' && !accepted) {
+          accepted = true
+          clearTimeout(timer)
+          resolve({ socket, events: read() })
+        } else if (typeof frame.e === 'string')
+          queue.push({ event: frame.e, data: (frame.d ?? {}) as Record<string, unknown> })
+      } catch {
+        // Not a frame of ours.
+      }
+      wake?.()
     }
-  })
-}
-
-/** The frames of an open run socket as panel events, until it closes. */
-async function* socketEvents(socket: WebSocket): AsyncGenerator<PanelEvent> {
-  const queue: PanelEvent[] = []
-  let wake: (() => void) | undefined
-  let closed: CloseEvent | undefined
-  socket.onmessage = (message) => {
-    try {
-      const frame = JSON.parse(String(message.data)) as { e?: unknown; d?: unknown }
-      if (typeof frame.e === 'string')
-        queue.push({ event: frame.e, data: (frame.d ?? {}) as Record<string, unknown> })
-    } catch {
-      // Not a frame of ours.
+    socket.onclose = (event) => {
+      clearTimeout(timer)
+      closed = true
+      if (!accepted)
+        reject(
+          event.code === 4401
+            ? new Refused('the token was not accepted')
+            : new Error('the socket closed before it was accepted'),
+        )
+      wake?.()
     }
-    wake?.()
-  }
-  socket.onclose = (event) => {
-    closed = event
-    wake?.()
-  }
-  for (;;) {
-    const next = queue.shift()
-    if (next !== undefined) {
-      yield next
-      continue
+    socket.onerror = () => {
+      clearTimeout(timer)
+      if (!accepted) reject(new Error('the server refused the upgrade'))
     }
-    if (closed !== undefined) {
-      if (closed.code === 4401)
-        yield {
-          event: 'error',
-          data: { message: 'the panel was not accepted (reload the page and try again)' },
+    async function* read(): AsyncGenerator<PanelEvent> {
+      for (;;) {
+        const next = queue.shift()
+        if (next !== undefined) {
+          yield next
+          continue
         }
-      return
+        if (closed) return
+        await new Promise<void>((done) => {
+          wake = done
+        })
+      }
     }
-    await new Promise<void>((resolve) => {
-      wake = resolve
-    })
-  }
+  })
 }
 
 const css = `
@@ -145,7 +165,7 @@ textarea { width: 100%; min-height: 64px; resize: vertical; padding: 8px; border
 async function start(): Promise<void> {
   const reply = await fetch(`${PREFIX}/session`)
   if (!reply.ok) return
-  const session = (await reply.json()) as Session
+  let session = (await reply.json()) as Session
 
   const host = document.createElement('div')
   host.id = 'agent-panel'
@@ -199,6 +219,7 @@ async function start(): Promise<void> {
           onChange(change: { extension: string; action: string }): void
         }): Promise<{ detach(): void; stop(): Promise<void> }>
       }
+      await refreshSession()
       terminal = await openTerminal({
         container: term,
         token: session.token,
@@ -265,26 +286,41 @@ async function start(): Promise<void> {
   // A run belongs to the app, not to this page: it goes on when the page reloads (the door reloads it after a plugin change, an agent may move it to another page) and the page that
   // loads next follows it again. Only Stop cancels it.
   const headers = { 'content-type': 'application/json', 'x-agent-panel-token': session.token }
+  /**
+   * The token belongs to one start of the app: `node --watch` restarts it at every change of a file, and a page left open across that restart holds a token the new server
+   * does not know. Ask for the session again; the caller tries once more with what it gets.
+   */
+  const refreshSession = async (): Promise<void> => {
+    const reply = await fetch(`${PREFIX}/session`)
+    if (!reply.ok) return
+    session = (await reply.json()) as Session
+    headers['x-agent-panel-token'] = session.token
+  }
   let following = false
-  stop.addEventListener('click', () => {
+  const stopRun = (): void => {
     // On the run's socket when there is one: a request would wait behind the browser's six connections per host.
     if (activeSocket?.readyState === WebSocket.OPEN)
       activeSocket.send(JSON.stringify({ t: 'stop' }))
     else void fetch(`${PREFIX}/stop`, { method: 'POST', headers })
-  })
-  /** A run over the socket when the server upgrades, else over the stream, with one console warning saying why. */
-  const openRun = async (
-    action: { t: 'ask'; message: string; driver: string } | { t: 'follow' },
-  ): Promise<RunSource | { error: string } | undefined> => {
+  }
+  stop.addEventListener('click', stopRun)
+  // The door's "Agent is driving" bar has a Stop too (the same page): it ends this run.
+  window.addEventListener('acryl:stop-run', stopRun)
+  const REFUSED = Symbol('refused')
+  /** A run over the socket when the server upgrades, else over the stream, with one console warning saying why. `REFUSED` when the server does not know the token. */
+  const tryOpenRun = async (
+    action: { t: 'ask'; message: string; driver: string; page?: string } | { t: 'follow' },
+  ): Promise<RunSource | { error: string } | undefined | typeof REFUSED> => {
     if (!socketBroken && typeof WebSocket !== 'undefined') {
       try {
-        const socket = await openSocket(session.token, action)
+        const { socket, events: frames } = await openSocket(session.token, action)
         activeSocket = socket
         socket.addEventListener('close', () => {
           if (activeSocket === socket) activeSocket = undefined
         })
-        return { events: socketEvents(socket) }
+        return { events: frames }
       } catch (cause) {
+        if (cause instanceof Refused) return REFUSED
         socketBroken = true
         console.warn(
           `agent-panel: the run could not open a WebSocket (${cause instanceof Error ? cause.message : String(cause)}); using server-sent events, which count against the browser's six connections per host`,
@@ -295,8 +331,9 @@ async function start(): Promise<void> {
       const response = await fetch(`${PREFIX}/ask`, {
         method: 'POST',
         headers,
-        body: JSON.stringify({ message: action.message, driver: action.driver }),
+        body: JSON.stringify({ message: action.message, driver: action.driver, page: action.page }),
       })
+      if (response.status === 403) return REFUSED
       if (!response.ok)
         return {
           error:
@@ -306,10 +343,23 @@ async function start(): Promise<void> {
       return { events: events(response) }
     }
     const latest = await fetch(`${PREFIX}/run`, { headers })
+    if (latest.status === 403) return REFUSED
     return latest.ok && (latest.headers.get('content-type') ?? '').includes('text/event-stream')
       ? { events: events(latest) }
       : undefined
   }
+  /** `tryOpenRun`, and when the token was refused, a new session and one more try without the person seeing anything; a second refusal is shown. */
+  const openRun = async (
+    action: { t: 'ask'; message: string; driver: string; page?: string } | { t: 'follow' },
+  ): Promise<RunSource | { error: string } | undefined> => {
+    const first = await tryOpenRun(action)
+    if (first !== REFUSED) return first
+    await refreshSession()
+    const second = await tryOpenRun(action)
+    return second === REFUSED
+      ? { error: 'the panel was not accepted (reload the page and try again)' }
+      : second
+  }
   /**
    * Show one run, as its events come, until it ends. `own` is true for a run this page just started (its question is on screen); a run found on load is shown from its question, and
    * a run that had already ended before the page loaded is only shown, never reloads the page.
@@ -400,7 +450,7 @@ async function start(): Promise<void> {
     input.value = ''
     line(message, 'me')
     try {
-      const run = await openRun({ t: 'ask', message, driver: driver.value })
+      const run = await openRun({ t: 'ask', message, driver: driver.value, ...doorPage() })
       if (run === undefined) return
       if ('error' in run) {
         line(run.error, 'err')

package/plugins/agent-panel/index.ts

@@ -42,6 +42,11 @@ export const name = 'agent-panel'
 export const inject = ['router', 'agent', 'extensions', 'appInstance']
 
 const PREFIX = '/api/agent-panel'
+
+/** The slice of the door the panel uses; the door is optional (it is a development plugin, and a different row). */
+interface DoorPort {
+  driveFor(windowId: string): () => void
+}
 const CLIENT_DIR = join(import.meta.dirname, 'client')
 
 export interface PanelConfig {
@@ -123,10 +128,14 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
     .post(`${PREFIX}/ask`, async (c) => {
       if (!fromOwnPage(c.req.raw.headers) || c.req.header('x-agent-panel-token') !== token)
         return c.json({ error: "only the app's own page may ask" }, 403)
-      const body = (await c.req.json().catch(() => ({}))) as { message?: unknown; driver?: unknown }
+      const body = (await c.req.json().catch(() => ({}))) as {
+        message?: unknown
+        driver?: unknown
+        page?: unknown
+      }
       const checked = checkAsk(body.message, body.driver)
       if ('error' in checked) return c.json({ error: checked.error }, checked.status)
-      const run = startRun(checked.driverName, checked.message, checked.driver)
+      const run = startRun(checked.driverName, checked.message, checked.driver, pageOf(body.page))
       return follow(c, run, false)
     })
     // Stop: the only thing that cancels a run. A page that goes away (a reload, a move to another page, a closed tab) does not: the agent goes on, and the page picks it up again.
@@ -184,7 +193,15 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
   }
   let current: Run | undefined
   let runs = 0
-  const startRun = (driverName: string, message: string, driver: ChatDriver): Run => {
+  /** The door's id of the page that asked, when it sent one that looks like it. */
+  const pageOf = (raw: unknown): string | undefined =>
+    typeof raw === 'string' && /^[A-Za-z0-9-]{1,80}$/u.test(raw) ? raw : undefined
+  const startRun = (
+    driverName: string,
+    message: string,
+    driver: ChatDriver,
+    page?: string,
+  ): Run => {
     runs += 1
     const run: Run = {
       id: runs,
@@ -209,6 +226,9 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
     })
     ctx.effect(() => () => run.cancel.abort(), `agent-panel: run ${runs}`)
     audit({ ask: 'start', driver: driverName, characters: message.length })
+    // The agent's door calls name no window: while this run goes, they are for the page whose panel asked, not for another tab or window that happens to be open.
+    const door = page === undefined ? undefined : (ctx.get('door') as DoorPort | undefined)
+    const releasePage = door?.driveFor(page as string)
     void (async () => {
       try {
         for await (const { event, data } of driver.start({ message, signal: run.cancel.signal }))
@@ -218,6 +238,7 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
         emit('error', { message: error instanceof Error ? error.message : String(error) })
       } finally {
         off()
+        releasePage?.()
         run.ended = true
         run.endedAt = Date.now()
         audit({ ask: 'end', driver: driverName, changed })
@@ -339,7 +360,13 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
             },
             onMessage(event, ws) {
               if (typeof event.data !== 'string') return
-              let message: { t?: unknown; token?: unknown; message?: unknown; driver?: unknown }
+              let message: {
+                t?: unknown
+                token?: unknown
+                message?: unknown
+                driver?: unknown
+                page?: unknown
+              }
               try {
                 message = JSON.parse(event.data) as typeof message
               } catch {
@@ -352,6 +379,8 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
                 }
                 authed = true
                 if (hello !== undefined) clearTimeout(hello)
+                // The page waits for this before it counts the socket as open: a token it was given by an earlier start of the app is refused (4401) and it asks for a new one.
+                ws.send(JSON.stringify({ e: 'accepted', d: {} }))
                 return
               }
               const send = (e: string, d: unknown): void => {
@@ -374,7 +403,15 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
                   ws.close(1000, 'refused')
                   return
                 }
-                watch(startRun(checked.driverName, checked.message, checked.driver), false)
+                watch(
+                  startRun(
+                    checked.driverName,
+                    checked.message,
+                    checked.driver,
+                    pageOf(message.page),
+                  ),
+                  false,
+                )
               } else if (message.t === 'follow') {
                 if (current === undefined) {
                   send('idle', {})

package/plugins/instance/index.ts

@@ -44,6 +44,9 @@ export const PORT_SPAN = 900
 export const HOME_ENV = 'ACRYLBLENDS_HOME'
 export const PORT_ENV = 'ACRYLBLENDS_PORT'
 export const HOST_ENV = 'ACRYLBLENDS_HOST'
+/** The names hosting platforms set: used when `ACRYLBLENDS_PORT` and `ACRYLBLENDS_HOST` are not. */
+export const PLATFORM_PORT_ENV = 'PORT'
+export const PLATFORM_HOST_ENV = 'HOST'
 
 export class AppInstanceError extends Error {
   override name = 'AppInstanceError'
@@ -134,7 +137,7 @@ export function withPort(instance: AppInstance, start: number): AppInstance {
 
 /**
  * Choose the instance. The only place that reads the environment: `ACRYLBLENDS_HOME` pins the home, `ACRYLBLENDS_PORT` sets the start port, `ACRYLBLENDS_HOST` the interface;
- * otherwise the project folder decides.
+ * hosting platforms set `PORT` and `HOST` instead, and those are read when the `ACRYLBLENDS_` ones are not; otherwise the project folder decides.
  */
 export function selectInstance(options: {
   projectRoot: string
@@ -145,9 +148,9 @@ export function selectInstance(options: {
   let instance = pinned
     ? pinnedInstance(pinned, { name: plainName(options.projectRoot), root: options.projectRoot })
     : projectInstance(options.projectRoot)
-  const port = env[PORT_ENV]?.trim()
+  const port = env[PORT_ENV]?.trim() || env[PLATFORM_PORT_ENV]?.trim()
   if (port) instance = withPort(instance, Number(port))
-  const host = env[HOST_ENV]?.trim()
+  const host = env[HOST_ENV]?.trim() || env[PLATFORM_HOST_ENV]?.trim()
   if (host) instance = Object.freeze({ ...instance, host })
   return instance
 }

package/templates/agent/AGENTS.md

@@ -9,6 +9,8 @@ and an optional `check(ctx)` that receives the plugin's own context (so `ctx.rou
 
 **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/src/routes.ts

@@ -16,14 +16,41 @@ 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 APPEARANCE_SCRIPT = '<script src="/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>`
@@ -52,6 +79,12 @@ export const routes = {
       )
       .get('/health', (c) => c.json({ ok: true }))
       .get('/settings', (c) => c.html(settingsPage))
+      .get('/appearance.js', (c) =>
+        c.body(APPEARANCE_JS, 200, {
+          'content-type': 'text/javascript; charset=utf-8',
+          'cache-control': 'no-cache',
+        }),
+      )
     ctx.router.route('/', base)
     // The routes that give a visitor the agent: mounted only while the agent, the extensions and the tasks run (see the header).
     ctx.inject(['agent', 'extensions', 'tasks'], (inner) => {

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

@@ -156,11 +156,47 @@ test('the app has a /settings page with the appearance setting, and the home pag
     assert.match(page, /<select id="theme"/)
     for (const option of ['System', 'Light', 'Dark'])
       assert.match(page, new RegExp(`>(?:Match the )?${option.toLowerCase()}|>${option}<`, 'i'))
-    // The setting is kept in the browser and applied to the home page before it paints.
+    // The setting is kept in the browser and applied to the home page before it paints, by the one script every page of the app can carry.
     const home = await (
       await app.root.router.request('/', { headers: { accept: 'text/html' } })
     ).text()
-    assert.match(home, /localStorage\.getItem\('theme'\)/)
+    assert.match(home, /<script src="\/appearance\.js"><\/script>/)
+    assert.match(page, /<script src="\/appearance\.js"><\/script>/)
     // ... without leaving a global behind for the page's own code to collide with.
     assert.doesNotMatch(home, /<script>\s*(?:var|let|const) /)
+    const script = await app.root.router.request('/appearance.js')
+    assert.equal(script.status, 200)
+    assert.match(script.headers.get('content-type') ?? '', /javascript/)
+    const code = await script.text()
+    assert.match(code, /localStorage\.getItem\('theme'\)/)
+    // A change made in another window of the app is applied here at once, and the colours are custom properties for a page to use.
+    assert.match(code, /addEventListener\('storage'/)
+    for (const token of ['--bg', '--fg', '--muted', '--surface', '--border', '--accent'])
+      assert.ok(code.includes(token), token)
+    assert.match(code, /prefers-color-scheme:dark/)
+    // Run against a stand-in page: it applies the saved choice, follows a change made in another window, and goes back to the system's choice when the setting is removed.
+    const storage = new Map<string, string>([['theme', 'dark']])
+    const dataset: Record<string, string> = {}
+    const appended: Array<{ id: string; textContent: string }> = []
+    const listeners: Array<(event: { key: string | null }) => void> = []
+    new Function('document', 'localStorage', 'addEventListener', code)(
+      {
+        documentElement: { dataset },
+        head: { appendChild: (style: { id: string; textContent: string }) => appended.push(style) },
+        createElement: () => ({ id: '', textContent: '' }),
+      },
+      { getItem: (key: string) => storage.get(key) ?? null },
+      (_type: string, listener: (event: { key: string | null }) => void) =>
+        listeners.push(listener),
+    )
+    assert.equal(dataset.theme, 'dark')
+    assert.equal(appended[0]?.id, 'appearance')
+    storage.set('theme', 'light')
+    for (const listener of listeners) listener({ key: 'theme' })
+    assert.equal(dataset.theme, 'light')
+    storage.delete('theme')
+    for (const listener of listeners) listener({ key: 'something-else' })
+    assert.equal(dataset.theme, 'light')
+    for (const listener of listeners) listener({ key: null })
+    assert.equal(dataset.theme, undefined)
   }))

package/templates/chat/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.CHAT_DB ? { database: process.env.CHAT_DB } : {}),

package/templates/nodejs/src/main.ts

@@ -6,12 +6,7 @@ import { APP_NAME } from './routes.ts'
 // The composition root: the one place that reads the environment (through selectInstance) 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)
 console.log(`${APP_NAME} listening on ${app.url} (data in ${chosen.home})`)