buninu-browser 0.5.0 → 0.6.0

package/README.md

@@ -291,9 +291,9 @@ borrows a contiguous raster view instead of rescaling; encoded output uses
 the same crop. `Page.getLayoutMetrics` provides the viewport position so
 Casty can follow document scrolling.
 
-Casty also sends a private `clip` on `Page.startScreencast`. It takes precedence over fallback max limits and crops at native pixel density, without resizing. Width/height are CSS units; output pixels still follow device scale. This extension is not standard CDP.
+Casty also sends a private `clip` on `Page.startScreencast`. It takes precedence over fallback max limits and crops at native pixel density, without resizing. Width/height are CSS units; output pixels still follow device scale. This extension is not standard CDP. A clip with both width and height equal to zero requests update notifications only: the server sends a fixed 1×1 PNG placeholder without rendering or encoding a preview. Ordinary captureScreenshot still rejects zero-sized clips.
 
-Casty 也會在 `Page.startScreencast` 傳入私有 `clip`；優先於相容用的 max 限制，以原像素密度裁切、不縮放。寬高是 CSS 單位，實體像素仍隨 device scale 換算。此擴充不是標準 CDP。
+Casty 也會在 `Page.startScreencast` 傳入私有 `clip`；優先於相容用的 max 限制，以原像素密度裁切、不縮放。寬高是 CSS 單位，實體像素仍隨 device scale 換算。此擴充不是標準 CDP。寬高都為零時只發送更新通知：server 回傳固定 1×1 PNG 佔位資料，不渲染或編碼預覽；一般 captureScreenshot 仍拒絕零尺寸。
 
 標準 CDP `clip` 也適用於 raw 截圖；小數 CSS 尺寸保留到最後才換算成實體像素，
 避免字體大小改變後差一列而觸發 bunterm 縮放。`clip.scale: 1` 的全寬裁切
@@ -469,7 +469,13 @@ it to `buninu-browser.log` in the working directory, or set
 
 - page errors and page `console` output;
 - per-phase load timings;
-- renderer crashes and watchdog kills.
+- renderer crashes and explicitly enabled watchdog kills.
+
+Renderer and video-worker startup have no deadline. Document navigation also
+waits until completion, failure, or explicit close. The browser does not enable
+the renderer method watchdog by default: slow initialization or page work must
+not kill the renderer. Internal callers can opt into a method watchdog through
+`rendererTimeout`; this does not impose a startup or navigation deadline.
 
 Renderers cannot open files under seccomp, so the controller collects their
 output and writes the log.

package/lib/audio/pcm.js

@@ -1,6 +1,17 @@
+// Typed-array stores use host byte order; the wire format is always s16le.
+const LITTLE_ENDIAN = new Uint8Array(new Uint16Array([1]).buffer)[0] === 1;
+
 /** Interleaved Float32 samples in [-1, 1] (as audio decoders produce) as s16le bytes. */
 export function floatToS16(samples) {
   const out = new Uint8Array(samples.length * 2);
+  if (LITTLE_ENDIAN) {
+    const view = new Int16Array(out.buffer);
+    for (let index = 0; index < samples.length; index++) {
+      const value = Math.max(-1, Math.min(1, samples[index]));
+      view[index] = Math.round(value < 0 ? value * 32768 : value * 32767);
+    }
+    return out;
+  }
   const view = new DataView(out.buffer);
   for (let index = 0; index < samples.length; index++) {
     const value = Math.max(-1, Math.min(1, samples[index]));

package/lib/audio/pulse-client.js

@@ -339,6 +339,9 @@ export class PulseClient {
  */
 const LEAD_SECONDS = 0.5;
 const PACE_MS = 50;
+// Video follows this measured clock. Sharing the 50 ms PCM timer would cap
+// presentation at 20 FPS even when decoding and output can keep up.
+const TIMING_MS = 16;
 const MIN_REQUEST_SECONDS = 0.02;
 const MIN_PACKET_SECONDS = 0.04;
 const MAX_PACKET_SECONDS = 0.1;
@@ -355,6 +358,7 @@ class PlaybackStream {
   #outstanding = 0;
   #started = null;
   #timer = null;
+  #timingTimer = null;
   #leadSeconds;
   #onTiming;
   #onTimingError;
@@ -376,7 +380,8 @@ class PlaybackStream {
     this.#producerBuffer = new PlaybackBuffer(this.#bytesPerSecond, this.#frameBytes, leadSeconds);
     this.#onTiming = onTiming;
     this.#onTimingError = onTimingError;
-    this.#timer = setInterval(() => { this.#pace(); void this.updateTiming(); }, PACE_MS);
+    this.#timer = setInterval(() => this.#pace(), PACE_MS);
+    if (onTiming) this.#timingTimer = setInterval(() => { void this.updateTiming(); }, TIMING_MS);
   }
 
   async updateTiming() {
@@ -393,7 +398,6 @@ class PlaybackStream {
       this.#onTiming({ seconds: this.#playedBytes / this.#bytesPerSecond,
         sentSeconds: this.#offset / this.#bytesPerSecond, sinkSeconds: timing.sinkSeconds, playing: timing.playing,
         bufferedSeconds: this.#queuedBytes / this.#bytesPerSecond });
-      this.#pace();
     } catch (error) {
       if (!this.killed) this.#onTimingError?.(error);
     } finally {
@@ -527,5 +531,6 @@ class PlaybackStream {
     this.#queue = [];
     this.#queuedBytes = 0;
     clearInterval(this.#timer);
+    clearInterval(this.#timingTimer);
   }
 }

package/lib/cdp-server.js

@@ -40,11 +40,20 @@ export class CdpServer {
     // Pages change on their own (loading stages, scripts, compositor
     // scrolling): push a screencast frame whenever the context reports one,
     // and send lifecycle events when the document really reaches them.
-    context.onFrame?.(() => {
+    context.onFrame?.((frame) => {
+      const offset = frame?.scrollOffset;
+      const scrollOffset = Number.isFinite(offset?.x) && Number.isFinite(offset?.y)
+        ? { x: offset.x, y: offset.y } : null;
       for (const target of state.targets.values()) {
-        if (target.screencast && target.screencastEmit) pushScreencastFrame(context, state, target);
+        if (target.screencast && target.screencastEmit) {
+          target.screencastScrollOffset = scrollOffset;
+          pushScreencastFrame(context, state, target);
+        }
+      }
+      if (state.implicitTarget?.screencast) {
+        state.implicitTarget.screencastScrollOffset = scrollOffset;
+        pushScreencastFrame(context, state, state.implicitTarget);
       }
-      if (state.implicitTarget?.screencast) pushScreencastFrame(context, state, state.implicitTarget);
     });
     context.onLifecycle?.((name) => {
       for (const target of state.targets.values()) emitLifecycle(target, name);
@@ -844,6 +853,7 @@ function createTarget(state, url = "about:blank", options = {}) {
       deviceScaleFactor: 1,
     },
     screencast: null,
+    screencastScrollOffset: null,
     screencastFrames: new Set(),
   };
   state.targets.set(targetId, target);
@@ -892,6 +902,7 @@ function stopScreencast(target) {
   target.screencast = null;
   target.screencastEmit = null;
   target.screencastPending = false;
+  target.screencastScrollOffset = null;
   target.screencastFrames.clear();
 }
 
@@ -918,10 +929,21 @@ async function pushScreencastFrame(ctx, state, target) {
 
 async function emitScreencastFrame(ctx, state, target) {
   const stream = target.screencast, emit = target.screencastEmit;
-  const data = await screenshotData(ctx, target, stream);
-  if (!data || stream !== target.screencast || emit !== target.screencastEmit) return;
-  const scrollOffset = await ctx.scrollOffset?.() ?? { x: 0, y: 0 };
-  if (stream !== target.screencast || emit !== target.screencastEmit) return;
+  const loaderId = target.loaderId;
+  // This belongs to one invalidation, not a lasting cache. Pending updates
+  // replace it with the latest position; start/restart without one still query.
+  const notifiedOffset = target.screencastScrollOffset;
+  target.screencastScrollOffset = null;
+  // Private zero-area screencast: signal invalidation without rendering pixels.
+  // captureScreenshot keeps its ordinary clip validation.
+  const zeroArea = stream.clip?.width === 0 && stream.clip?.height === 0;
+  const data = zeroArea
+    ? "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAusB9Wl6SAAAAABJRU5ErkJggg=="
+    : await screenshotData(ctx, target, stream);
+  if (!data || stream !== target.screencast || emit !== target.screencastEmit || loaderId !== target.loaderId) return;
+  const scrollOffset = zeroArea && notifiedOffset ? notifiedOffset
+    : await ctx.scrollOffset?.() ?? { x: 0, y: 0 };
+  if (stream !== target.screencast || emit !== target.screencastEmit || loaderId !== target.loaderId) return;
   const sessionId = state.nextScreencastFrameId++;
   target.screencastFrames.add(sessionId);
   emit("Page.screencastFrame", {
@@ -950,6 +972,7 @@ function getPendingInitialNavigationTarget(state) {
 
 function navigateTarget(state, target, url, emit, options = {}) {
   const deferLifecycle = typeof state.context?.onLifecycle === "function";
+  target.screencastScrollOffset = null;
   target.lifecycleEmit = null;
   target.url = url;
   loadDocument(target, url);
@@ -1045,6 +1068,7 @@ function getImplicitTarget(state) {
   state.implicitTarget = {
     targetId: "implicit-target",
     screencast: null,
+    screencastScrollOffset: null,
     screencastFrames: new Set(),
     frameId: "implicit-target",
     loaderId: "implicit-loader",

package/lib/happy-dom/document-base.js

@@ -1,12 +1,40 @@
 import Node from "../../vendor/happy-dom/packages/happy-dom/src/nodes/node/Node.ts";
 import Document from "../../vendor/happy-dom/packages/happy-dom/src/nodes/document/Document.ts";
+import HTMLBaseElement from "../../vendor/happy-dom/packages/happy-dom/src/nodes/html-base-element/HTMLBaseElement.ts";
 import HTMLHyperlinkElementUtility from "../../vendor/happy-dom/packages/happy-dom/src/nodes/html-hyperlink-element/HTMLHyperlinkElementUtility.ts";
+import * as PropertySymbol from "../../vendor/happy-dom/packages/happy-dom/src/PropertySymbol.ts";
+
+// Happy DOM reads baseURI on every attribute set, so the parser looked up
+// `base[href]` once per attribute: a whole-document scan each time when there
+// is no base. The first base[href] of each document is cached until one of
+// that document's <base> elements is connected, disconnected or has an
+// attribute changed. An adopted <base> disconnects from its old document
+// first, so both documents are invalidated.
+const baseCache = new WeakMap();
+{
+  const prototype = HTMLBaseElement.prototype;
+  const inherited = Object.getPrototypeOf(prototype);
+  for (const symbol of [PropertySymbol.connectedToDocument, PropertySymbol.disconnectedFromDocument,
+    PropertySymbol.onSetAttribute, PropertySymbol.onRemoveAttribute]) {
+    prototype[symbol] = function(...args) {
+      baseCache.delete(this[PropertySymbol.ownerDocument]);
+      return inherited[symbol].apply(this, args);
+    };
+  }
+}
+
+function firstBase(document) {
+  if (baseCache.has(document)) return baseCache.get(document);
+  const base = document.querySelector?.("base[href]") ?? null;
+  baseCache.set(document, base);
+  return base;
+}
 
 /** HTML document base URL, shared by the inert DOM and its page bindings. */
 export function documentBaseURL(node) {
   const document = node?.nodeType === 9 ? node : node?.ownerDocument;
   const fallback = document?.URL ?? "about:blank";
-  const base = document?.querySelector?.("base[href]");
+  const base = document ? firstBase(document) : null;
   if (!base) return fallback;
   try {
     const url = new URL(base.getAttribute("href"), fallback);

package/lib/happy-dom/inert-link.js

@@ -0,0 +1,26 @@
+import * as PropertySymbol from '../../vendor/happy-dom/packages/happy-dom/src/PropertySymbol.ts';
+
+// Happy DOM shares HTMLLinkElement.prototype between windows. Install one
+// dispatch hook, but bypass its loader only for windows owned by our renderer.
+const inertWindows = new WeakSet();
+let installed = false;
+export function makeLinksInert(window) {
+  inertWindows.add(window);
+  if (installed) return;
+  installed = true;
+  const base = window.HTMLElement.prototype;
+  const prototype = window.HTMLLinkElement.prototype;
+  const connected = prototype[PropertySymbol.connectedToDocument];
+  const setAttribute = prototype[PropertySymbol.onSetAttribute];
+  prototype[PropertySymbol.connectedToDocument] = function() {
+    if (!inertWindows.has(this[PropertySymbol.window])) return connected.call(this);
+    // The renderer owns load/error dispatch; the disabled parser loader must
+    // not emit a premature error when a dynamic stylesheet is connected.
+    base[PropertySymbol.connectedToDocument].call(this);
+    this.ownerDocument[PropertySymbol.clearComputedStyleCache]();
+  };
+  prototype[PropertySymbol.onSetAttribute] = function(attribute, replacedAttribute) {
+    if (!inertWindows.has(this[PropertySymbol.window])) return setAttribute.call(this, attribute, replacedAttribute);
+    base[PropertySymbol.onSetAttribute].call(this, attribute, replacedAttribute);
+  };
+}

package/lib/happy-dom/mutation-observer.js

@@ -0,0 +1,157 @@
+import * as PropertySymbol from '../../vendor/happy-dom/packages/happy-dom/src/PropertySymbol.ts';
+
+// One notification microtask for this renderer agent, with one ordered record
+// queue per observer. Target registrations must not schedule their own delivery.
+const enqueueMicrotask = globalThis.queueMicrotask;
+const pending = new Set();
+let queued = false;
+let creationIndex = 0;
+
+function activate(observer) {
+  pending.add(observer);
+  if (queued) return;
+  queued = true;
+  enqueueMicrotask(() => {
+    queued = false;
+    const observers = [...pending].sort((left, right) => left.order - right.order);
+    pending.clear();
+    for (const observer of observers) observer.deliver();
+  });
+}
+
+function optionsOf(window, input = {}) {
+  const attributes = input.attributes === undefined
+    ? input.attributeOldValue !== undefined || input.attributeFilter !== undefined
+    : Boolean(input.attributes);
+  const characterData = input.characterData === undefined
+    ? input.characterDataOldValue !== undefined : Boolean(input.characterData);
+  const options = {
+    childList: Boolean(input.childList), attributes, characterData,
+    subtree: Boolean(input.subtree),
+    attributeOldValue: Boolean(input.attributeOldValue),
+    characterDataOldValue: Boolean(input.characterDataOldValue),
+    attributeFilter: input.attributeFilter === undefined ? null : Array.from(input.attributeFilter, String),
+  };
+  if ((!options.childList && !attributes && !characterData) ||
+      (!attributes && (options.attributeOldValue || options.attributeFilter !== null)) ||
+      (!characterData && options.characterDataOldValue)) {
+    throw new window.TypeError('Invalid MutationObserver options');
+  }
+  return options;
+}
+
+export function installMutationObservers(window) {
+  window.MutationObserver = class MutationObserver {
+    #callback;
+    #registrations = new Map();
+    #records = [];
+    #seen = new WeakMap();
+    #destroyed = false;
+    #delivery;
+
+    constructor(callback) {
+      if (typeof callback !== 'function') throw new window.TypeError('MutationObserver callback must be a function');
+      this.#callback = callback;
+      this.#delivery = { order: creationIndex++, deliver: () => this.#deliver() };
+    }
+
+    observe(target, input) {
+      if (this.#destroyed || window.closed) return;
+      if (!target || typeof target[PropertySymbol.observeMutations] !== 'function') {
+        throw new window.TypeError('MutationObserver.observe requires a Node');
+      }
+      const options = optionsOf(window, input);
+      const previous = this.#registrations.get(target);
+      if (previous) this.#remove(previous);
+      const registration = { target, options, transientRoots: new Set(), callback: null, listener: null };
+      registration.callback = (record) => this.#report(registration, record);
+      registration.listener = {
+        // Removals establish temporary registrations even if childList records
+        // were not requested. These survive until this observer is notified.
+        options: { ...options, childList: options.childList || options.subtree },
+        callback: new WeakRef(registration.callback),
+      };
+      this.#registrations.set(target, registration);
+      target[PropertySymbol.observeMutations](registration.listener);
+      if (!window[PropertySymbol.mutationObservers].includes(this)) {
+        window[PropertySymbol.mutationObservers].push(this);
+      }
+    }
+
+    #clearTransient(registration) {
+      for (const root of registration.transientRoots) {
+        root[PropertySymbol.unobserveMutations](registration.listener);
+      }
+      registration.transientRoots.clear();
+    }
+
+    #remove(registration) {
+      this.#clearTransient(registration);
+      registration.target[PropertySymbol.unobserveMutations](registration.listener);
+    }
+
+    #report(registration, record) {
+      const { options } = registration;
+      if (options.subtree && record.type === 'childList') {
+        for (const root of record.removedNodes) {
+          if (!registration.transientRoots.has(root)) {
+            registration.transientRoots.add(root);
+            root[PropertySymbol.observeMutations](registration.listener);
+          }
+        }
+        if (record.removedNodes.length) activate(this.#delivery);
+      }
+      if (record.type === 'childList' && !options.childList) return;
+      const wantsOld = record.type === 'attributes' ? options.attributeOldValue
+        : record.type === 'characterData' && options.characterDataOldValue;
+      const existing = this.#seen.get(record);
+      if (existing) {
+        if (wantsOld) existing.oldValue = record.oldValue;
+        return;
+      }
+      const copy = Object.assign(Object.create(Object.getPrototypeOf(record)), record, {
+        oldValue: wantsOld ? record.oldValue : null,
+      });
+      this.#seen.set(record, copy);
+      this.#records.push(copy);
+      activate(this.#delivery);
+    }
+
+    #deliver() {
+      const records = this.takeRecords();
+      for (const registration of this.#registrations.values()) this.#clearTransient(registration);
+      if (!records.length || this.#destroyed || window.closed) return;
+      try {
+        this.#callback.call(this, records, this);
+      } catch (error) {
+        window[PropertySymbol.dispatchError](error);
+      }
+    }
+
+    takeRecords() {
+      const records = this.#records;
+      this.#records = [];
+      this.#seen = new WeakMap();
+      return records;
+    }
+
+    disconnect() {
+      for (const registration of this.#registrations.values()) this.#remove(registration);
+      this.#registrations.clear();
+      this.takeRecords();
+      // Window destruction iterates this array. Do not splice it during that
+      // iteration, otherwise the next observer would survive teardown.
+      if (!window.closed) {
+        const observers = window[PropertySymbol.mutationObservers];
+        const index = observers.indexOf(this);
+        if (index >= 0) observers.splice(index, 1);
+      }
+    }
+
+    [PropertySymbol.destroy]() {
+      this.#destroyed = true;
+      this.disconnect();
+      pending.delete(this.#delivery);
+    }
+  };
+}

package/lib/happy-dom/node-iterator-removal.js

@@ -0,0 +1,36 @@
+import Node from '../../vendor/happy-dom/packages/happy-dom/src/nodes/node/Node.ts';
+import * as PropertySymbol from '../../vendor/happy-dom/packages/happy-dom/src/PropertySymbol.ts';
+
+// NodeIterator's pre-removing steps must run synchronously, including removals
+// by innerHTML, normalize and reparenting. All reach Happy DOM's internal hook.
+const roots = new WeakMap();
+const cleanup = new FinalizationRegistry(({ entries, ref }) => entries.delete(ref));
+let installed = false;
+export function observeIteratorRemoval(root, iterator) {
+  let entries = roots.get(root);
+  if (!entries) roots.set(root, entries = new Set());
+  const ref = new WeakRef(iterator);
+  entries.add(ref);
+  cleanup.register(iterator, { entries, ref });
+  if (installed) return;
+  installed = true;
+  const remove = Node.prototype[PropertySymbol.removeChild];
+  Node.prototype[PropertySymbol.removeChild] = function(node) {
+    node = node?.[PropertySymbol.proxy] ?? node;
+    // select/form methods are bound to the raw target, while parentNode and
+    // iterator roots expose its proxy. Compare and walk the public identity.
+    const parent = this[PropertySymbol.proxy] ?? this;
+    if (node?.parentNode === parent) {
+      for (let ancestor = parent; ancestor; ancestor = ancestor.parentNode) {
+        const entries = roots.get(ancestor);
+        if (!entries) continue;
+        for (const ref of entries) {
+          const iterator = ref.deref();
+          if (iterator) iterator.preRemove(node);
+          else entries.delete(ref);
+        }
+      }
+    }
+    return remove.call(this, node);
+  };
+}

package/lib/happy-dom/node-replacement.js

@@ -0,0 +1,60 @@
+/** DOM replace: validate first, detach the incoming node, remove the outgoing
+ * node, then insert. Happy DOM's insert-then-remove order skips replacements
+ * in live NodeIterators. Keep this on the renderer bindings' mutation path.
+ * https://dom.spec.whatwg.org/#concept-node-replace */
+function validate(parent, node, child) {
+  const fail = (name) => { throw new DOMException('Invalid node replacement', name); };
+  if (![1,9,11].includes(parent.nodeType)) fail('HierarchyRequestError');
+  for (let ancestor = parent; ancestor; ancestor = ancestor.parentNode ?? ancestor.host) {
+    if (ancestor === node) fail('HierarchyRequestError');
+  }
+  if (child.parentNode !== parent) fail('NotFoundError');
+  if (![1,3,4,7,8,10,11].includes(node.nodeType)) fail('HierarchyRequestError');
+  if (node.nodeType === 10 && parent.nodeType !== 9) fail('HierarchyRequestError');
+  if (parent.nodeType !== 9) return;
+  // Validate the final document, allowing the outgoing child and an incoming
+  // sibling to be replaced/moved without counting either twice.
+  const added = node.nodeType === 11 ? [...node.childNodes] : [node];
+  const final = [];
+  for (const current of parent.childNodes) {
+    if (current === child) final.push(...added);
+    else if (current !== node) final.push(current);
+  }
+  let element = false, doctype = false;
+  for (const current of final) {
+    if (current.nodeType === 3 || current.nodeType === 4) fail('HierarchyRequestError');
+    if (current.nodeType === 1) {
+      if (element) fail('HierarchyRequestError');
+      element = true;
+    } else if (current.nodeType === 10) {
+      if (doctype || element) fail('HierarchyRequestError');
+      doctype = true;
+    }
+  }
+}
+
+export function replaceNode(parent, node, child) {
+  validate(parent, node, child);
+  let reference = child.nextSibling;
+  if (reference === node) reference = node.nextSibling;
+  if (node.parentNode) node.parentNode.removeChild(node);
+  if (child.parentNode) child.parentNode.removeChild(child);
+  parent.insertBefore(node, reference);
+  return child;
+}
+
+export function replaceWithNodes(child, nodes) {
+  const parent = child.parentNode;
+  if (!parent) return;
+  let reference = child.nextSibling;
+  while (reference && nodes.includes(reference)) reference = reference.nextSibling;
+  // DOM's convert-nodes algorithm moves multiple arguments into a fragment
+  // first, including the receiver if it occurs among the arguments.
+  let node = nodes[0];
+  if (nodes.length !== 1) {
+    node = child.ownerDocument.createDocumentFragment();
+    for (const item of nodes) node.appendChild(item);
+  }
+  if (child.parentNode === parent) replaceNode(parent, node, child);
+  else parent.insertBefore(node, reference);
+}

package/lib/happy-dom/parser.js

@@ -1,3 +1,5 @@
+import { makeLinksInert } from './inert-link.js';
+import { installMutationObservers } from './mutation-observer.js';
 import HTMLParser from "../../vendor/happy-dom/packages/happy-dom/src/html-parser/HTMLParser.ts";
 import Window from "../../vendor/happy-dom/packages/happy-dom/src/window/Window.ts";
 import * as PropertySymbol from "../../vendor/happy-dom/packages/happy-dom/src/PropertySymbol.ts";
@@ -26,7 +28,7 @@ export function parseHTMLDocument(html, url = "about:blank", referrer = "") {
 
 /** An isolated parser context: no script execution, resource loads or page custom elements. */
 export function createInertWindow(url = "about:blank") {
-  return new Window({
+  const window = new Window({
     url,
     settings: {
       disableJavaScriptEvaluation: true,
@@ -40,6 +42,9 @@ export function createInertWindow(url = "about:blank") {
       navigation: { disableFallbackToSetURL: true },
     },
   });
+  installMutationObservers(window);
+  makeLinksInert(window);
+  return window;
 }
 
 /**

package/lib/headless-shell.js

@@ -90,7 +90,7 @@ export async function runHeadlessShell(args = Bun.argv.slice(2)) {
  * WebKit identity defaults on; webkit: false selects Chromium. Mobile takes priority.
  */
 export async function createBrowser({
-  allowHostJs = false, spareRenderer = true, network = new NetworkService(), rendererTimeout = 30_000, mobile = false,
+  allowHostJs = false, spareRenderer = true, network = new NetworkService(), rendererTimeout = 0, mobile = false,
   waitForRenderer = true, webkit = true,
   clipboard = null,
 } = {}) {
@@ -105,6 +105,7 @@ export async function createBrowser({
   let current = null;
   let currentKey = null;
   let spare = null;
+  let sparePreparation = null;
   let closed = false;
   // Settles when the first renderer shows about:blank (assigned below).
   let rendererReady = null;
@@ -195,8 +196,8 @@ export async function createBrowser({
         if (host !== current) return;
         void download({ url, body: data, attributeName: name, totalBytes: data.byteLength });
       },
-      onFrame: () => {
-        if (host === current) notify(frameListeners);
+      onFrame: (frame) => {
+        if (host === current) notify(frameListeners, frame);
       },
       onLifecycle: (name, generation) => {
         let generations = lifecycleSeen.get(host);
@@ -207,7 +208,11 @@ export async function createBrowser({
         generations.set(generation, names);
         if (names.has(name)) return;
         names.add(name);
-        if (committed.host === host && committed.generation === generation) notify(lifecycleListeners, name);
+        if (committed.host === host && committed.generation === generation) {
+          if (name === "load" && sparePreparation?.host === host && sparePreparation.generation === generation)
+            armSparePreparation(sparePreparation, 1_000);
+          notify(lifecycleListeners, name);
+        }
       },
     });
     return host;
@@ -232,12 +237,45 @@ export async function createBrowser({
 
   function prepareSpare() {
     if (!spareRenderer || closed || spare) return;
-    spare = createHost();
-    spare.start().catch(() => {
-      spare = null;
+    const preparing = createHost();
+    spare = preparing;
+    preparing.start().catch(() => {
+      // An acquired spare may fail after its successor has been scheduled.
+      // Only this host owns its slot; never clear a newer spare's reference.
+      if (spare === preparing) {
+        spare = null;
+        preparing.close();
+      }
     });
   }
 
+  function cancelSparePreparation() {
+    if (sparePreparation) clearTimeout(sparePreparation.timer);
+    sparePreparation = null;
+  }
+
+  function armSparePreparation(request, delay) {
+    clearTimeout(request.timer);
+    request.timer = setTimeout(() => {
+      if (sparePreparation !== request) return;
+      sparePreparation = null;
+      if (current === request.host && committed.host === request.host
+        && committed.generation === request.generation) prepareSpare();
+    }, delay);
+    request.timer.unref?.();
+  }
+
+  function scheduleSparePreparation(host, generation) {
+    cancelSparePreparation();
+    if (!spareRenderer || closed || spare || host !== current) return;
+    const request = { host, generation, timer: null };
+    sparePreparation = request;
+    // Delay after load, rather than competing with the new page's initial
+    // scripts/layout. This is not CPU-idle detection. A bounded fallback
+    // still warms a spare for pages whose load event never arrives.
+    armSparePreparation(request, reachedLifecycle(host, generation).has("load") ? 1_000 : 30_000);
+  }
+
   /** The renderer for a URL's origin, swapping processes on an origin change. */
   async function rendererFor(url) {
     let key = originKey(url);
@@ -264,7 +302,6 @@ export async function createBrowser({
     current = next;
     currentKey = key;
     previous?.close();
-    prepareSpare();
     return current;
   }
 
@@ -345,12 +382,14 @@ export async function createBrowser({
     selectRenderer = url => rendererFor(url, { qmlHost });
     // qml handle end
 
+    cancelSparePreparation();
     const host = invoke ? current : await selectRenderer(document.url);
     let generation;
     try {
       generation = await (invoke ?? ((method, ...params) => host.call(method, ...params)))("loadDocument", document);
     } finally { documentReady.get(host)?.resolve(); }
     committed = { host, generation };
+    scheduleSparePreparation(host, generation);
     for (const name of reachedLifecycle(host, generation)) notify(lifecycleListeners, name);
     writeLog("navigation", `${document.url}: first paint in ${Math.round(performance.now() - fetched)}ms`);
   }
@@ -502,7 +541,7 @@ export async function createBrowser({
     press: (key, options) => call("press", key, options),
     type: (text) => call("type", text),
     scrollOffset: () => composite("scrollOffset"),
-    /** Calls `listener()` whenever what the viewport shows changes; returns an unsubscribe function. */
+    /** Calls `listener(frame?)` when the viewport changes, with its measured scroll offset when available. */
     onFrame(listener) {
       frameListeners.add(listener);
       return () => frameListeners.delete(listener);
@@ -573,6 +612,7 @@ export async function createBrowser({
     },
     close() {
       closed = true;
+      cancelSparePreparation();
       current?.close();
       spare?.close();
       current = null;