acrylblends 1.0.7 → 1.0.9

package/plugins/agent-panel/index.ts

@@ -9,17 +9,24 @@
  * - Only the app's own page may ask (a same-origin request carrying the token), one run at a time, and every ask is written to `.acryl/audit/agent-panel.jsonl`.
  * - Development only: the plugin does nothing with `NODE_ENV=production` or `ACRYL_DOOR=off`.
  */
-import { randomBytes } from 'node:crypto'
+import { randomBytes, timingSafeEqual } from 'node:crypto'
 import { appendFileSync, mkdirSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import type { Context } from '@deepseek-ai/cordis'
 import { clientModules } from '../acryl-node-server/src/client-modules.ts'
-import { streamSSE } from '../acryl-router/src/helpers/index.ts'
-import { Acryl } from '../acryl-router/src/index.ts'
+import { streamSSE, type UpgradeWebSocket } from '../acryl-router/src/helpers/index.ts'
+import { Acryl, type MiddlewareHandler } from '../acryl-router/src/index.ts'
+import { loopbackAuthority } from '../acryl-router/src/middleware/index.ts'
 import type {} from '../agent/index.ts'
 import type {} from '../extensions/index.ts'
 import type { ChatDriver } from './drivers.ts'
-import { agentDriver, availableHeadless, type HeadlessName, headlessDriver } from './headless.ts'
+import {
+  agentDriver,
+  availableHeadless,
+  type HeadlessName,
+  headlessDriver,
+  whyNotChat,
+} from './headless.ts'
 import { provideDrivers } from './registry.ts'
 
 export type {
@@ -117,25 +124,9 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
       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 message = typeof body.message === 'string' ? body.message.trim() : ''
-      const driverName = typeof body.driver === 'string' ? body.driver : 'agent'
-      if (message === '' || message.length > 8000)
-        return c.json({ error: 'write a message of at most 8000 characters' }, 400)
-      const driver = registry.get(driverName)
-      if (driver?.kind !== 'chat')
-        return c.json(
-          {
-            error: `the driver "${driverName}" is not available here (${registry
-              .list()
-              .filter((d) => d.kind === 'chat')
-              .map((d) => d.name)
-              .join(', ')})`,
-          },
-          400,
-        )
-      if (current !== undefined && !current.ended)
-        return c.json({ error: 'a run is already going; wait for it to end' }, 409)
-      const run = startRun(driverName, message, driver)
+      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)
       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.
@@ -151,11 +142,40 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
         return c.json({ error: "only the app's own page may read the run" }, 403)
       return current === undefined ? c.json({ run: null }) : follow(c, current, true)
     })
+  /** What `/ask` and the socket's `ask` both check: a message of a sensible size, a chat driver that is here, and no run going. */
+  const checkAsk = (
+    rawMessage: unknown,
+    rawDriver: unknown,
+  ):
+    | { message: string; driverName: string; driver: ChatDriver }
+    | { error: string; status: 400 | 409 } => {
+    const message = typeof rawMessage === 'string' ? rawMessage.trim() : ''
+    const driverName = typeof rawDriver === 'string' ? rawDriver : 'agent'
+    if (message === '' || message.length > 8000)
+      return { error: 'write a message of at most 8000 characters', status: 400 }
+    const driver = registry.get(driverName)
+    if (driver?.kind !== 'chat') {
+      const chat = registry
+        .list()
+        .filter((d) => d.kind === 'chat')
+        .map((d) => d.name)
+        .join(', ')
+      const why = whyNotChat(driverName, driver?.kind)
+      return {
+        error: `the driver "${driverName}" is not available here${why === undefined ? '' : `: ${why}`} (chat drivers: ${chat})`,
+        status: 400,
+      }
+    }
+    if (current !== undefined && !current.ended)
+      return { error: 'a run is already going; wait for it to end', status: 409 }
+    return { message, driverName, driver }
+  }
   /** One run of an agent: its events as they came, and who is following. It lives in the app, not in a page. */
   interface Run {
     readonly id: number
     readonly driver: string
     readonly message: string
+    readonly startedAt: number
     readonly events: Array<{ event: string; data: unknown }>
     readonly followers: Set<(item: { event: string; data: unknown }) => void>
     readonly cancel: AbortController
@@ -170,6 +190,7 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
       id: runs,
       driver: driverName,
       message,
+      startedAt: Date.now(),
       events: [],
       followers: new Set(),
       cancel: new AbortController(),
@@ -205,33 +226,36 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
     })()
     return run
   }
-  /** Follow a run as server-sent events: a `run` event (what it is, whether it already ended), the events so far, then the new ones until it ends. Following does not keep it alive. */
-  const follow = (c: Parameters<typeof streamSSE>[0], run: Run, announce: boolean): Response =>
-    streamSSE(c, async (stream) => {
-      if (announce)
-        await stream.writeSSE({
-          event: 'run',
-          data: JSON.stringify({
-            id: run.id,
-            driver: run.driver,
-            message: run.message,
-            ended: run.ended,
-            endedAt: run.endedAt ?? null,
-          }),
-        })
-      const queue: Array<{ event: string; data: unknown }> = [...run.events]
-      let wake: (() => void) | undefined
-      const follower = (item: { event: string; data: unknown }): void => {
-        queue.push(item)
-        wake?.()
-      }
-      if (!run.ended) run.followers.add(follower)
-      let open = true
-      stream.onAbort(() => {
-        open = false
-        run.followers.delete(follower)
-        wake?.()
+  /**
+   * Follow a run into `write`: a `run` event (what it is, whether it already ended) when `announce`, the events so far, then the new ones until it ends. Following does not keep the
+   * run alive. `detach` stops following (the page went away); `done` settles when the run ended or the following was detached.
+   */
+  const pump = (
+    run: Run,
+    announce: boolean,
+    write: (event: string, data: unknown) => void | Promise<void>,
+  ): { done: Promise<void>; detach(): void } => {
+    const queue: Array<{ event: string; data: unknown }> = [...run.events]
+    if (announce)
+      queue.unshift({
+        event: 'run',
+        data: {
+          id: run.id,
+          driver: run.driver,
+          message: run.message,
+          startedAt: run.startedAt,
+          ended: run.ended,
+          endedAt: run.endedAt ?? null,
+        },
       })
+    let wake: (() => void) | undefined
+    const follower = (item: { event: string; data: unknown }): void => {
+      queue.push(item)
+      wake?.()
+    }
+    if (!run.ended) run.followers.add(follower)
+    let open = true
+    const done = (async () => {
       try {
         while (open) {
           const item = queue.shift()
@@ -244,11 +268,130 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
             continue
           }
           if (item.event === 'end') break
-          await stream.writeSSE({ event: item.event, data: JSON.stringify(item.data) })
+          await write(item.event, item.data)
         }
       } finally {
         run.followers.delete(follower)
       }
+    })()
+    return {
+      done,
+      detach: () => {
+        open = false
+        run.followers.delete(follower)
+        wake?.()
+      },
+    }
+  }
+  /** Follow a run as server-sent events. */
+  const follow = (c: Parameters<typeof streamSSE>[0], run: Run, announce: boolean): Response =>
+    streamSSE(c, async (stream) => {
+      const following = pump(run, announce, (event, data) =>
+        stream.writeSSE({ event, data: JSON.stringify(data) }),
+      )
+      stream.onAbort(following.detach)
+      await following.done
     })
+  // The same runs over a WebSocket, which is not one of the browser's six connections per host: a page that streams its own state in two windows, with a run going, would otherwise
+  // queue the panel's Stop and the door's answers behind them. A WebSocket has no CORS and cannot set a header, so the Origin must be this app's own and the first frame carries the
+  // token. Frames: up `{ t: 'hello', token }`, then `{ t: 'ask', message, driver }`, `{ t: 'follow' }` or `{ t: 'stop' }`; down `{ e: <event>, d: <data> }`, as the stream's events.
+  // The server row comes after this plugin in a blend, so the WebSocket form is mounted when the server appears (and not at all without one that upgrades or without the `ws` package).
+  ctx.inject(['nodeServer'], (inner) => {
+    let upgrade: UpgradeWebSocket
+    try {
+      upgrade = (
+        inner as unknown as { nodeServer: { upgrades(): UpgradeWebSocket } }
+      ).nodeServer.upgrades()
+    } catch {
+      return
+    }
+    const ws = new Acryl()
+    const own: MiddlewareHandler = async (c, next) => {
+      const authority = loopbackAuthority(c)
+      const origin = c.req.header('origin')
+      const site = c.req.header('sec-fetch-site')
+      if (
+        authority === undefined ||
+        origin === undefined ||
+        origin !== authority.origin ||
+        (site !== undefined && site !== 'same-origin')
+      )
+        return c.json({ error: "only the app's own page may use the panel" }, 403)
+      await next()
+    }
+    const sameToken = (presented: unknown): boolean => {
+      if (typeof presented !== 'string') return false
+      const a = Buffer.from(presented)
+      const b = Buffer.from(token)
+      return a.length === b.length && timingSafeEqual(a, b)
+    }
+    ws.get(
+      `${PREFIX}/run/ws`,
+      own,
+      upgrade(
+        () => {
+          let authed = false
+          let following: { detach(): void } | undefined
+          let hello: NodeJS.Timeout | undefined
+          return {
+            onOpen(_event, ws) {
+              hello = setTimeout(() => ws.close(4401, 'no token'), 5000)
+            },
+            onMessage(event, ws) {
+              if (typeof event.data !== 'string') return
+              let message: { t?: unknown; token?: unknown; message?: unknown; driver?: unknown }
+              try {
+                message = JSON.parse(event.data) as typeof message
+              } catch {
+                return
+              }
+              if (!authed) {
+                if (message.t !== 'hello' || !sameToken(message.token)) {
+                  ws.close(4401, 'token')
+                  return
+                }
+                authed = true
+                if (hello !== undefined) clearTimeout(hello)
+                return
+              }
+              const send = (e: string, d: unknown): void => {
+                ws.send(JSON.stringify({ e, d }))
+              }
+              if (message.t === 'stop') {
+                current?.cancel.abort()
+                return
+              }
+              if (following !== undefined) return
+              const watch = (run: Run, announce: boolean): void => {
+                const pumped = pump(run, announce, send)
+                following = pumped
+                void pumped.done.then(() => ws.close(1000, 'run ended'))
+              }
+              if (message.t === 'ask') {
+                const checked = checkAsk(message.message, message.driver)
+                if ('error' in checked) {
+                  send('error', { message: checked.error })
+                  ws.close(1000, 'refused')
+                  return
+                }
+                watch(startRun(checked.driverName, checked.message, checked.driver), false)
+              } else if (message.t === 'follow') {
+                if (current === undefined) {
+                  send('idle', {})
+                  ws.close(1000, 'no run')
+                } else watch(current, true)
+              }
+            },
+            onClose() {
+              if (hello !== undefined) clearTimeout(hello)
+              following?.detach()
+            },
+          }
+        },
+        { textOnly: true },
+      ),
+    )
+    inner.router.route('/', ws)
+  })
   ctx.router.route('/', app)
 }

package/plugins/desktop/door-shell.ts

@@ -17,6 +17,7 @@ export interface WindowPort {
   isFocused(): boolean
   isMinimized(): boolean
   getSize(): number[]
+  getPosition(): number[]
   restore(): void
   focus(): void
   close(): void
@@ -68,6 +69,8 @@ export type ShellResult =
         focused: boolean
         width: number
         height: number
+        x?: number
+        y?: number
       }[]
     }
   | { readonly items: readonly { path: string; label: string; enabled: boolean; ends?: boolean }[] }
@@ -133,6 +136,7 @@ export function handleShellCall(request: ShellRequest, desktop: DesktopPort): Sh
       return {
         windows: desktop.windows().map((window) => {
           const [width = 0, height = 0] = window.getSize()
+          const [x = 0, y = 0] = window.getPosition()
           return {
             id: window.id,
             title: window.getTitle(),
@@ -140,6 +144,8 @@ export function handleShellCall(request: ShellRequest, desktop: DesktopPort): Sh
             focused: window.isFocused(),
             width,
             height,
+            x,
+            y,
           }
         }),
       }

package/plugins/desktop/main.ts

@@ -9,7 +9,7 @@
 import { mkdirSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { app, BrowserWindow, Menu, type MenuItem, shell } from 'electron'
+import { app, BrowserWindow, Menu, MenuItem, screen, shell } from 'electron'
 import type { App } from '../../src/app.ts'
 import '../acryl-node-server/src/register.ts'
 import { selectInstance } from '../instance/index.ts'
@@ -20,9 +20,10 @@ import {
   startDoorShell,
   type WindowPort,
 } from './door-shell.ts'
+import { hasSettings, settingsPlacement } from './menu.ts'
 import { createDesktopShutdown, installShutdownRequests } from './shutdown.ts'
 import { resolveDesktopUserDataOverride } from './user-data.ts'
-import { windowOptions } from './window.ts'
+import { cascade, windowOptions } from './window.ts'
 
 const projectRoot = fileURLToPath(new URL('../..', import.meta.url))
 const chosen = selectInstance({ projectRoot, env: process.env })
@@ -91,7 +92,26 @@ if (!app.requestSingleInstanceLock()) {
     const origin = new URL(url).origin
     /** One window on a path of the app. Navigation stays on the app's own server; any other address opens in the system browser. The user agent names the window to the door (`AcrylWindow/<id>`), so an agent can drive it with `--window <id>`. */
     const createWindow = (path: string): BrowserWindow => {
-      const created = new BrowserWindow(windowOptions({ title: chosen.name }))
+      // A window opened while another is open sits a step down and to the right of it, not exactly on top.
+      const beside =
+        BrowserWindow.getFocusedWindow() ??
+        BrowserWindow.getAllWindows().find((other) => !other.isDestroyed())
+      const where = (() => {
+        if (beside === undefined) return {}
+        const bounds = beside.getBounds()
+        // The places of the windows that are open: a new window never goes exactly where one already is.
+        const taken = BrowserWindow.getAllWindows()
+          .filter((other) => !other.isDestroyed())
+          .map((other) => other.getPosition())
+          .map(([x = 0, y = 0]) => ({ x, y }))
+        return cascade(
+          bounds,
+          screen.getDisplayMatching(bounds).workArea,
+          { width: 1100, height: 760 },
+          taken,
+        )
+      })()
+      const created = new BrowserWindow(windowOptions({ title: chosen.name, ...where }))
       created.webContents.setUserAgent(
         `${created.webContents.getUserAgent()} AcrylWindow/${String(created.id)}`,
       )
@@ -123,6 +143,7 @@ if (!app.requestSingleInstanceLock()) {
       isFocused: () => candidate.isFocused(),
       isMinimized: () => candidate.isMinimized(),
       getSize: () => candidate.getSize(),
+      getPosition: () => candidate.getPosition(),
       restore: () => candidate.restore(),
       focus: () => candidate.focus(),
       close: () => candidate.close(),
@@ -147,6 +168,40 @@ if (!app.requestSingleInstanceLock()) {
       open: (path) => port(createWindow(path ?? startPath())),
       menu: () => (Menu.getApplicationMenu()?.items ?? []).map(menuItem),
     }
+    // An app that serves a /settings page gets a Settings item in the menu (Electron's own menu otherwise): it opens that page, in the window that already shows it when there is one.
+    const settingsServed = await fetch(new URL('/settings', url), {
+      headers: { accept: 'text/html' },
+      signal: AbortSignal.timeout(2000),
+    }).then(
+      (answer) => answer.ok,
+      () => false,
+    )
+    const menu = Menu.getApplicationMenu()
+    const placement =
+      menu === null || !settingsServed || hasSettings(menu.items)
+        ? undefined
+        : settingsPlacement(menu.items, process.platform)
+    if (menu !== null && placement !== undefined) {
+      const target = menu.items[placement.menu]?.submenu
+      const openSettings = (): void => {
+        const shown = live().find(
+          (candidate) =>
+            new URL(candidate.webContents.getURL() || 'about:blank', url).pathname === '/settings',
+        )
+        if (shown === undefined) createWindow('/settings')
+        else {
+          if (shown.isMinimized()) shown.restore()
+          shown.focus()
+        }
+      }
+      target?.insert(
+        placement.at,
+        new MenuItem({ label: 'Settings...', accelerator: 'CmdOrCtrl+,', click: openSettings }),
+      )
+      if (placement.separatorAfter)
+        target?.insert(placement.at + 1, new MenuItem({ type: 'separator' }))
+      Menu.setApplicationMenu(menu)
+    }
     stopDoorShell = startDoorShell(projectRoot, { desktop, log: console.log })
   })
 }

package/plugins/desktop/menu.ts

@@ -0,0 +1,60 @@
+/**
+ * The desktop app's Settings menu item. An app that serves a `/settings` page gets a "Settings..." item that opens it in a window (Cmd+, on macOS, Ctrl+, elsewhere); an app without
+ * the page gets nothing. Where the item goes is decided here, from the labels of the application menu Electron built, so it is tested without Electron.
+ */
+
+/** The part of an Electron menu item this file reads. */
+export interface MenuNode {
+  readonly label: string
+  readonly role?: string | undefined
+  readonly type?: string | undefined
+  readonly submenu?: { readonly items: readonly MenuNode[] } | null | undefined
+}
+
+export interface Placement {
+  /** Index of the top-level menu that gets the item. */
+  readonly menu: number
+  /** Index inside that menu to insert at. */
+  readonly at: number
+  /** Whether a separator goes after the item (so it sits in a group of its own). */
+  readonly separatorAfter: boolean
+}
+
+/**
+ * macOS puts Settings in the application menu, under About; elsewhere it is the first item of the File menu. Returns nothing when the menu has neither place (an app that
+ * replaced Electron's menu with its own keeps its own).
+ */
+export function settingsPlacement(
+  items: readonly MenuNode[],
+  platform: NodeJS.Platform,
+): Placement | undefined {
+  if (platform === 'darwin') {
+    const submenu = items[0]?.submenu?.items
+    if (submenu === undefined || submenu === null) return undefined
+    const about = submenu.findIndex(
+      (item) => item.role === 'about' || /^about\b/iu.test(item.label),
+    )
+    // Under About and the separator after it; first when there is no About.
+    const separator =
+      about === -1
+        ? -1
+        : submenu.findIndex((item, index) => index > about && item.type === 'separator')
+    return {
+      menu: 0,
+      at: separator === -1 ? (about === -1 ? 0 : about + 1) : separator + 1,
+      separatorAfter: true,
+    }
+  }
+  const file = items.findIndex((item) => /^&?file$/iu.test(item.label) || item.role === 'fileMenu')
+  if (file === -1 || items[file]?.submenu == null) return undefined
+  return { menu: file, at: 0, separatorAfter: true }
+}
+
+/** Whether a menu already has a Settings item (so a restart that builds the menu twice adds it once). */
+export function hasSettings(items: readonly MenuNode[]): boolean {
+  return items.some(
+    (item) =>
+      /^settings\b|^preferences\b/iu.test(item.label) ||
+      (item.submenu?.items !== undefined && hasSettings(item.submenu.items)),
+  )
+}

package/plugins/desktop/window.ts

@@ -1,23 +1,83 @@
 /** The one window of a desktop app: the operating system's frame around a page the app's own server serves, with the renderer locked down. */
-import type { BrowserWindowConstructorOptions } from 'electron'
 
 export interface WindowSpec {
   readonly title: string
   readonly width?: number
   readonly height?: number
+  /** Where the window's top left corner goes; Electron centers the window when these are left out. */
+  readonly x?: number
+  readonly y?: number
+}
+
+export interface Rect {
+  readonly x: number
+  readonly y: number
+  readonly width: number
+  readonly height: number
+}
+
+/** How far each new window sits from the one it was opened from. */
+export const CASCADE_STEP = 32
+
+/**
+ * Where a new window goes so that it does not cover another one exactly. The first free place of: a step down and to the right of `from`, and again, while the window still fits on the
+ * screen; then the same steps from the top left of the work area (a row of windows cascades, then starts again); and, on a screen no bigger than the window, the steps from `from` even
+ * though the window runs past the edge (two windows at one place cannot be told apart). A place is free when no window in `taken` is there.
+ */
+export function cascade(
+  from: Rect,
+  work: Rect,
+  size: { width: number; height: number },
+  taken: readonly { x: number; y: number }[] = [],
+): { x: number; y: number } {
+  const free = (place: { x: number; y: number }): boolean =>
+    !taken.some((other) => other.x === place.x && other.y === place.y)
+  const fits = (place: { x: number; y: number }): boolean =>
+    place.x + size.width <= work.x + work.width && place.y + size.height <= work.y + work.height
+  const steps = (origin: { x: number; y: number }): { x: number; y: number }[] =>
+    Array.from({ length: 40 }, (_, at) => ({
+      x: origin.x + CASCADE_STEP * (at + 1),
+      y: origin.y + CASCADE_STEP * (at + 1),
+    }))
+  const fromHere = steps(from)
+  const fromCorner = [{ x: work.x, y: work.y }, ...steps(work)]
+  return (
+    fromHere.find((place) => fits(place) && free(place)) ??
+    fromCorner.find((place) => fits(place) && free(place)) ??
+    fromHere.find(free) ??
+    fromHere[0] ?? { x: from.x + CASCADE_STEP, y: from.y + CASCADE_STEP }
+  )
 }
 
 /**
  * Secure BrowserWindow options. The settings are ACRYL Desktop's: context isolation on, no Node in the page, the sandbox on, web security on; the window stays
  * hidden until the page has painted (`show: false`, shown on `ready-to-show`).
  */
-export function windowOptions(spec: WindowSpec): BrowserWindowConstructorOptions {
+export interface WindowOptions {
+  readonly title: string
+  readonly width: number
+  readonly height: number
+  readonly minWidth: number
+  readonly minHeight: number
+  readonly x?: number
+  readonly y?: number
+  readonly show: boolean
+  readonly webPreferences: {
+    readonly contextIsolation: boolean
+    readonly nodeIntegration: boolean
+    readonly sandbox: boolean
+    readonly webSecurity: boolean
+  }
+}
+
+export function windowOptions(spec: WindowSpec): WindowOptions {
   return {
     title: spec.title,
     width: spec.width ?? 1100,
     height: spec.height ?? 760,
     minWidth: 480,
     minHeight: 360,
+    ...(spec.x === undefined || spec.y === undefined ? {} : { x: spec.x, y: spec.y }),
     show: false,
     webPreferences: {
       contextIsolation: true,

package/templates/agent/AGENTS.md

@@ -7,6 +7,8 @@ and an optional `check(ctx)` that receives the plugin's own context (so `ctx.rou
 
 **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.
 
-**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. When a person asks for settings, build them as a page at `/settings`, so `acryl window open --path /settings` opens them in every app. Without a desktop app these answer "no desktop window is attached; run npm run desktop".
+**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.
 
 **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

@@ -19,6 +19,15 @@ const DOOR_TAG =
  * 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
  * 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. */
+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>"
+
+/** `/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>`
+
 export const routes = {
   name: 'routes',
   inject: ['router'],
@@ -37,11 +46,12 @@ export const routes = {
       .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></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>`,
+              `<!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 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

@@ -144,3 +144,23 @@ test('outside production nothing changes: the agent answers and the extensions r
     assert.equal((await app.root.router.request('/extensions')).status, 200)
     assert.deepEqual(warnings, [])
   }))
+
+test('the app has a /settings page with the appearance setting, and the home page applies it', () =>
+  inEnvironment({ NODE_ENV: 'test', ACRYL_PRODUCTION_KEEP: undefined }, async (app) => {
+    const settings = await app.root.router.request('/settings', {
+      headers: { accept: 'text/html' },
+    })
+    assert.equal(settings.status, 200)
+    const page = await settings.text()
+    assert.match(page, /<h1>Settings<\/h1>/)
+    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.
+    const home = await (
+      await app.root.router.request('/', { headers: { accept: 'text/html' } })
+    ).text()
+    assert.match(home, /localStorage\.getItem\('theme'\)/)
+    // ... without leaving a global behind for the page's own code to collide with.
+    assert.doesNotMatch(home, /<script>\s*(?:var|let|const) /)
+  }))