acrylblends 1.0.8 → 1.0.10

package/docs/framework/guides/bring-your-own-tool.md

@@ -119,6 +119,8 @@ export async function apply(ctx: Context, config: { path?: string } = {}): Promi
 
 The suite is the contract: it runs the same cases against every provider. A test gives it a fresh store for each case and a way to reopen the same storage.
 
+The suite imports `vitest` from your project, where `--suite` put it as a dev dependency. The same suite is in the package as `acrylblends/kv/conformance` (and `acrylblends/db/conformance`), and there it runs on the vitest your test hands it: `import * as vitest from 'vitest'` and `describeKvConformance('my-provider', open, vitest)`. The package does not declare `vitest` as a peer, so a production install of an app that uses `acrylblends` carries no vitest, vite or native build tools (1.0.10 and later; before that, `pnpm deploy --prod` pulled them in).
+
 ```ts no-check
 // test/kv-lowdb.spec.ts
 import { mkdir, mkdtemp } from 'node:fs/promises'

package/lib/{audit-BD8_2pkh.d.ts → audit-Dw-siYTp.d.ts}

@@ -9,6 +9,11 @@ interface PageStream {
 interface ChannelOptions {
   /** How long a page has to acknowledge a read-only call (`look`, `wait`) before the next page is tried. */
   readonly ackMs?: number;
+  /**
+   * How long a read-only call waits for a page to register when there is none, or when every page was silent and a new one may be on its way (a page that is moving to another
+   * address registers again a moment later). 0 (the default) fails at once.
+   */
+  readonly attachWaitMs?: number;
 }
 /**
  * The pages and who drives which. One page answers a call, chosen the same way every time: the page the Host just sent somewhere (it comes back as a new page, `prefer`), else the
@@ -16,6 +21,7 @@ interface ChannelOptions {
  */
 declare class UiChannel {
   private readonly ackMs;
+  private readonly attachWaitMs;
   /** The page the Host sent to a new place and that came back: it keeps being driven until the person focuses another page. */
   private preferred;
   constructor(options?: ChannelOptions);
@@ -52,7 +58,7 @@ declare class UiChannel {
     signal?: AbortSignal;
     timeoutMs?: number;
     window?: number;
-  }): Promise<UiResult>;
+  }, retried?: boolean): Promise<UiResult>;
   private callOne;
   /**
    * A promise for the next time a page connects (a page that reloaded or moved opens a new stream). Ask for it BEFORE the call that makes the page leave, or a fast page is missed.

package/lib/cordis/door.d.ts

@@ -1,5 +1,5 @@
 import { f as UiActionResult, y as UiSnapshot } from "../protocol-a2aqrp2X.js";
-import { i as UiChannel, r as PageStream, t as AuditLog } from "../audit-BD8_2pkh.js";
+import { i as UiChannel, r as PageStream, t as AuditLog } from "../audit-Dw-siYTp.js";
 import { Context } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
 
@@ -37,6 +37,9 @@ interface ShellWindow {
   readonly focused: boolean;
   readonly width: number;
   readonly height: number;
+  /** Where the window's top left corner is on the screen (so two windows on top of each other can be told). */
+  readonly x?: number;
+  readonly y?: number;
 }
 interface ShellMenuItem {
   /** Labels from the top of the menu, joined with `>`: `File>New Note`. */

package/lib/cordis/door.js

@@ -4,7 +4,7 @@ import { r as loopbackAuthority } from "../loopback-only-BbasoF7R.js";
 import "../helpers-BEjcdbgw.js";
 import { n as clientModules } from "../client-modules-drj4mjhj.js";
 import { a as MAX_WAIT_MS, d as parseChannelToHost, l as UiControlError, p as parseUiRequest, r as MAX_SNAPSHOT_NODES, u as WINDOW_ID } from "../protocol-CQ_if7Dg.js";
-import { a as INVALID_JSON, c as operatorOnly, d as AuditLog, f as auditPath, i as DOOR_PREFIX, l as privateApi, o as error, p as UiChannel, r as pageChannelRoutes, s as jsonBody, t as renderSnapshot, u as readJson } from "../snapshot-text-m13Pk-AI.js";
+import { a as INVALID_JSON, c as operatorOnly, d as AuditLog, f as auditPath, i as DOOR_PREFIX, l as privateApi, o as error, p as UiChannel, r as pageChannelRoutes, s as jsonBody, t as renderSnapshot, u as readJson } from "../snapshot-text-BfEbEOjA.js";
 import "../src-BTBm4OPD.js";
 import "../middleware-BfG_fp8P.js";
 import { isAbsolute, join, relative, resolve } from "node:path";
@@ -600,7 +600,7 @@ var DoorError = class extends Error {
 };
 /** A shell answer as text an agent reads: windows and menu items one to a line. */
 function renderShell(result) {
-	if ("windows" in result) return result.windows.length === 0 ? "no windows are open" : result.windows.map((window) => `${String(window.id)}  ${JSON.stringify(window.title)}  ${window.path}  ${String(window.width)}x${String(window.height)}${window.focused ? "  focused" : ""}`).join("\n");
+	if ("windows" in result) return result.windows.length === 0 ? "no windows are open" : result.windows.map((window) => `${String(window.id)}  ${JSON.stringify(window.title)}  ${window.path}  ${String(window.width)}x${String(window.height)}${window.x === void 0 || window.y === void 0 ? "" : `@${String(window.x)},${String(window.y)}`}${window.focused ? "  focused" : ""}`).join("\n");
 	if ("items" in result) return result.items.length === 0 ? "the app has no menu" : result.items.map((item) => `${item.path}${item.enabled ? "" : "  (disabled)"}${item.ends === true ? "  (ends the app; needs force)" : ""}`).join("\n");
 	return result.detail;
 }
@@ -1380,7 +1380,7 @@ function apply(ctx, rawConfig = {}) {
 		ctx.logger?.error?.(`acryl-door: failed to ${operation}: ${cause instanceof Error ? cause.message : String(cause)}`);
 	};
 	const secret = newSecret();
-	const channel = new UiChannel();
+	const channel = new UiChannel({ attachWaitMs: 2e3 });
 	const shell = new ShellChannel();
 	const door = new Door({
 		channel,

package/lib/db/conformance.d.ts

@@ -1,4 +1,5 @@
 import { t as Db } from "../database-DBHdwefi.js";
+import { t as VitestApi } from "../vitest-binding-CctNu3jT.js";
 
 //#region ../../plugins/acryl-db/src/conformance.d.ts
 /** A fresh, empty database from the provider under test, and how to close it. */
@@ -6,6 +7,9 @@ interface DbUnderTest {
   readonly db: Db;
   close(): Promise<void>;
 }
-declare function describeDbConformance(provider: string, open: () => Promise<DbUnderTest>): void;
+declare function describeDbConformance$1(provider: string, open: () => Promise<DbUnderTest>): void;
 //#endregion
-export { DbUnderTest, describeDbConformance };
+//#region src/db-conformance.d.ts
+declare function describeDbConformance(provider: string, open: Parameters<typeof describeDbConformance$1>[1], vitest: VitestApi): void;
+//#endregion
+export { type DbUnderTest, type VitestApi, describeDbConformance };

package/lib/db/conformance.js

@@ -1,8 +1,8 @@
 import { i as applyMigrations, n as MIGRATIONS_TABLE, r as readMigrationFiles } from "../src-MWcsMS8i.js";
+import { a as it, i as expect, n as bind, r as describe, t as afterEach } from "../vitest-binding-CrH7rKg2.js";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
-import { afterEach, describe, expect, it } from "vitest";
 //#region ../../plugins/acryl-db/src/conformance.ts
 /**
 * The `db` conformance suite: what every provider of the port must do, as Vitest tests. A provider passes it to be accepted
@@ -24,7 +24,7 @@ function gate() {
 		open
 	};
 }
-function describeDbConformance(provider, open) {
+function describeDbConformance$1(provider, open) {
 	describe(`db conformance: ${provider}`, () => {
 		const opened = [];
 		const fresh = async () => {
@@ -264,4 +264,16 @@ function describeDbConformance(provider, open) {
 	});
 }
 //#endregion
+//#region src/db-conformance.ts
+/**
+* `acrylblends/db/conformance`: the `db` conformance suite a provider of the port passes. It runs on the vitest your test hands it, so the package declares no vitest:
+*
+*   import * as vitest from 'vitest'
+*   describeDbConformance('my-provider', open, vitest)
+*/
+function describeDbConformance(provider, open, vitest) {
+	bind(vitest);
+	describeDbConformance$1(provider, open);
+}
+//#endregion
 export { describeDbConformance };

package/lib/door/host.d.ts

@@ -1,6 +1,6 @@
 import { t as Acryl } from "../app-D8riatvv.js";
 import { n as AuditEntry, y as UiSnapshot } from "../protocol-a2aqrp2X.js";
-import { i as UiChannel, n as auditPath, r as PageStream, t as AuditLog } from "../audit-BD8_2pkh.js";
+import { i as UiChannel, n as auditPath, r as PageStream, t as AuditLog } from "../audit-Dw-siYTp.js";
 
 //#region ../../plugins/acryl-door/src/host/page-routes.d.ts
 /** How often the Host writes a `ping`; the page gives up on a stream that is silent for three of these. */

package/lib/door/host.js

@@ -1,2 +1,2 @@
-import { d as AuditLog, f as auditPath, n as HEARTBEAT_MS, p as UiChannel, r as pageChannelRoutes, t as renderSnapshot } from "../snapshot-text-m13Pk-AI.js";
+import { d as AuditLog, f as auditPath, n as HEARTBEAT_MS, p as UiChannel, r as pageChannelRoutes, t as renderSnapshot } from "../snapshot-text-BfEbEOjA.js";
 export { AuditLog, HEARTBEAT_MS, UiChannel, auditPath, pageChannelRoutes, renderSnapshot };

package/lib/kv/conformance.d.ts

@@ -1,3 +1,4 @@
+import { t as VitestApi } from "../vitest-binding-CctNu3jT.js";
 import { n as Kv } from "../kv-9f-AlRKN.js";
 
 //#region ../../plugins/acryl-kv/src/conformance.d.ts
@@ -8,6 +9,9 @@ interface KvUnderTest {
   /** Close this store (if it is still open) and open the same storage again, to prove what was written is durable. */
   reopen(): Promise<KvUnderTest>;
 }
-declare function describeKvConformance(provider: string, open: () => Promise<KvUnderTest>): void;
+declare function describeKvConformance$1(provider: string, open: () => Promise<KvUnderTest>): void;
 //#endregion
-export { KvUnderTest, describeKvConformance };
+//#region src/kv-conformance.d.ts
+declare function describeKvConformance(provider: string, open: Parameters<typeof describeKvConformance$1>[1], vitest: VitestApi): void;
+//#endregion
+export { type KvUnderTest, type VitestApi, describeKvConformance };

package/lib/kv/conformance.js

@@ -1,10 +1,10 @@
-import { afterEach, describe, expect, it } from "vitest";
+import { a as it, i as expect, n as bind, r as describe, t as afterEach } from "../vitest-binding-CrH7rKg2.js";
 //#region ../../plugins/acryl-kv/src/conformance.ts
 /**
 * The `kv` conformance suite: what every provider of the port must do, as Vitest tests. A provider passes it to be accepted
 * (`describeKvConformance('acryl-kv-json', open)` in its own tests), so the same cases run on a file and on SQL.
 */
-function describeKvConformance(provider, open) {
+function describeKvConformance$1(provider, open) {
 	describe(`kv conformance: ${provider}`, () => {
 		const opened = [];
 		const track = (subject) => {
@@ -298,4 +298,16 @@ function describeKvConformance(provider, open) {
 	});
 }
 //#endregion
+//#region src/kv-conformance.ts
+/**
+* `acrylblends/kv/conformance`: the `kv` conformance suite a provider of the port passes. It runs on the vitest your test hands it, so the package declares no vitest:
+*
+*   import * as vitest from 'vitest'
+*   describeKvConformance('my-provider', open, vitest)
+*/
+function describeKvConformance(provider, open, vitest) {
+	bind(vitest);
+	describeKvConformance$1(provider, open);
+}
+//#endregion
 export { describeKvConformance };

package/lib/{snapshot-text-m13Pk-AI.js → snapshot-text-BfEbEOjA.js}

@@ -34,10 +34,12 @@ const DEFAULT_ACK_MS = 3e3;
 */
 var UiChannel = class {
 	ackMs;
+	attachWaitMs;
 	/** The page the Host sent to a new place and that came back: it keeps being driven until the person focuses another page. */
 	preferred;
 	constructor(options = {}) {
 		this.ackMs = options.ackMs ?? DEFAULT_ACK_MS;
+		this.attachWaitMs = options.attachWaitMs ?? 0;
 	}
 	connections = /* @__PURE__ */ new Map();
 	pending = /* @__PURE__ */ new Map();
@@ -114,8 +116,10 @@ var UiChannel = class {
 	* until it speaks; a call that changes the page is never sent to a second page, because the first might still run it.
 	* @throws UiControlError `no-window`, `timeout`, `aborted`, `unloaded`, `disconnected`, or whatever the page refused with.
 	*/
-	async call(request, options = {}) {
+	async call(request, options = {}, retried = false) {
 		if (this.closed) throw new UiControlError("unloaded", "the door was unloaded");
+		const readOnlyCall = request.op === "snapshot" || request.op === "wait";
+		if (readOnlyCall && this.attachWaitMs > 0 && this.connections.size === 0) await this.expectNewPage(this.attachWaitMs);
 		const ordered = this.ordered();
 		const candidates = options.window === void 0 ? ordered : ordered.filter((connection) => connection.shellWindow === options.window);
 		if (candidates.length === 0 && options.window !== void 0) {
@@ -124,13 +128,21 @@ var UiChannel = class {
 		}
 		if (candidates.length === 0) throw new UiControlError("no-window", "no page of the app is open to control");
 		if (options.signal?.aborted === true) throw new UiControlError("aborted", "the call was cancelled");
-		const readOnly = request.op === "snapshot" || request.op === "wait";
-		for (const target of candidates) try {
-			return await this.callOne(target, request, options, readOnly);
-		} catch (cause) {
-			if (!(cause instanceof Silent)) throw cause;
+		const readOnly = readOnlyCall;
+		const tried = /* @__PURE__ */ new Set();
+		for (const target of candidates) {
+			tried.add(target.windowId);
+			try {
+				return await this.callOne(target, request, options, readOnly);
+			} catch (cause) {
+				if (!(cause instanceof Silent)) throw cause;
+			}
+		}
+		if (readOnly && !retried && this.attachWaitMs > 0 && options.window === void 0) {
+			const fresh = await this.expectNewPage(this.attachWaitMs);
+			if (fresh !== void 0 && !tried.has(fresh)) return await this.call(request, options, true);
 		}
-		throw new UiControlError("timeout", `no page of the app answered within ${String(Math.round(this.ackMs / 1e3))} s: the app's pages are open but none responded (a tab in the background, or a page that is still loading). Bring the app's tab to the front, or navigate it, then look again`);
+		throw new UiControlError("timeout", `no page of the app answered within ${String(Math.round(this.ackMs / 1e3))} s: the app's pages are open but none responded. Likely causes: a tab in the background, a page that is still loading after a navigation (look again), a page busy running a long script, or a page that holds the browser's six connections with event streams of its own (a page should keep to two). Bring the app's tab to the front, or navigate it, then look again`);
 	}
 	callOne(target, request, options, failOver) {
 		const signal = options.signal;

package/lib/vitest-binding-CctNu3jT.d.ts

@@ -0,0 +1,15 @@
+//#region src/vitest-binding.d.ts
+/**
+ * The conformance suites (`acrylblends/db/conformance`, `acrylblends/kv/conformance`) run on the test runner's own vitest, which the test hands them. In the package build their
+ * `import ... from 'vitest'` is pointed here (`tsdown.config.ts`), so the package imports no vitest and does not declare one: it cannot put vitest, vite, rolldown or lightningcss into
+ * a production install, and the suite can never see a second copy of vitest that is not the one running the test.
+ */
+/** The four functions of vitest the suites use; a test passes `import * as vitest from 'vitest'`. */
+interface VitestApi {
+  readonly afterEach: (...args: never[]) => unknown;
+  readonly describe: (...args: never[]) => unknown;
+  readonly expect: (...args: never[]) => unknown;
+  readonly it: (...args: never[]) => unknown;
+}
+//#endregion
+export { VitestApi as t };

package/lib/vitest-binding-CrH7rKg2.js

@@ -0,0 +1,17 @@
+//#region src/vitest-binding.ts
+let bound;
+/** Use `api` for the suites that run next. They register their cases synchronously, so one call per suite is enough. */
+function bind(api) {
+	if (api === void 0 || typeof api.describe !== "function" || typeof api.it !== "function" || typeof api.expect !== "function" || typeof api.afterEach !== "function") throw new Error("the conformance suite needs the vitest your tests run on: pass it as the third argument, `import * as vitest from 'vitest'` then `describeKvConformance(name, open, vitest)`");
+	bound = api;
+}
+const use = () => {
+	if (bound === void 0) throw new Error("the conformance suite ran before it was given vitest");
+	return bound;
+};
+const afterEach = (...args) => Reflect.apply(use().afterEach, void 0, args);
+const describe = (...args) => Reflect.apply(use().describe, void 0, args);
+const expect = (...args) => Reflect.apply(use().expect, void 0, args);
+const it = (...args) => Reflect.apply(use().it, void 0, args);
+//#endregion
+export { it as a, expect as i, bind as n, describe as r, afterEach as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acrylblends",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "description": "The Acryl web framework (import { Acryl } from \"acrylblends\") and the acrylblends command that scaffolds Cordis apps.",
   "license": "MIT",
   "type": "module",
@@ -436,7 +436,6 @@
     "@deepseek-ai/cordis": "^4.0.2",
     "@deepseek-ai/schemastery": "~3.18.4",
     "react": ">=18",
-    "vitest": ">=3",
     "ws": ">=8"
   },
   "peerDependenciesMeta": {
@@ -449,9 +448,6 @@
     "react": {
       "optional": true
     },
-    "vitest": {
-      "optional": true
-    },
     "ws": {
       "optional": true
     }

package/plugins/acryl-door/src/host/channel.ts

@@ -57,6 +57,11 @@ const DEFAULT_ACK_MS = 3000
 export interface ChannelOptions {
   /** How long a page has to acknowledge a read-only call (`look`, `wait`) before the next page is tried. */
   readonly ackMs?: number
+  /**
+   * How long a read-only call waits for a page to register when there is none, or when every page was silent and a new one may be on its way (a page that is moving to another
+   * address registers again a moment later). 0 (the default) fails at once.
+   */
+  readonly attachWaitMs?: number
 }
 
 /**
@@ -65,11 +70,13 @@ export interface ChannelOptions {
  */
 export class UiChannel {
   private readonly ackMs: number
+  private readonly attachWaitMs: number
   /** The page the Host sent to a new place and that came back: it keeps being driven until the person focuses another page. */
   private preferred: string | undefined
 
   constructor(options: ChannelOptions = {}) {
     this.ackMs = options.ackMs ?? DEFAULT_ACK_MS
+    this.attachWaitMs = options.attachWaitMs ?? 0
   }
 
   private readonly connections = new Map<string, Connection>()
@@ -143,8 +150,11 @@ export class UiChannel {
    * until it speaks; a call that changes the page is never sent to a second page, because the first might still run it.
    * @throws UiControlError `no-window`, `timeout`, `aborted`, `unloaded`, `disconnected`, or whatever the page refused with.
    */
-  async call(request: UiRequest, options: { signal?: AbortSignal; timeoutMs?: number; window?: number } = {}): Promise<UiResult> {
+  async call(request: UiRequest, options: { signal?: AbortSignal; timeoutMs?: number; window?: number } = {}, retried = false): Promise<UiResult> {
     if (this.closed) throw new UiControlError('unloaded', 'the door was unloaded')
+    const readOnlyCall = request.op === 'snapshot' || request.op === 'wait'
+    // A page that is moving to another address registers again a moment later: a read-only call right after a navigate or reload waits for it, rather than failing.
+    if (readOnlyCall && this.attachWaitMs > 0 && this.connections.size === 0) await this.expectNewPage(this.attachWaitMs)
     const ordered = this.ordered()
     // `window` is the number `window list` prints: that desktop window's page, not the one used last.
     const candidates = options.window === undefined ? ordered : ordered.filter(connection => connection.shellWindow === options.window)
@@ -154,15 +164,22 @@ export class UiChannel {
     }
     if (candidates.length === 0) throw new UiControlError('no-window', 'no page of the app is open to control')
     if (options.signal?.aborted === true) throw new UiControlError('aborted', 'the call was cancelled')
-    const readOnly = request.op === 'snapshot' || request.op === 'wait'
+    const readOnly = readOnlyCall
+    const tried = new Set<string>()
     for (const target of candidates) {
+      tried.add(target.windowId)
       try {
         return await this.callOne(target, request, options, readOnly)
       } catch (cause) {
         if (!(cause instanceof Silent)) throw cause
       }
     }
-    throw new UiControlError('timeout', `no page of the app answered within ${String(Math.round(this.ackMs / 1000))} s: the app's pages are open but none responded (a tab in the background, or a page that is still loading). Bring the app's tab to the front, or navigate it, then look again`)
+    // Every page was silent. A page that registered meanwhile (the one that was moving) gets the call once.
+    if (readOnly && !retried && this.attachWaitMs > 0 && options.window === undefined) {
+      const fresh = await this.expectNewPage(this.attachWaitMs)
+      if (fresh !== undefined && !tried.has(fresh)) return await this.call(request, options, true)
+    }
+    throw new UiControlError('timeout', `no page of the app answered within ${String(Math.round(this.ackMs / 1000))} s: the app's pages are open but none responded. Likely causes: a tab in the background, a page that is still loading after a navigation (look again), a page busy running a long script, or a page that holds the browser's six connections with event streams of its own (a page should keep to two). Bring the app's tab to the front, or navigate it, then look again`)
   }
 
   private callOne(target: Connection, request: UiRequest, options: { signal?: AbortSignal; timeoutMs?: number }, failOver: boolean): Promise<UiResult> {

package/plugins/acryl-door/src/host/door.ts

@@ -71,7 +71,7 @@ function renderShell(result: ShellResult): string {
   if ('windows' in result) {
     return result.windows.length === 0
       ? 'no windows are open'
-      : result.windows.map(window => `${String(window.id)}  ${JSON.stringify(window.title)}  ${window.path}  ${String(window.width)}x${String(window.height)}${window.focused ? '  focused' : ''}`).join('\n')
+      : result.windows.map(window => `${String(window.id)}  ${JSON.stringify(window.title)}  ${window.path}  ${String(window.width)}x${String(window.height)}${window.x === undefined || window.y === undefined ? '' : `@${String(window.x)},${String(window.y)}`}${window.focused ? '  focused' : ''}`).join('\n')
   }
   if ('items' in result) return result.items.length === 0 ? 'the app has no menu' : result.items.map(item => `${item.path}${item.enabled ? '' : '  (disabled)'}${item.ends === true ? '  (ends the app; needs force)' : ''}`).join('\n')
   return result.detail

package/plugins/acryl-door/src/index.ts

@@ -115,7 +115,8 @@ export function apply(ctx: Context, rawConfig: Config = {}): void {
     ctx.logger?.error?.(`acryl-door: failed to ${operation}: ${cause instanceof Error ? cause.message : String(cause)}`)
   }
   const secret = newSecret()
-  const channel = new UiChannel()
+  // A look right after a navigate or reload waits up to two seconds for the page that is moving to register again, and a read-only call that no page acknowledged gives a page that just registered one more try.
+  const channel = new UiChannel({ attachWaitMs: 2000 })
   const shell = new ShellChannel()
   const audit = new AuditLog(auditPath(stateDir(app.root)))
   const door = new Door({

package/plugins/acryl-door/src/shell/protocol.ts

@@ -27,6 +27,9 @@ export interface ShellWindow {
   readonly focused: boolean
   readonly width: number
   readonly height: number
+  /** Where the window's top left corner is on the screen (so two windows on top of each other can be told). */
+  readonly x?: number
+  readonly y?: number
 }
 
 export interface ShellMenuItem {

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

@@ -316,25 +316,38 @@ async function start(): Promise<void> {
    */
   const watch = async (source: RunSource, own: boolean): Promise<void> => {
     let live = true
-    following = true
-    send.disabled = true
-    stop.disabled = false
     let changed = false
     let answer: HTMLElement | undefined
     let answered = ''
-    // A coding agent started headless says little until it is done, so the panel says it is working, and for how long.
-    const started = Date.now()
-    const working = line('', 'working')
+    // A coding agent started headless says little until it is done, so the panel says it is working, and for how long (from when the run began, not from when this page loaded).
+    let started = Date.now()
+    let working: HTMLElement | undefined
+    let timer: ReturnType<typeof setInterval> | undefined
     const tick = (): void => {
-      const seconds = Math.floor((Date.now() - started) / 1000)
+      if (working === undefined) return
+      const seconds = Math.max(0, Math.floor((Date.now() - started) / 1000))
       working.textContent = `Working... ${String(Math.floor(seconds / 60))}:${String(seconds % 60).padStart(2, '0')}`
       log.append(working)
     }
-    tick()
-    const timer = setInterval(tick, 1000)
+    // The panel is busy once there is a run to show. A page that just loaded asks the server for the latest run first, and "there is none" must not make a message typed in that moment
+    // wait or vanish, so a run that is only being looked for does not count (it begins at its first event).
+    const begin = (): void => {
+      if (working !== undefined) return
+      following = true
+      send.disabled = true
+      stop.disabled = false
+      working = line('', 'working')
+      tick()
+      timer = setInterval(tick, 1000)
+    }
+    if (own) begin()
     try {
       for await (const { event, data } of source.events) {
+        if (event === 'idle') continue
+        begin()
         if (event === 'run') {
+          if (typeof data.startedAt === 'number') started = data.startedAt
+          tick()
           live = data.ended !== true
           if (!own) {
             if (typeof data.message === 'string') line(data.message, 'me')
@@ -365,11 +378,13 @@ async function start(): Promise<void> {
     } catch (error) {
       line(`The request failed: ${error instanceof Error ? error.message : String(error)}`, 'err')
     } finally {
-      clearInterval(timer)
-      working.remove()
-      following = false
-      send.disabled = false
-      stop.disabled = true
+      if (timer !== undefined) clearInterval(timer)
+      if (working !== undefined) {
+        working.remove()
+        following = false
+        send.disabled = false
+        stop.disabled = true
+      }
     }
     // A plugin was installed or removed while this page watched: the new feature is served by the running app, so the page only needs to be loaded again (unless something is being typed).
     // A run that ended before this page loaded was already shown after its reload, and does not reload it again.

package/plugins/agent-panel/index.ts

@@ -175,6 +175,7 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
     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
@@ -189,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(),
@@ -241,6 +243,7 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
           id: run.id,
           driver: run.driver,
           message: run.message,
+          startedAt: run.startedAt,
           ended: run.ended,
           endedAt: run.endedAt ?? null,
         },

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

@@ -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 =
@@ -99,12 +101,20 @@ if (!app.requestSingleInstanceLock()) {
       const where = (() => {
         if (beside === undefined) return {}
         const bounds = beside.getBounds()
-        return cascade(bounds, screen.getDisplayMatching(bounds).workArea, {
-          width: 1100,
-          height: 760,
-        })
+        // 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 }))
+      openedOn.set(created.id, path)
       created.webContents.setUserAgent(
         `${created.webContents.getUserAgent()} AcrylWindow/${String(created.id)}`,
       )
@@ -132,10 +142,12 @@ 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(),
+      getPosition: () => candidate.getPosition(),
       restore: () => candidate.restore(),
       focus: () => candidate.focus(),
       close: () => candidate.close(),

package/plugins/desktop/window.ts

@@ -20,19 +20,33 @@ export interface Rect {
 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).
+ * 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 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 }
+  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 }
+  )
 }
 
 /**