acrylblends 1.0.10 → 1.2.0

package/lib/cordis/state.js

@@ -1,9 +1,9 @@
 import { t as Acryl } from "../app-CQcGWjrk.js";
 import { t as methodNotAllowed } from "../method-not-allowed-TO2_hnfl.js";
 import { r as streamSSE } from "../streaming-BlDaph8U.js";
-import { i as loopbackOnly } from "../loopback-only-BbasoF7R.js";
+import { i as loopbackOnly, r as loopbackAuthority } from "../loopback-only-BbasoF7R.js";
 import "../helpers-BEjcdbgw.js";
-import "../src-BTBm4OPD.js";
+import "../src-iBJ2ysV9.js";
 import "../middleware-BfG_fp8P.js";
 import { Service } from "@deepseek-ai/cordis";
 //#region ../../plugins/acryl-state/src/cell.ts
@@ -58,6 +58,345 @@ function createDerived(key, inputs, compute, report = () => void 0) {
 	};
 }
 //#endregion
+//#region ../../plugins/acryl-state/src/client-source.ts
+/**
+* The browser module served at `/api/state/client.js`, kept as text so it travels with the plugin wherever the plugin goes (copied into an app as source, or bundled): there is
+* no file to find at run time and no compiler needed to serve it. `String.raw` keeps every backslash as written, so what is below is the module exactly as the browser gets it.
+* The code has no imports and uses no backtick or dollar-brace of its own.
+*
+*   import { watch } from '/api/state/client.js'
+*   const stop = watch('tasks.count', (value) => { badge.textContent = String(value) })
+*
+* One WebSocket for the whole page carries every key; a WebSocket is not one of the browser's six connections per host, so a page that watches ten keys, in as many windows,
+* leaves every one of them free for requests. Where the WebSocket cannot open (no `ws` package on the server, a proxy that does not upgrade), each key is followed by its
+* event stream instead, with one console warning.
+*/
+const CLIENT_SOURCE = String.raw`// acryl-state: watch(key, onValue, onError?) follows a state key over one WebSocket for the page.
+const HEARTBEAT_SILENCE_MS = 45000
+const RETRY_MIN_MS = 250
+const RETRY_MAX_MS = 10000
+
+const here = import.meta.url
+const watchers = new Map()
+const latest = new Map()
+const streams = new Map()
+const complained = new Set()
+let socket
+let timer
+let watchdog
+let attempts = 0
+let opened = false
+let following = 'socket'
+let suspended = false
+let warnedStream = false
+
+const socketUrl = () => {
+  const url = new URL('ws', here)
+  url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:'
+  return url.href
+}
+const streamUrl = (key) => new URL(encodeURIComponent(key) + '/events?json=1', here).href
+
+const deliver = (key, text) => {
+  if (latest.get(key) === text) return
+  latest.set(key, text)
+  let value
+  try {
+    value = JSON.parse(text)
+  } catch {
+    return
+  }
+  for (const watcher of [...(watchers.get(key) ?? [])]) {
+    try {
+      watcher.onValue(value)
+    } catch (cause) {
+      console.error('acryl-state: a watcher of ' + key + ' threw', cause)
+    }
+  }
+}
+
+const fail = (key, message) => {
+  const set = watchers.get(key)
+  if (set === undefined) return
+  let told = false
+  for (const watcher of [...set]) {
+    if (watcher.onError === undefined) continue
+    told = true
+    try {
+      watcher.onError(new Error(message))
+    } catch (cause) {
+      console.error('acryl-state: an error handler of ' + key + ' threw', cause)
+    }
+  }
+  if (!told && !complained.has(key)) {
+    complained.add(key)
+    console.warn('acryl-state: ' + key + ': ' + message)
+  }
+}
+
+const send = (frame) => {
+  if (socket !== undefined && socket.readyState === 1) socket.send(JSON.stringify(frame))
+}
+
+const arm = () => {
+  clearTimeout(watchdog)
+  watchdog = setTimeout(() => lost(socket), HEARTBEAT_SILENCE_MS)
+}
+
+const closeSocket = () => {
+  clearTimeout(watchdog)
+  const current = socket
+  socket = undefined
+  if (current === undefined) return
+  current.onopen = current.onmessage = current.onerror = current.onclose = null
+  try {
+    current.close(1000, 'page left')
+  } catch {
+    // Already closed.
+  }
+}
+
+const closeStreams = () => {
+  for (const source of streams.values()) source.close()
+  streams.clear()
+}
+
+const openStream = (key) => {
+  if (streams.has(key) || typeof EventSource === 'undefined') return
+  const source = new EventSource(streamUrl(key))
+  streams.set(key, source)
+  source.addEventListener('value', (event) => deliver(key, event.data))
+  source.onerror = () => {
+    // A network error is retried by the browser itself; a refusal (the key does not exist) ends the stream for good.
+    if (source.readyState === 2) {
+      streams.delete(key)
+      fail(key, 'the event stream was refused (no such state?)')
+    }
+  }
+}
+
+const fallBack = () => {
+  following = 'stream'
+  if (!warnedStream) {
+    warnedStream = true
+    console.warn('acryl-state: the WebSocket did not open, so each key is followed by its own event stream (each holds one of the browser\'s six connections to this host)')
+  }
+  for (const key of watchers.keys()) openStream(key)
+}
+
+// A socket that closes, errors or goes quiet: before it ever opened this is a server without WebSockets, so the streams take over; after, the server went away and the page tries again.
+const lost = (which) => {
+  if (which !== socket) return
+  closeSocket()
+  if (watchers.size === 0 || suspended) return
+  if (!opened) {
+    fallBack()
+    return
+  }
+  const delay = Math.min(RETRY_MIN_MS * 2 ** attempts, RETRY_MAX_MS)
+  attempts += 1
+  clearTimeout(timer)
+  timer = setTimeout(connect, delay)
+}
+
+const connect = () => {
+  clearTimeout(timer)
+  if (socket !== undefined || watchers.size === 0 || suspended || following !== 'socket') return
+  let made
+  try {
+    made = new WebSocket(socketUrl())
+  } catch {
+    fallBack()
+    return
+  }
+  socket = made
+  made.onopen = () => {
+    opened = true
+    attempts = 0
+    arm()
+    for (const key of watchers.keys()) send({ t: 'sub', key })
+  }
+  made.onmessage = (event) => {
+    if (made !== socket) return
+    arm()
+    let frame
+    try {
+      frame = JSON.parse(event.data)
+    } catch {
+      return
+    }
+    if (frame === null || typeof frame !== 'object' || typeof frame.key !== 'string') return
+    if (typeof frame.error === 'string') fail(frame.key, frame.error)
+    else deliver(frame.key, JSON.stringify(frame.value))
+  }
+  made.onerror = () => lost(made)
+  made.onclose = () => lost(made)
+}
+
+const start = () => {
+  if (watchers.size === 0) return
+  if (following === 'stream') for (const key of watchers.keys()) openStream(key)
+  else connect()
+}
+
+if (typeof addEventListener === 'function') {
+  // A page in the back/forward cache keeps its connections open for as long as it is kept; let them go when the page is hidden for good, and open them again when it comes back.
+  addEventListener('pagehide', () => {
+    suspended = true
+    clearTimeout(timer)
+    closeSocket()
+    closeStreams()
+  })
+  addEventListener('pageshow', () => {
+    if (!suspended) return
+    suspended = false
+    start()
+  })
+}
+
+// Follow the state key: onValue gets the value now and after every change, as the JSON value the server holds (a string stays a string). onError, when given, is told of a key that
+// does not exist; without it the page console gets one warning. Returns the function that stops watching.
+export function watch(key, onValue, onError) {
+  if (typeof key !== 'string' || key === '') throw new TypeError('watch(key, onValue): the key is a state key like "tasks.count"')
+  if (typeof onValue !== 'function') throw new TypeError('watch(key, onValue): onValue is a function')
+  const watcher = { onValue, onError }
+  let set = watchers.get(key)
+  const first = set === undefined
+  if (first) {
+    set = new Set()
+    watchers.set(key, set)
+  }
+  set.add(watcher)
+  complained.delete(key)
+  if (!first && latest.has(key)) {
+    const text = latest.get(key)
+    queueMicrotask(() => {
+      if (!set.has(watcher)) return
+      try {
+        onValue(JSON.parse(text))
+      } catch (cause) {
+        console.error('acryl-state: a watcher of ' + key + ' threw', cause)
+      }
+    })
+  }
+  if (first && !suspended) {
+    if (following === 'stream') openStream(key)
+    else if (socket === undefined) connect()
+    else send({ t: 'sub', key })
+  }
+  let stopped = false
+  return () => {
+    if (stopped) return
+    stopped = true
+    set.delete(watcher)
+    if (set.size > 0) return
+    watchers.delete(key)
+    latest.delete(key)
+    complained.delete(key)
+    streams.get(key)?.close()
+    streams.delete(key)
+    send({ t: 'unsub', key })
+    if (watchers.size === 0) {
+      clearTimeout(timer)
+      closeSocket()
+    }
+  }
+}
+`;
+/** A refusal (403) unless the upgrade comes from this machine to this app, and from its own page when it comes from a page at all. */
+function refuseStranger(c) {
+	const authority = loopbackAuthority(c);
+	if (authority === void 0) return c.json({ error: "request authority rejected" }, 403);
+	const origin = c.req.header("origin");
+	const site = c.req.header("sec-fetch-site");
+	if (origin !== void 0 && origin !== authority.origin || site !== void 0 && site !== "same-origin") return c.json({ error: "only this app's own page may follow its state" }, 403);
+}
+/** The route handler that upgrades and follows keys of `cells` for as long as the socket is open. */
+function stateSocket(cells, options) {
+	const heartbeatMs = options.heartbeatMs ?? 15e3;
+	return options.upgrade(() => {
+		const following = /* @__PURE__ */ new Map();
+		let beat;
+		return {
+			onOpen(_event, ws) {
+				beat = setInterval(() => {
+					try {
+						ws.send(JSON.stringify({ t: "ping" }));
+					} catch {}
+				}, heartbeatMs);
+				beat.unref();
+			},
+			onMessage(event, ws) {
+				if (typeof event.data !== "string") return;
+				let message;
+				try {
+					message = JSON.parse(event.data);
+				} catch {
+					return;
+				}
+				if (typeof message.key !== "string") return;
+				const key = message.key;
+				const tell = (frame) => {
+					try {
+						ws.send(JSON.stringify(frame));
+					} catch {}
+				};
+				const value = (current) => {
+					let text;
+					try {
+						text = JSON.stringify({
+							key,
+							value: current === void 0 ? null : current
+						});
+					} catch {
+						tell({
+							key,
+							error: "the value cannot be sent as JSON"
+						});
+						return;
+					}
+					try {
+						ws.send(text);
+					} catch {}
+				};
+				if (message.t === "unsub") {
+					following.get(key)?.();
+					following.delete(key);
+					return;
+				}
+				if (message.t !== "sub") return;
+				const cell = cells.find(key);
+				if (cell === void 0) {
+					tell({
+						key,
+						error: "no such state"
+					});
+					return;
+				}
+				const known = following.has(key);
+				if (!known && following.size >= 256) {
+					tell({
+						key,
+						error: "too many keys on one socket"
+					});
+					return;
+				}
+				if (known) {
+					value(cell.get());
+					return;
+				}
+				value(cell.get());
+				following.set(key, cell.subscribe(value));
+			},
+			onClose() {
+				if (beat !== void 0) clearInterval(beat);
+				for (const stop of following.values()) stop();
+				following.clear();
+			}
+		};
+	}, { textOnly: true });
+}
+//#endregion
 //#region ../../plugins/acryl-state/src/service.ts
 /**
 * The ACRYL state service (`ctx.state`): observable cells owned by plugins. A cell created from a plugin's context is removed
@@ -69,6 +408,8 @@ const KEEP_ALIVE_MS = 15e3;
 /** Stable Cordis plugin name, equal to the package name and the Loader row id. */
 const name = "acryl-state";
 const KEY_PATTERN = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)*$/;
+/** Names under `/api/state` that are routes, not keys: a cell cannot be called by one. */
+const RESERVED_KEYS = /* @__PURE__ */ new Set(["ws", "client.js"]);
 var State = class extends Service {
 	cells = /* @__PURE__ */ new Map();
 	constructor(ctx) {
@@ -76,6 +417,7 @@ var State = class extends Service {
 	}
 	claim(key) {
 		if (!KEY_PATTERN.test(key)) throw new TypeError(`acryl-state: key "${key}" must be dotted lowercase words, like "market.sources"`);
+		if (RESERVED_KEYS.has(key)) throw new TypeError(`acryl-state: "${key}" is the name of a route under /api/state, choose another key`);
 		if (this.cells.has(key)) throw new Error(`acryl-state: key "${key}" is already in use`);
 	}
 	report = (error) => {
@@ -111,9 +453,10 @@ var State = class extends Service {
 	}
 	/**
 	* The current value of `key` as a server-sent event stream: the value now, then one event per change, until the client cancels or the router
-	* is disposed (both abort the stream). A comment line goes out every 15 seconds so proxies and browsers keep an idle stream open.
+	* is disposed (both abort the stream). A comment line goes out every 15 seconds so proxies and browsers keep an idle stream open. A string value travels as it is; with `json`
+	* (the `?json=1` of the browser client) every value is JSON, so `"12"` and `12` can be told apart.
 	*/
-	stream(key, c) {
+	stream(key, c, json = false) {
 		const cell = this.find(key);
 		if (cell === void 0) return void 0;
 		return streamSSE(c, async (stream) => {
@@ -124,7 +467,7 @@ var State = class extends Service {
 			const send = (value) => {
 				queue = queue.then(() => stream.writeSSE({
 					event: "value",
-					data: typeof value === "string" ? value : JSON.stringify(value)
+					data: typeof value === "string" && !json ? value : JSON.stringify(value)
 				})).catch(() => {});
 			};
 			send(cell.get());
@@ -146,14 +489,35 @@ function apply(ctx) {
 	const state = new State(ctx);
 	ctx.inject(["router"], (inner) => {
 		const api = new Acryl();
-		api.use(loopbackOnly({ inProcess: "allow" }), methodNotAllowed({ app: api })).get("/", (c) => c.json({ keys: state.keys() })).get("/:key", (c) => {
+		let socket;
+		api.use(loopbackOnly({ inProcess: "allow" }), methodNotAllowed({ app: api })).get("/", (c) => c.json({ keys: state.keys() })).get("/client.js", (c) => c.body(CLIENT_SOURCE, 200, {
+			"content-type": "text/javascript; charset=utf-8",
+			"cache-control": "no-cache"
+		})).get("/ws", async (c, next) => {
+			const upgrade = socket;
+			if (upgrade === void 0) return c.json({ error: "this server does not upgrade to a WebSocket" }, 404);
+			const refusal = refuseStranger(c);
+			if (refusal !== void 0) return refusal;
+			return await upgrade(c, next);
+		}).get("/:key", (c) => {
 			const cell = state.find(c.req.param("key"));
 			return cell === void 0 ? c.json({ error: "no such state" }, 404) : c.json({
 				key: cell.key,
 				value: cell.get()
 			});
-		}).get("/:key/events", (c) => state.stream(c.req.param("key"), c) ?? c.json({ error: "no such state" }, 404));
+		}).get("/:key/events", (c) => state.stream(c.req.param("key"), c, c.req.query("json") === "1") ?? c.json({ error: "no such state" }, 404));
 		inner.router.route("/api/state", api);
+		inner.inject(["nodeServer"], (withServer) => {
+			try {
+				const upgrade = withServer.nodeServer.upgrades();
+				socket = stateSocket(state, { upgrade });
+				withServer.effect(() => () => {
+					socket = void 0;
+				}, "acryl-state: the WebSocket route");
+			} catch (cause) {
+				ctx.logger.warn(`acryl-state: state is followed by event streams only (${cause instanceof Error ? cause.message : String(cause)})`);
+			}
+		});
 		inner.inject(["routerHttp"], (http) => {
 			http.routerHttp.mount("/api/state");
 		});

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-Dw-siYTp.js";
+import { n as AuditEntry, y as UiSnapshot } from "../protocol-BeIYCgTo.js";
+import { i as UiChannel, n as auditPath, r as PageStream, t as AuditLog } from "../audit-Bok_UNCn.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-BfEbEOjA.js";
+import { d as AuditLog, f as auditPath, n as HEARTBEAT_MS, p as UiChannel, r as pageChannelRoutes, t as renderSnapshot } from "../snapshot-text-CXTnjxGx.js";
 export { AuditLog, HEARTBEAT_MS, UiChannel, auditPath, pageChannelRoutes, renderSnapshot };

package/lib/door/page.d.ts

@@ -1,9 +1,11 @@
-import { _ as UiRequest, v as UiResult } from "../protocol-a2aqrp2X.js";
+import { _ as UiRequest, v as UiResult } from "../protocol-BeIYCgTo.js";
 
 //#region ../../plugins/acryl-door/src/page/driver/driver.d.ts
 interface DriverActivity {
   /** True from the moment a call starts until it ends. */
   readonly busy: boolean;
+  /** True from the moment a run asked for from this page's panel starts until it ends, between the calls too. */
+  readonly running: boolean;
   /** What the agent is doing, for the indicator ("click", "type", ...). */
   readonly doing: string;
   /** True after the user pressed the kill switch. */
@@ -14,6 +16,8 @@ interface UiDriverOptions {
   /** Milliseconds since the user last used the page (mouse, keyboard); Infinity when never. */
   readonly msSinceUserInput?: () => number;
   readonly sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+  /** Called with the element an act is about to use, for the page to show it (the door's outline on what the agent touches). */
+  readonly touched?: (element: Element) => void;
   /** Leave the page: reload it, or go to a path of the app. Default: the document's own `location`, a moment after the answer is sent. */
   readonly leave?: (to: {
     readonly reload: true;
@@ -32,6 +36,7 @@ declare class UiDriver {
   private busyCount;
   private doing;
   private current;
+  private runningFlag;
   private readonly options;
   constructor(options: UiDriverOptions);
   /** The current activity; the same object until something changes, as a store snapshot must be. */
@@ -39,6 +44,11 @@ declare class UiDriver {
   subscribe(listener: (activity: DriverActivity) => void): () => void;
   /** The user pressed the kill switch: pending calls settle as `killed` and new ones are refused. */
   kill(): void;
+  /**
+   * A run asked for from this page's panel starts (`true`) or ends (`false`). The indicator stays up for the whole run, not only while a call is in flight. A new run is a new
+   * question from the person, so it also allows the agent to drive again after an earlier Stop.
+   */
+  setRunning(running: boolean): void;
   /** The user allowed the agent to drive again. */
   resume(): void;
   /** The driver goes away: pending calls settle as `unloaded`; refs are gone. */
@@ -46,6 +56,11 @@ declare class UiDriver {
   /** @param signal - the Host cancelled the call. @throws UiControlError. */
   handle(request: UiRequest, signal?: AbortSignal): Promise<UiResult>;
   private run;
+  /**
+   * Run an act that may start a navigation (a click on a link, Enter in a form) and say so: the browser asks `beforeunload` when a navigation starts, during the act or a
+   * moment after it. The answer is sent before the page goes; the Host then waits for the next page instead of reading this one again.
+   */
+  private watchLeaving;
   /**
    * The page is about to be replaced, so the answer is given first and the move happens a moment later (the answer is a POST that the page's own unload would cut off).
    * The Host does not wait for this answer to be the last word: it waits for the page to come back.
@@ -73,6 +88,8 @@ interface ChannelSource {
 declare const SILENCE_MS = 45000;
 interface PageChannelOptions {
   readonly windowId: string;
+  /** The browser tab the page is in (kept across the tab's reloads and moves), so the Host follows a run's page into the next document of its tab. */
+  readonly tab?: string;
   /** The desktop window this page is in (`AcrylWindow/<n>` in the user agent, set by the Electron shell), so the Host can drive it by the number `window list` prints. */
   readonly shellWindow?: number;
   readonly focused: () => boolean;
@@ -87,6 +104,8 @@ interface PageChannelOptions {
   readonly post?: (url: string, body: string) => Promise<unknown>;
   readonly silenceMs?: number;
   readonly now?: () => number;
+  /** The Host says a run asked for from this page's panel started (`true`) or ended (`false`); false too when the stream is lost, until the Host says again. */
+  readonly onRun?: (running: boolean) => void;
 }
 declare class PageChannel {
   private source;