buninu-browser 0.1.0 → 0.2.1

package/lib/headless-shell.js

@@ -11,10 +11,13 @@
  * the renderer sandbox, for every page.
  */
 import { CdpServer } from "./cdp-server.js";
+import { DEFAULT_DOWNLOAD_DIR, isAttachment, saveDownload, suggestedFilename } from "./download.js";
+import { audioDemoDocument, displayDocument } from "./document-types.js";
 import { installLog, logFileFromEnv, writeLog } from "./log.js";
 import { NetworkService } from "./network/network-service.js";
 import { RendererHost } from "./renderer/host.js";
 import { MOBILE_FLAG, MOBILE_LAYOUT_WIDTH, MOBILE_USER_AGENT } from "./renderer/flags.js";
+import { DESKTOP_USER_AGENT } from "./user-agent.js";
 
 /** Opt-in phone presentation: mobile user agent and touch media features. */
 export const MOBILE = "--mobile";
@@ -34,15 +37,23 @@ export async function runHeadlessShell(args = Bun.argv.slice(2)) {
   const mobile = args.includes(MOBILE);
   if (mobile) console.error(`buninu-browser: ${MOBILE}: mobile user agent and touch media features; user agent overrides are ignored`);
 
-  const browser = await createBrowser({ allowHostJs, mobile });
-  const layerStatus = (layer) => layer?.installed ? "on" : `off (${layer?.reason})`;
-  console.error(`buninu-browser: renderer sandbox: seccomp ${layerStatus(browser.sandbox?.seccomp)}, `
-    + `ses ${layerStatus(browser.sandbox?.ses)}`);
-
+  // The endpoint opens while the first renderer starts: a client's first
+  // navigation fetches its document meanwhile.
+  const browser = await createBrowser({ allowHostJs, mobile, waitForRenderer: false });
   const portArgument = args.find((argument) => argument.startsWith("--remote-debugging-port="));
   const requestedPort = Number(portArgument?.slice("--remote-debugging-port=".length) ?? 9222);
   const server = CdpServer.create(browser.context).listen(requestedPort, "127.0.0.1");
   console.error(`DevTools listening on ws://127.0.0.1:${server.port}/devtools/browser/cdp-server`);
+  try {
+    await browser.ready;
+  } catch (error) {
+    server.stop(true);
+    browser.close();
+    throw error;
+  }
+  const layerStatus = (layer) => layer?.installed ? "on" : `off (${layer?.reason})`;
+  console.error(`buninu-browser: renderer sandbox: seccomp ${layerStatus(browser.sandbox?.seccomp)}, `
+    + `ses ${layerStatus(browser.sandbox?.ses)}`);
 
   const shutdown = () => {
     server.stop(true);
@@ -64,26 +75,38 @@ export async function runHeadlessShell(args = Bun.argv.slice(2)) {
  * not wait for CanvasKit and fonts to load. Site isolation is by origin
  * because no Public Suffix List is bundled to compute sites.
  *
- * @param {{ allowHostJs?: boolean, spareRenderer?: boolean, network?: NetworkService, rendererTimeout?: number }} options
+ * With `waitForRenderer: false` it returns before the first renderer is up
+ * (`ready` settles then): navigations fetch their documents meanwhile, and
+ * anything that needs a renderer waits for it.
+ *
+ * @param {{ allowHostJs?: boolean, spareRenderer?: boolean, network?: NetworkService, rendererTimeout?: number,
+ *   waitForRenderer?: boolean }} options
  */
 export async function createBrowser({
   allowHostJs = false, spareRenderer = true, network = new NetworkService(), rendererTimeout = 30_000, mobile = false,
+  waitForRenderer = true,
 } = {}) {
   // --mobile fixes the user agent for page requests and navigator.userAgent.
-  if (mobile) network.userAgent = MOBILE_USER_AGENT;
+  network.userAgent = mobile ? MOBILE_USER_AGENT : DESKTOP_USER_AGENT;
   const history = [{ url: "about:blank", x: 0, y: 0 }];
   let historyIndex = 0;
   let currentUrl = "about:blank";
+  // The current document's response as fetched (raw bytes), for downloads.
+  let resource = null;
   let current = null;
   let currentKey = null;
   let spare = null;
   let closed = false;
+  // Settles when the first renderer shows about:blank (assigned below).
+  let rendererReady = null;
   // Renderer-independent state replayed into every new renderer.
   const viewport = { width: 800, height: 600, deviceScaleFactor: 1 };
   let userAgent = null;
   // Listeners for frame and lifecycle notifications (the CDP server).
   const frameListeners = new Set();
   const lifecycleListeners = new Set();
+  const downloadListeners = new Set();
+  let downloadBehavior = { behavior: "allow", downloadPath: DEFAULT_DOWNLOAD_DIR, eventsEnabled: false };
   // The committed document: its renderer and load generation. Lifecycle
   // messages can arrive before loadDocument returns, so each host records
   // what every generation has reached.
@@ -104,6 +127,30 @@ export async function createBrowser({
     }
   }
 
+  async function download({ url, body, disposition = "", attributeName = "", totalBytes = 0 }) {
+    const guid = crypto.randomUUID();
+    const filename = suggestedFilename(url, disposition, attributeName);
+    if (downloadBehavior.eventsEnabled) notify(downloadListeners, "willBegin", { guid, url, suggestedFilename: filename });
+    if (downloadBehavior.behavior === "deny") {
+      if (downloadBehavior.eventsEnabled) notify(downloadListeners, "progress", { guid, state: "canceled", receivedBytes: 0, totalBytes });
+      return { downloaded: true };
+    }
+    try {
+      if (downloadBehavior.eventsEnabled) notify(downloadListeners, "progress", { guid, state: "inProgress", receivedBytes: 0, totalBytes });
+      const saved = await saveDownload({ url, body, disposition, attributeName,
+        filename: downloadBehavior.behavior === "allowAndName" ? guid : null, dir: downloadBehavior.downloadPath });
+      if (downloadBehavior.eventsEnabled) notify(downloadListeners, "progress", {
+        guid, state: "completed", receivedBytes: saved.bytes, totalBytes: totalBytes || saved.bytes, filePath: saved.path,
+      });
+      writeLog("download", `${url} -> ${saved.path}`);
+      return { downloaded: true, path: saved.path };
+    } catch (error) {
+      if (downloadBehavior.eventsEnabled) notify(downloadListeners, "progress", { guid, state: "canceled", receivedBytes: 0, totalBytes });
+      console.error(`buninu-browser: download failed: ${error?.message ?? error}`);
+      return { downloaded: true, error };
+    }
+  }
+
   function createHost() {
     const host = new RendererHost({
       network,
@@ -115,9 +162,17 @@ export async function createBrowser({
         await load(currentUrl, invoke);
       },
       // Only the renderer showing the current page may navigate it.
-      onNavigate: (url) => {
+      onNavigate: (url, downloadName, fragmentFrom) => {
+        if (host !== current) return;
+        if (fragmentFrom) {
+          recordFragment(url, fragmentFrom);
+          return;
+        }
+        navigate(url, { downloadName }).catch((error) => console.error(`buninu-browser: navigation failed: ${error.message}`));
+      },
+      onDownload: ({ url, name, data }) => {
         if (host !== current) return;
-        navigate(url).catch((error) => console.error(`buninu-browser: navigation failed: ${error.message}`));
+        void download({ url, body: data, attributeName: name, totalBytes: data.byteLength });
       },
       onFrame: () => {
         if (host === current) notify(frameListeners);
@@ -177,29 +232,57 @@ export async function createBrowser({
     return current;
   }
 
-  const call = (method, ...params) => current.call(method, ...params);
+  const call = async (method, ...params) => {
+    await rendererReady;
+    return current.call(method, ...params);
+  };
+
+  /**
+   * Applies viewport or user agent state the renderer is told about. Before
+   * the first renderer is up there is nothing to wait for: it starts with the
+   * state (replayState), and the latest state is applied again once it is.
+   */
+  function applyState(method, args) {
+    if (current) return current.call(method, ...args());
+    rendererReady.then(() => current?.call(method, ...args())).catch(() => {});
+    return undefined;
+  }
 
   /**
    * Fetches a top-level document, then commits it in the renderer for its
    * final origin. `invoke` pins the renderer (used when restoring a
    * restarted renderer).
    */
-  async function load(url, invoke = null) {
+  async function load(url, invoke = null, downloadName = null) {
     const started = performance.now();
-    currentUrl = url;
+    if (downloadName !== null && resource && withoutHash(url) === withoutHash(resource.url)) {
+      return download({ url: resource.url, body: resource.body, attributeName: downloadName, totalBytes: resource.body.byteLength });
+    }
     let document;
     if (url === "about:blank") {
       document = { url };
+    } else if (url === "about:audio") {
+      document = { url, ...audioDemoDocument() };
     } else {
       try {
         const target = new URL(url);
         const response = ["http:", "https:"].includes(target.protocol)
-          ? await network.navigate(target.href)
+          ? await network.navigate(target.href, { onResponse: (raw, finalUrl) => {
+            if (!raw.ok || (downloadName === null && !isAttachment(raw.headers.get("content-disposition")))) return null;
+            return download({ url: finalUrl, body: raw.body, disposition: raw.headers.get("content-disposition") ?? "",
+              attributeName: downloadName ?? "", totalBytes: Number(raw.headers.get("content-length")) || 0 });
+          } })
           : await localDocument(target);
+        if (response.downloaded) return response;
+        if (downloadName !== null) return download({ url: response.url, body: response.body,
+          attributeName: downloadName, totalBytes: response.body.byteLength });
+        resource = { url: response.url, contentType: response.contentType ?? "", body: response.body };
+        // Non-HTML responses (images, JSON, TOML, text...) are shown through a generated page.
+        const shown = displayDocument({ url: response.url, contentType: response.contentType, body: response.body });
         document = {
           url: response.url,
-          source: new TextDecoder().decode(response.body),
-          contentType: response.contentType || "text/html",
+          source: shown.source,
+          contentType: shown.contentType,
           status: response.status,
           statusText: response.statusText,
           cookie: network.documentCookie(response.url),
@@ -208,10 +291,12 @@ export async function createBrowser({
         document = { url, error: String(error) };
       }
     }
+    if (document.url === "about:blank" || document.url === "about:audio" || document.error) resource = null;
     currentUrl = document.url;
     const fetched = performance.now();
     writeLog("navigation", `${url}: ${document.error ?? `HTTP ${document.status ?? 200}`}`
       + `${document.url === url ? "" : ` -> ${document.url}`} in ${Math.round(fetched - started)}ms`);
+    if (!invoke) await rendererReady;
     const host = invoke ? current : await rendererFor(document.url);
     const generation = await (invoke ?? ((method, ...params) => host.call(method, ...params)))("loadDocument", document);
     committed = { host, generation };
@@ -221,14 +306,19 @@ export async function createBrowser({
 
   // Screenshots and scrolling go to the compositor thread, so they are
   // answered even while the renderer's main thread is busy.
-  const composite = (method, ...params) => current.composite(method, ...params);
+  const composite = async (method, ...params) => {
+    await rendererReady;
+    return current.composite(method, ...params);
+  };
 
   async function rememberScroll() {
+    // Before the first renderer is up nothing has been shown or scrolled.
+    if (!current) return;
     const offset = await composite("scrollOffset");
     Object.assign(history[historyIndex], { x: offset.x, y: offset.y });
   }
 
-  async function navigate(url) {
+  async function navigate(url, { downloadName = null } = {}) {
     const resolved = new URL(url, currentUrl).href;
     // A javascript: URL runs in the current document; history does not change.
     if (resolved.startsWith("javascript:")) {
@@ -236,10 +326,11 @@ export async function createBrowser({
       return;
     }
     await rememberScroll();
-    if (withoutHash(resolved) === withoutHash(currentUrl)) {
+    if (downloadName === null && withoutHash(resolved) === withoutHash(currentUrl)) {
       currentUrl = resolved;
     } else {
-      await load(resolved);
+      const result = await load(resolved, null, downloadName);
+      if (result?.downloaded) return null;
     }
     await call("showFragment", resolved);
     history.splice(historyIndex + 1);
@@ -247,6 +338,16 @@ export async function createBrowser({
     historyIndex = history.length - 1;
   }
 
+  /** The renderer already navigated to a fragment of its document; only history changes. */
+  function recordFragment(url, from) {
+    if (withoutHash(url) !== withoutHash(currentUrl)) return;
+    Object.assign(history[historyIndex], { x: from.x, y: from.y });
+    currentUrl = url;
+    history.splice(historyIndex + 1);
+    history.push({ url, x: 0, y: 0 });
+    historyIndex = history.length - 1;
+  }
+
   async function traverseHistory(index) {
     if (index < 0 || index >= history.length || index === historyIndex) return;
     await rememberScroll();
@@ -258,25 +359,49 @@ export async function createBrowser({
 
   const context = {
     navigate,
+    setDownloadBehavior({ behavior = "allow", downloadPath = DEFAULT_DOWNLOAD_DIR, eventsEnabled = false } = {}) {
+      if (!["allow", "allowAndName", "default", "deny"].includes(behavior)) throw new TypeError(`Unsupported download behavior ${behavior}`);
+      downloadBehavior = { behavior, downloadPath, eventsEnabled: Boolean(eventsEnabled) };
+    },
+    onDownload(listener) {
+      downloadListeners.add(listener);
+      return () => downloadListeners.delete(listener);
+    },
     reload: () => load(currentUrl),
     goBack: () => traverseHistory(historyIndex - 1),
     goForward: () => traverseHistory(historyIndex + 1),
     resize(width, height, deviceScaleFactor = 1) {
       Object.assign(viewport, { width, height, deviceScaleFactor });
-      return call("resize", ...resizeArguments());
+      return applyState("resize", resizeArguments);
     },
     setUserAgent(value) {
       // With --mobile the phone user agent stays (casty, for one, overrides it with a desktop one).
       if (mobile) return undefined;
       userAgent = typeof value === "string" && value ? value : null;
       network.userAgent = userAgent;
-      return userAgent ? call("setUserAgent", userAgent) : undefined;
+      return userAgent ? applyState("setUserAgent", () => [userAgent]) : undefined;
     },
     screenshot: (options = {}) => composite("screenshot", {
       format: options.format === "jpeg" || options.format === "webp" ? options.format : "png",
       quality: Number.isFinite(options.quality) ? options.quality : 80,
     }),
     title: () => call("title"),
+    /**
+     * The document's response body as it arrived (CDP Page.getResourceContent),
+     * for the current document's URL with or without its fragment; else null.
+     */
+    resourceContent(url = currentUrl) {
+      if (!resource) return null;
+      let wanted;
+      try {
+        wanted = withoutHash(String(url));
+      } catch {
+        return null;
+      }
+      return wanted === withoutHash(resource.url) || wanted === withoutHash(currentUrl)
+        ? { url: resource.url, contentType: resource.contentType, body: resource.body }
+        : null;
+    },
     scroll: (deltaX, deltaY) => composite("scroll", deltaX / pageScale(), deltaY / pageScale()),
     press: (key, options) => call("press", key, options),
     type: (text) => call("type", text),
@@ -296,10 +421,15 @@ export async function createBrowser({
       return [...reachedLifecycle(committed.host, committed.generation)];
     },
     async click(x, y) {
-      const href = await call("click", x / pageScale(), y / pageScale());
+      const clicked = await call("click", x / pageScale(), y / pageScale());
+      const href = typeof clicked === "string" ? clicked : clicked?.url;
       if (typeof href !== "string") return null;
-      await navigate(href);
-      return { url: href, title: await call("title") };
+      if (clicked.fragmentFrom) {
+        recordFragment(href, clicked.fragmentFrom);
+        return { url: href, title: await call("title") };
+      }
+      const result = await navigate(href, { downloadName: typeof clicked === "object" ? clicked.download ?? null : null });
+      return result === null ? null : { url: href, title: await call("title") };
     },
     evaluate: (expression) => call("evaluate", String(expression)),
     cdp() {
@@ -307,12 +437,21 @@ export async function createBrowser({
     },
   };
 
-  await rendererFor("about:blank");
-  await current.call("loadDocument", { url: "about:blank" });
+  // The spare starts with the first renderer rather than after it, ready
+  // for the first navigation to an origin.
+  rendererReady = (async () => {
+    const first = rendererFor("about:blank");
+    prepareSpare();
+    await first;
+    await current.call("loadDocument", { url: "about:blank" });
+  })();
+  if (waitForRenderer) await rendererReady;
+  else rendererReady.catch(() => {}); // the caller awaits `ready`
 
   return {
     context,
     network,
+    ready: rendererReady,
     get sandbox() {
       return current?.sandbox ?? null;
     },

package/lib/input/hit-test.js

@@ -1,14 +1,19 @@
-const INTERACTIVE_TAGS = new Set(["A", "BUTTON", "INPUT", "SELECT", "SUMMARY", "TEXTAREA", "VIDEO"]);
+const INTERACTIVE_TAGS = new Set(["A", "AUDIO", "BUTTON", "INPUT", "LABEL", "SELECT", "SUMMARY", "TEXTAREA", "VIDEO"]);
+// Form controls and labels are hit over their whole box, not only where text
+// is drawn (an unchecked checkbox or an empty field has none; a block label
+// is clickable beside its text).
+const CONTROL_TAGS = new Set(["AUDIO", "BUTTON", "INPUT", "LABEL", "SELECT", "TEXTAREA"]);
 
 export function interactiveRegions(tree, layout, scroll = { x: 0, y: 0 }, viewport = {}) {
   const regions = [];
   const byElement = new Map();
+  const hittable = hitTestable(tree);
 
   for (const fragment of layout.fragments) {
     for (const run of fragment.runs) {
       const renderNode = tree.nodesById.get(run.nodeId);
       const element = closestInteractive(renderNode?.domNode);
-      if (!element) continue;
+      if (!element || !hittable(renderNode)) continue;
       const top = fragment.y - scroll.y;
       const left = run.x - scroll.x;
       const right = left + run.width;
@@ -27,19 +32,43 @@ export function interactiveRegions(tree, layout, scroll = { x: 0, y: 0 }, viewpo
     }
   }
 
+  for (const box of layout.boxes ?? []) {
+    const renderNode = tree.nodesById.get(box.nodeId);
+    const element = renderNode?.domNode;
+    if (!element || element.nodeType !== 1 || !CONTROL_TAGS.has(element.tagName) || !hittable(renderNode)) continue;
+    const top = box.y - scroll.y;
+    const left = box.x - scroll.x;
+    const right = left + box.width;
+    const bottom = top + box.height;
+    if (box.width <= 0 || box.height <= 0 || right <= 0 || bottom <= 0
+      || left >= (viewport.width ?? Infinity) || top >= (viewport.height ?? Infinity)) {
+      continue;
+    }
+    const rect = Object.freeze({ left, top, right, bottom, width: box.width, height: box.height });
+    let region = byElement.get(element);
+    if (!region) {
+      region = { element, rects: [] };
+      byElement.set(element, region);
+      regions.push(region);
+    }
+    region.rects.push(rect);
+  }
+
   return regions.map((region) => Object.freeze({
     element: region.element,
     rects: Object.freeze(region.rects),
   }));
 }
 
+/** The innermost interactive element under a point (a checkbox before its label). */
 export function hitTest(tree, layout, x, y, scroll, viewport) {
-  for (const region of interactiveRegions(tree, layout, scroll, viewport)) {
-    if (region.rects.some((rect) => x >= rect.left && x < rect.right && y >= rect.top && y < rect.bottom)) {
-      return region;
-    }
-  }
-  return null;
+  const hits = interactiveRegions(tree, layout, scroll, viewport).map((region) => ({
+    ...region,
+    area: Math.min(...region.rects.filter((rect) => x >= rect.left && x < rect.right && y >= rect.top && y < rect.bottom)
+      .map((rect) => rect.width * rect.height)),
+  })).filter((region) => Number.isFinite(region.area));
+  const deepest = hits.filter((region) => !hits.some((other) => other !== region && region.element.contains(other.element)));
+  return deepest.sort((left, right) => left.area - right.area)[0] ?? null;
 }
 
 /** Returns the content-coordinate bounds contributed by an element's text descendants. */
@@ -68,6 +97,26 @@ export function elementBounds(tree, layout, element) {
   return Object.freeze({ left, top, right, bottom, width: right - left, height: bottom - top });
 }
 
+/**
+ * Whether a render node takes clicks: not when its element is
+ * visibility: hidden or pointer-events: none (both inherited, so a visible
+ * or pointer-events: auto descendant still does). Text uses its element's style.
+ */
+function hitTestable(tree) {
+  const styles = new Map();
+  for (const node of tree.nodesById.values()) {
+    if (node.domNode?.nodeType === 1 && node.style && !node.pseudo && !styles.has(node.domNode)) {
+      styles.set(node.domNode, node.style);
+    }
+  }
+  return (renderNode) => {
+    const domNode = renderNode?.domNode;
+    const element = domNode?.nodeType === 1 ? domNode : domNode?.parentElement;
+    const style = (renderNode?.pseudo ? renderNode.style : null) ?? styles.get(element);
+    return !style || (style.visibility !== "hidden" && style.pointerEvents !== "none");
+  };
+}
+
 function closestInteractive(node) {
   for (let current = node?.nodeType === 1 ? node : node?.parentElement; current; current = current.parentElement) {
     if (INTERACTIVE_TAGS.has(current.tagName) || current.hasAttribute("onclick") || current.hasAttribute("tabindex")) {