acrylblends 1.0.9 → 1.1.0

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

@@ -91,6 +91,8 @@ 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>`. */
+    // Where each window was opened: `window list` shows it until the page reports its own address (Electron gives none while the first load has not started).
+    const openedOn = new Map<number, string>()
     const createWindow = (path: string): BrowserWindow => {
       // A window opened while another is open sits a step down and to the right of it, not exactly on top.
       const beside =
@@ -112,6 +114,7 @@ if (!app.requestSingleInstanceLock()) {
         )
       })()
       const created = new BrowserWindow(windowOptions({ title: chosen.name, ...where }))
+      openedOn.set(created.id, path)
       created.webContents.setUserAgent(
         `${created.webContents.getUserAgent()} AcrylWindow/${String(created.id)}`,
       )
@@ -139,7 +142,8 @@ if (!app.requestSingleInstanceLock()) {
     const port = (candidate: BrowserWindow): WindowPort => ({
       id: candidate.id,
       getTitle: () => candidate.getTitle(),
-      getURL: () => candidate.webContents.getURL(),
+      getURL: () =>
+        candidate.webContents.getURL() || new URL(openedOn.get(candidate.id) ?? '/', url).href,
       isFocused: () => candidate.isFocused(),
       isMinimized: () => candidate.isMinimized(),
       getSize: () => candidate.getSize(),

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

package/templates/notes/src/main.ts

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