acrylblends 1.1.0 → 1.2.0

package/plugins/desktop/frame.ts

@@ -0,0 +1,231 @@
+/**
+ * The desktop window on the ACRYL frame (docs/plans/ide-host-inversion.md, section 27). An app with `scripts/ide-host.mjs` runs inside the frame on `npm run dev`;
+ * `npm run desktop` shows that same frame: it attaches to a host that already runs (the host's address record, `.acrylblends/frame-url.json`), or starts the host
+ * the way `npm run dev` does and loads the address it prints. Nothing here imports electron: `main.ts` decides with these functions and owns the window.
+ */
+import { type ChildProcess, spawn, spawnSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { connect } from 'node:net'
+import { join, resolve } from 'node:path'
+
+/** The launcher every frame app has; without it the app runs on its own server (made before the frame). */
+export const HOST_SCRIPT = join('scripts', 'ide-host.mjs')
+
+/** The line the host prints once it serves the frame, with the launch token in the address. */
+const HOST_LINE = /acrylblends host: (http:\/\/\S+)/u
+
+const LOOPBACK = new Set(['127.0.0.1', 'localhost', '[::1]'])
+
+/** How long a stopping host gets before its tree is killed. */
+export const HOST_STOP_GRACE_MS = 5_000
+
+export function isFrameApp(root: string, exists: (path: string) => boolean = existsSync): boolean {
+  return exists(join(root, HOST_SCRIPT))
+}
+
+/** The app home the host uses: `ACRYLBLENDS_HOME` when set, else `<app>/.acrylblends` (the launcher's own rule). */
+export function frameHome(root: string, env: Record<string, string | undefined>): string {
+  const pinned = env.ACRYLBLENDS_HOME?.trim()
+  return pinned === undefined || pinned === ''
+    ? join(resolve(root), '.acrylblends')
+    : resolve(pinned)
+}
+
+/** The frame address in the host's output so far, or `undefined` while it has not printed it. */
+export function hostAddress(output: string): string | undefined {
+  return HOST_LINE.exec(output)?.[1]
+}
+
+/** A loopback `http:` address, or `undefined` for anything else: the window only ever opens a frame on this machine. */
+export function loopbackAddress(url: unknown): URL | undefined {
+  if (typeof url !== 'string') return undefined
+  try {
+    const parsed = new URL(url)
+    return parsed.protocol === 'http:' && LOOPBACK.has(parsed.hostname) ? parsed : undefined
+  } catch {
+    return undefined
+  }
+}
+
+export interface RecordDeps {
+  readonly read?: (file: string) => string
+  /** Whether something accepts a connection at the address. */
+  readonly listening?: (url: URL) => Promise<boolean>
+}
+
+const tcpListening = (url: URL, timeoutMs = 500): Promise<boolean> =>
+  new Promise((done) => {
+    const socket = connect({
+      host: url.hostname.replace(/^\[|\]$/gu, ''),
+      port: Number(url.port || 80),
+    })
+    const finish = (listening: boolean) => {
+      socket.destroy()
+      done(listening)
+    }
+    socket.setTimeout(timeoutMs)
+    socket.once('connect', () => finish(true))
+    socket.once('timeout', () => finish(false))
+    socket.once('error', () => finish(false))
+  })
+
+/**
+ * The frame that already runs for this app: the host's address record, when it names a loopback address and something listens there. A record a stopped host
+ * left behind is not a running frame.
+ */
+export async function runningFrame(
+  home: string,
+  deps: RecordDeps = {},
+): Promise<string | undefined> {
+  const read = deps.read ?? ((file: string) => readFileSync(file, 'utf8'))
+  let record: { url?: unknown }
+  try {
+    record = JSON.parse(read(join(home, 'frame-url.json'))) as { url?: unknown }
+  } catch {
+    return undefined
+  }
+  const url = loopbackAddress(record.url)
+  if (url === undefined) return undefined
+  return (await (deps.listening ?? tcpListening)(url)) ? url.href : undefined
+}
+
+/** An address as the door may show it: the frame's launch token removed (the token is the way into the frame, so it never goes to a log). */
+export function withoutToken(href: string): string {
+  try {
+    const parsed = new URL(href)
+    if (!parsed.searchParams.has('token')) return href
+    parsed.searchParams.delete('token')
+    return parsed.href
+  } catch {
+    return href
+  }
+}
+
+/**
+ * What the Settings... menu item runs in a frame window: the window event the page's root owner opens its own Settings on (`acryl-blends-frame`'s
+ * `OPEN_SETTINGS_EVENT`, and the IDE's `acryl-workspace`; keep the string in step). The same dialog as the top bar's gear, never a second one.
+ */
+export const openFrameSettings = "window.dispatchEvent(new Event('acryl:open-settings'))"
+
+/** What the window does with a navigation: stay on the frame's origin, hand the address to the system browser, or refuse it. */
+export type Navigation = 'stay' | 'external' | 'block'
+
+/**
+ * ACRYL Desktop's rule (`electron-shell-generation.ts`): only the main frame is checked, so the frame's tiles (the app's page in an iframe) navigate freely;
+ * the frame's own origin stays in the window, an `http(s)` or `mailto` address goes to the system browser, anything else is refused.
+ */
+export function navigation(target: string, origin: string, mainFrame = true): Navigation {
+  if (!mainFrame) return 'stay'
+  let parsed: URL
+  try {
+    parsed = new URL(target)
+  } catch {
+    return 'block'
+  }
+  if (parsed.origin === origin) return 'stay'
+  return parsed.protocol === 'http:' ||
+    parsed.protocol === 'https:' ||
+    parsed.protocol === 'mailto:'
+    ? 'external'
+    : 'block'
+}
+
+/** How the host is started: the npm and Node that ran `npm run desktop`, never Electron's Node (node-pty and DSH's rows are built for Node's ABI). */
+export function hostCommand(
+  env: Record<string, string | undefined>,
+  platform: NodeJS.Platform,
+): { file: string; args: string[]; shell: boolean } {
+  const node = env.npm_node_execpath
+  const npm = env.npm_execpath
+  if (node !== undefined && node !== '' && npm !== undefined && npm !== '')
+    return /\.c?js$/u.test(npm)
+      ? { file: node, args: [npm, 'run', 'dev'], shell: false }
+      : { file: npm, args: ['run', 'dev'], shell: platform === 'win32' }
+  // Started without npm (Electron run by hand): npm from the PATH, `npm.cmd` through the shell on Windows (scripts/lib/platform.mjs, npmSpawn).
+  return platform === 'win32'
+    ? { file: 'npm.cmd', args: ['run', 'dev'], shell: true }
+    : { file: 'npm', args: ['run', 'dev'], shell: false }
+}
+
+export interface FrameHost {
+  /** The frame address the host printed, or a rejection with the host's output when it ended first. */
+  readonly ready: Promise<string>
+  /** Stop the host and what it started; resolves once it has exited. */
+  stop(): Promise<void>
+}
+
+/** Start the app's frame host as `npm run dev` does, in the app folder; its output is passed through to `write`. */
+export function startFrameHost(
+  root: string,
+  env: NodeJS.ProcessEnv,
+  write: (text: string) => void,
+  platform: NodeJS.Platform = process.platform,
+): FrameHost {
+  const command = hostCommand(env, platform)
+  // The host leads its own process group on macOS and Linux, so a stop reaches npm, the host and every terminal it runs; Windows stops the tree with taskkill.
+  const child: ChildProcess = spawn(command.file, command.args, {
+    cwd: root,
+    env: { ...env, ELECTRON_RUN_AS_NODE: undefined },
+    stdio: ['ignore', 'pipe', 'pipe'],
+    shell: command.shell,
+    detached: platform !== 'win32',
+    windowsHide: true,
+  })
+  let output = ''
+  let exited = false
+  const exit = new Promise<void>((done) => {
+    child.once('exit', () => {
+      exited = true
+      done()
+    })
+    child.once('error', () => {
+      exited = true
+      done()
+    })
+  })
+  const ready = new Promise<string>((done, fail) => {
+    const take = (chunk: Buffer) => {
+      const text = chunk.toString()
+      write(text)
+      if (output.length < 200_000) output += text
+      const address = hostAddress(output)
+      if (address !== undefined) done(address)
+    }
+    child.stdout?.on('data', take)
+    child.stderr?.on('data', take)
+    void exit.then(() =>
+      fail(new Error(`the frame host ended before it served the frame:\n${output.slice(-3000)}`)),
+    )
+  })
+  const signal = (name: NodeJS.Signals) => {
+    if (child.pid === undefined) return
+    // Windows has no process groups and no SIGTERM a console process can answer: the whole tree (npm, the host, its terminals) is ended at once.
+    if (platform === 'win32') {
+      spawnSync('taskkill', ['/PID', String(child.pid), '/T', '/F'], {
+        stdio: 'ignore',
+        windowsHide: true,
+      })
+      return
+    }
+    try {
+      process.kill(-child.pid, name)
+    } catch {
+      // The group is already gone.
+    }
+  }
+  return {
+    ready,
+    async stop() {
+      if (exited) return
+      signal('SIGTERM')
+      const graceful = await Promise.race([
+        exit.then(() => true),
+        new Promise<boolean>((done) => setTimeout(() => done(false), HOST_STOP_GRACE_MS).unref()),
+      ])
+      if (!graceful) {
+        signal('SIGKILL')
+        await exit
+      }
+    },
+  }
+}

package/plugins/desktop/launch.ts

@@ -3,7 +3,7 @@
  * (Ubuntu 23.10 and later: `kernel.apparmor_restrict_unprivileged_userns=1`), Chromium's sandbox cannot start for an Electron that npm unpacked into node_modules, and Electron
  * aborts before any of our code runs. There, and only there, it starts with `--no-sandbox` and says so; everywhere else Electron starts exactly as it does with the sandbox on.
  */
-import { spawn } from 'node:child_process'
+import { type ChildProcess, spawn } from 'node:child_process'
 import { readFileSync } from 'node:fs'
 import { createRequire } from 'node:module'
 import { join } from 'node:path'
@@ -29,9 +29,45 @@ export const SANDBOX_NOTICE =
   "desktop: this Linux restricts unprivileged user namespaces (kernel.apparmor_restrict_unprivileged_userns=1), so Electron's sandbox cannot start; starting with --no-sandbox. " +
   'To keep the sandbox, give Electron an AppArmor profile that allows `userns` (the way the VS Code and Chrome packages do): see docs/framework/getting-started/desktop.md'
 
-/** The arguments for Electron: the entry file, with `--no-sandbox` first when the sandbox is blocked. */
-export function electronArgs(entry: string, blocked: boolean): string[] {
-  return blocked ? ['--no-sandbox', entry] : [entry]
+/**
+ * The arguments for Electron: the entry file, with `--no-sandbox` first when the sandbox is blocked. Chromium switches given to the script
+ * (`npm run desktop -- --remote-debugging-port=9222`) go before the entry; anything that is not a switch is dropped.
+ */
+export function electronArgs(
+  entry: string,
+  blocked: boolean,
+  extra: readonly string[] = [],
+): string[] {
+  const switches = extra.filter((arg) => /^--[a-z][a-z0-9-]*(=.*)?$/u.test(arg))
+  return [...(blocked ? ['--no-sandbox'] : []), ...switches, entry]
+}
+
+/** The signals the launcher hands to Electron: Ctrl-C, a stop, and the terminal closing. */
+export const FORWARDED_SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'] as const
+
+/**
+ * Start Electron and make it end the way it was asked to. On macOS and Linux Electron leads its own process group, so a terminal's Ctrl-C (which goes to the
+ * whole foreground group) reaches only this launcher, which hands Electron exactly one signal. Electron answers a first SIGINT, SIGTERM or SIGHUP with a
+ * graceful quit, the one that stops the frame host the window started; a second signal kills it at once, before any of that runs, and a Ctrl-C that reached
+ * both processes was two, as is one that npm passes on after the terminal sent it. Later signals are not passed on. Windows has no process groups and no such signals; there Electron starts as before. This process ends with Electron's exit code.
+ */
+export function runElectron(
+  file: string,
+  args: readonly string[],
+  platform: NodeJS.Platform = process.platform,
+): ChildProcess {
+  const child = spawn(file, args, { stdio: 'inherit', detached: platform !== 'win32' })
+  // One signal, ever: npm hands a Ctrl-C to this process a second time, and Electron's quit is bounded (DESKTOP_SHUTDOWN_TIMEOUT_MS) without another.
+  let forwarded = false
+  for (const signal of FORWARDED_SIGNALS)
+    if (platform !== 'win32' || signal !== 'SIGHUP')
+      process.on(signal, () => {
+        if (forwarded) return
+        forwarded = true
+        child.kill(signal)
+      })
+  child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)))
+  return child
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
@@ -40,9 +76,8 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
   const blocked =
     process.env.ACRYLBLENDS_DESKTOP_SANDBOX !== '1' && sandboxBlocked(process.platform)
   if (blocked) console.warn(SANDBOX_NOTICE)
-  const child = spawn(electron, electronArgs(join(import.meta.dirname, 'main.ts'), blocked), {
-    stdio: 'inherit',
-  })
-  for (const signal of ['SIGINT', 'SIGTERM'] as const) process.on(signal, () => child.kill(signal))
-  child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)))
+  runElectron(
+    electron,
+    electronArgs(join(import.meta.dirname, 'main.ts'), blocked, process.argv.slice(2)),
+  )
 }

package/plugins/desktop/main.ts

@@ -1,6 +1,8 @@
 /**
- * The desktop shell: `npm run desktop` starts the app's own server in this Electron main process and opens one window on its address. Nothing in the app
- * imports electron; every Electron call of the app is in this file and `window.ts`, so a different shell is a change here only.
+ * The desktop shell: `npm run desktop` opens the app in a window. A frame app (`scripts/ide-host.mjs`) gets the whole ACRYL frame: the window attaches to the
+ * frame host that runs for this folder, or starts it as `npm run dev` does (`frame.ts`, docs/plans/ide-host-inversion.md section 27). An app made before the frame
+ * starts its own server in this Electron main process and opens one window on its address. Nothing in the app imports electron; every Electron call of the app
+ * is in this file and `window.ts`, so a different shell is a change here only.
  *
  * Order matters: the user-data folder is set before anything else (and before the single-instance lock), so one app never shares window state, logs or the lock with
  * another app or with the real user's data.
@@ -20,10 +22,20 @@ import {
   startDoorShell,
   type WindowPort,
 } from './door-shell.ts'
+import {
+  type FrameHost,
+  frameHome,
+  isFrameApp,
+  navigation,
+  openFrameSettings,
+  runningFrame,
+  startFrameHost,
+  withoutToken,
+} from './frame.ts'
 import { hasSettings, settingsPlacement } from './menu.ts'
 import { createDesktopShutdown, installShutdownRequests } from './shutdown.ts'
 import { resolveDesktopUserDataOverride } from './user-data.ts'
-import { cascade, windowOptions } from './window.ts'
+import { cascade, windowOptions, windowSize } from './window.ts'
 
 const projectRoot = fileURLToPath(new URL('../..', import.meta.url))
 const chosen = selectInstance({ projectRoot, env: process.env })
@@ -47,6 +59,7 @@ if (!app.requestSingleInstanceLock()) {
   app.quit()
 } else {
   let running: App | undefined
+  let host: FrameHost | undefined
   let window: BrowserWindow | undefined
   let stopDoorShell: (() => void) | undefined
 
@@ -54,6 +67,8 @@ if (!app.requestSingleInstanceLock()) {
     async () => {
       stopDoorShell?.()
       await running?.stop()
+      // The frame host this window started (never one it attached to) goes with the window, with every terminal it runs.
+      await host?.stop()
     },
     (code) => {
       app.exit(code)
@@ -77,9 +92,33 @@ if (!app.requestSingleInstanceLock()) {
     // The hook above is registered before the app's modules are loaded, so the app may have .tsx pages: they are loaded here, not as a static import.
     // A dev server is already running from this folder (`npm run dev`): the door allows one process per folder, so the window opens on that server instead of starting a second one,
     // and closing the window leaves it running.
-    const attached = await runningApp(projectRoot)
+    const frame = isFrameApp(projectRoot)
+    const attached = frame ? undefined : await runningApp(projectRoot)
     let url: string
-    if (attached !== undefined) {
+    if (frame) {
+      // The frame that already runs for this folder (`npm run dev`, or another window's host), else a host of this window's own.
+      const runningAddress = await runningFrame(frameHome(projectRoot, process.env))
+      if (runningAddress !== undefined) {
+        console.log(
+          `desktop: attached to the frame already running from this folder at ${new URL(runningAddress).origin} (it keeps running when the window closes)`,
+        )
+        url = runningAddress
+      } else {
+        host = startFrameHost(projectRoot, process.env, (text) => {
+          process.stdout.write(text)
+        })
+        try {
+          url = await host.ready
+        } catch (cause) {
+          console.error(`desktop: ${cause instanceof Error ? cause.message : String(cause)}`)
+          await shutdown.request(1)
+          return
+        }
+        console.log(
+          `desktop: the frame host serves ${new URL(url).origin}; closing the window stops it`,
+        )
+      }
+    } else if (attached !== undefined) {
       console.log(
         `desktop: attached to the app already running from this folder at ${attached.url} (its server keeps running when the window closes)`,
       )
@@ -90,14 +129,23 @@ if (!app.requestSingleInstanceLock()) {
       url = running.url
     }
     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 a window opens: the frame's address (with its token) for a frame app, else a path of the app (`acrylblends.desktopPath`, else the root). */
+    const addressOf = (path: string | undefined): string =>
+      frame && path === undefined ? url : new URL(path ?? startPath(), url).href
+    /** One window on an address of the app. Navigation follows `navigation` in frame.ts. 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 => {
+    const createWindow = (path: string | undefined): BrowserWindow => {
       // 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 work = (
+        beside === undefined
+          ? screen.getPrimaryDisplay()
+          : screen.getDisplayMatching(beside.getBounds())
+      ).workArea
+      const size = windowSize(work)
       const where = (() => {
         if (beside === undefined) return {}
         const bounds = beside.getBounds()
@@ -106,44 +154,49 @@ if (!app.requestSingleInstanceLock()) {
           .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,
-        )
+        return cascade(bounds, work, size, taken)
       })()
-      const created = new BrowserWindow(windowOptions({ title: chosen.name, ...where }))
-      openedOn.set(created.id, path)
+      const created = new BrowserWindow(windowOptions({ title: chosen.name, ...size, ...where }))
+      const address = addressOf(path)
+      openedOn.set(created.id, new URL(address).pathname)
       created.webContents.setUserAgent(
         `${created.webContents.getUserAgent()} AcrylWindow/${String(created.id)}`,
       )
       created.once('ready-to-show', () => created.show())
-      created.webContents.setWindowOpenHandler(({ url }) => {
-        void shell.openExternal(url)
+      // A new window of the page never opens inside the app: an http(s) or mailto address goes to the system browser, anything else nowhere.
+      created.webContents.setWindowOpenHandler(({ url: target }) => {
+        if (navigation(target, '') === 'external') void shell.openExternal(target)
         return { action: 'deny' }
       })
-      created.webContents.on('will-navigate', (event, url) => {
-        if (new URL(url).origin === origin) return
+      // Only the main frame is checked, so the frame's tiles (the app's page in an iframe) navigate freely; the window itself stays on the app's origin.
+      created.webContents.on('will-frame-navigate', (event) => {
+        const decision = navigation(event.url, origin, event.isMainFrame)
+        if (decision === 'stay') return
         event.preventDefault()
-        void shell.openExternal(url)
+        if (decision === 'external') void shell.openExternal(event.url)
+      })
+      created.webContents.on('will-redirect', (event, target, _inPlace, isMainFrame) => {
+        if (navigation(target, origin, isMainFrame) !== 'stay') event.preventDefault()
       })
-      created.loadURL(new URL(path, url).href).catch((cause: unknown) => {
+      created.loadURL(address).catch((cause: unknown) => {
         console.warn(
-          `desktop: the window could not load ${path}: ${cause instanceof Error ? cause.message : String(cause)}`,
+          `desktop: the window could not load ${new URL(address).pathname}: ${cause instanceof Error ? cause.message : String(cause)}`,
         )
       })
       return created
     }
-    window = createWindow(startPath())
+    window = createWindow(frame ? undefined : startPath())
     // The door (development) reaches the windows and the menu through this port: `acryl window list`, `acryl menu click`.
     const live = (): BrowserWindow[] =>
       BrowserWindow.getAllWindows().filter((candidate) => !candidate.isDestroyed())
     const port = (candidate: BrowserWindow): WindowPort => ({
       id: candidate.id,
       getTitle: () => candidate.getTitle(),
+      // Without the frame's launch token: the door prints this address and its audit keeps it.
       getURL: () =>
-        candidate.webContents.getURL() || new URL(openedOn.get(candidate.id) ?? '/', url).href,
+        withoutToken(
+          candidate.webContents.getURL() || new URL(openedOn.get(candidate.id) ?? '/', url).href,
+        ),
       isFocused: () => candidate.isFocused(),
       isMinimized: () => candidate.isMinimized(),
       getSize: () => candidate.getSize(),
@@ -169,17 +222,20 @@ if (!app.requestSingleInstanceLock()) {
     })
     const desktop: DesktopPort = {
       windows: () => live().map(port),
-      open: (path) => port(createWindow(path ?? startPath())),
+      open: (path) => port(createWindow(path ?? (frame ? undefined : 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,
-    )
+    // A frame window's item opens the frame's own Settings (the dialog the left panel's button opens), in the window that has focus.
+    const settingsServed = frame
+      ? true
+      : 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)
@@ -188,6 +244,18 @@ if (!app.requestSingleInstanceLock()) {
     if (menu !== null && placement !== undefined) {
       const target = menu.items[placement.menu]?.submenu
       const openSettings = (): void => {
+        if (frame) {
+          const target = BrowserWindow.getFocusedWindow() ?? live()[0]
+          if (target === undefined) return
+          if (target.isMinimized()) target.restore()
+          target.focus()
+          target.webContents.executeJavaScript(openFrameSettings).catch((cause: unknown) => {
+            console.warn(
+              `desktop: Settings could not be opened in the frame: ${cause instanceof Error ? cause.message : String(cause)}`,
+            )
+          })
+          return
+        }
         const shown = live().find(
           (candidate) =>
             new URL(candidate.webContents.getURL() || 'about:blank', url).pathname === '/settings',

package/plugins/desktop/window.ts

@@ -19,6 +19,23 @@ export interface Rect {
 /** How far each new window sits from the one it was opened from. */
 export const CASCADE_STEP = 32
 
+/** A window's size when nothing asks for another, and the smallest it may be. */
+export const WINDOW_SIZE = { width: 1100, height: 760 } as const
+export const WINDOW_MIN_SIZE = { width: 480, height: 360 } as const
+
+/**
+ * The size of a new window on a work area: the usual size, made smaller on a screen where it would not leave room for a few cascade steps, never below the
+ * smallest size. macOS moves a window that runs past the screen's edge back onto it, so on a small screen (CI's 1024x768) a window of the usual size that
+ * `cascade` placed a step from another lands exactly on it; a window of this size fits at its place.
+ */
+export function windowSize(work: Rect): { width: number; height: number } {
+  const room = CASCADE_STEP * 3
+  return {
+    width: Math.max(WINDOW_MIN_SIZE.width, Math.min(WINDOW_SIZE.width, work.width - room)),
+    height: Math.max(WINDOW_MIN_SIZE.height, Math.min(WINDOW_SIZE.height, work.height - room)),
+  }
+}
+
 /**
  * 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
@@ -73,10 +90,10 @@ export interface WindowOptions {
 export function windowOptions(spec: WindowSpec): WindowOptions {
   return {
     title: spec.title,
-    width: spec.width ?? 1100,
-    height: spec.height ?? 760,
-    minWidth: 480,
-    minHeight: 360,
+    width: spec.width ?? WINDOW_SIZE.width,
+    height: spec.height ?? WINDOW_SIZE.height,
+    minWidth: WINDOW_MIN_SIZE.width,
+    minHeight: WINDOW_MIN_SIZE.height,
     ...(spec.x === undefined || spec.y === undefined ? {} : { x: spec.x, y: spec.y }),
     show: false,
     webPreferences: {

package/plugins/driver-pty/client/terminal.ts

@@ -4,7 +4,7 @@ import { FitAddon } from './vendor/addon-fit.mjs'
 import { Terminal } from './vendor/xterm.mjs'
 import css from './vendor/xterm-css.mjs'
 
-const PREFIX = '/api/driver-pty'
+let PREFIX = '/api/driver-pty'
 const REMEMBERED = 'driver-pty-session'
 
 export interface TerminalView {
@@ -21,6 +21,8 @@ interface Options {
   token: string
   /** The terminal driver's name (`pty:claude`). */
   driver: string
+  /** The URL prefix the driver's endpoints live under (`/api/driver-pty`, or the app's mount followed by it). */
+  prefix: string
   /** Called with a line of status for the panel to show (`The terminal ended (exit 0).`). */
   status(text: string): void
   /** A plugin was installed or removed while the terminal was open. */
@@ -57,6 +59,7 @@ async function* frames(response: Response): AsyncGenerator<Frame> {
 
 export async function openTerminal(options: Options): Promise<TerminalView> {
   const { container, token, driver, status, onChange } = options
+  PREFIX = options.prefix
   const headers = { 'content-type': 'application/json', 'x-agent-panel-token': token }
   const call = (path: string, body: unknown = {}): Promise<Response> =>
     fetch(`${PREFIX}${path}`, { method: 'POST', headers, body: JSON.stringify(body) })