acrylblends 1.0.7 → 1.0.8

package/plugins/desktop/window.ts

@@ -1,23 +1,69 @@
 /** 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: down and to the right of `from` by one step, and back at the top left of the work area when that would put
+ * it past the edge of the screen (so a row of windows cascades, then starts again).
+ */
+export function cascade(
+  from: Rect,
+  work: Rect,
+  size: { width: number; height: number },
+): { x: number; y: number } {
+  const x = from.x + CASCADE_STEP
+  const y = from.y + CASCADE_STEP
+  const fitsRight = x + size.width <= work.x + work.width
+  const fitsBottom = y + size.height <= work.y + work.height
+  return { x: fitsRight ? x : work.x, y: fitsBottom ? y : work.y }
 }
 
 /**
  * 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) /)
+  }))