buninu-browser 0.0.2

package/lib/headless-shell.js

@@ -0,0 +1,362 @@
+/**
+ * Headless shell controller.
+ *
+ * Owns the CDP endpoint, navigation history, and all network access. Page
+ * content (DOM, style, layout, raster, page JavaScript) lives in a renderer
+ * subprocess driven through `RendererHost`; the controller never parses or
+ * runs page content itself.
+ *
+ * Sandbox flags: `--no-sandbox` is accepted for Chromium compatibility (casty
+ * always passes it) but ignored. Only `--dangerously-allow-host-js` relaxes
+ * the renderer sandbox, for every page.
+ */
+import { CdpServer } from "./cdp-server.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";
+
+/** Opt-in phone presentation: mobile user agent and touch media features. */
+export const MOBILE = "--mobile";
+
+export const DANGEROUSLY_ALLOW_HOST_JS = "--dangerously-allow-host-js";
+
+export async function runHeadlessShell(args = Bun.argv.slice(2)) {
+  installLog(logFileFromEnv());
+  const allowHostJs = args.includes(DANGEROUSLY_ALLOW_HOST_JS);
+  if (args.includes("--no-sandbox")) {
+    console.error(`buninu-browser: --no-sandbox is ignored; use ${DANGEROUSLY_ALLOW_HOST_JS} to disable the page sandbox`);
+  }
+  if (allowHostJs) {
+    console.error(`buninu-browser: WARNING ${DANGEROUSLY_ALLOW_HOST_JS}: page scripts are not sandboxed`);
+  }
+
+  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)}`);
+
+  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`);
+
+  const shutdown = () => {
+    server.stop(true);
+    browser.close();
+    process.exit(0);
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+  return server;
+}
+
+/**
+ * The browser behind the CDP endpoint: navigation, history, the network
+ * service, and one renderer process per origin.
+ *
+ * Every document is committed in a renderer bound to its origin (the final
+ * URL after redirects); a cross-origin navigation swaps to a fresh process
+ * and closes the old one. A spare renderer is kept warm so the swap does
+ * 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
+ */
+export async function createBrowser({
+  allowHostJs = false, spareRenderer = true, network = new NetworkService(), rendererTimeout = 30_000, mobile = false,
+} = {}) {
+  // --mobile fixes the user agent for page requests and navigator.userAgent.
+  if (mobile) network.userAgent = MOBILE_USER_AGENT;
+  const history = [{ url: "about:blank", x: 0, y: 0 }];
+  let historyIndex = 0;
+  let currentUrl = "about:blank";
+  let current = null;
+  let currentKey = null;
+  let spare = null;
+  let closed = false;
+  // 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();
+  // The committed document: its renderer and load generation. Lifecycle
+  // messages can arrive before loadDocument returns, so each host records
+  // what every generation has reached.
+  let committed = { host: null, generation: null };
+  const lifecycleSeen = new WeakMap();
+
+  function reachedLifecycle(host, generation) {
+    return lifecycleSeen.get(host)?.get(generation) ?? new Set();
+  }
+
+  function notify(listeners, ...args) {
+    for (const listener of listeners) {
+      try {
+        listener(...args);
+      } catch (error) {
+        console.error(`buninu-browser: listener failed: ${error?.message ?? error}`);
+      }
+    }
+  }
+
+  function createHost() {
+    const host = new RendererHost({
+      network,
+      timeout: rendererTimeout,
+      args: [...(allowHostJs ? [DANGEROUSLY_ALLOW_HOST_JS] : []), ...(mobile ? [MOBILE_FLAG] : [])],
+      // A replacement renderer starts blank; bring the current page back.
+      onRestart: async (invoke) => {
+        await replayState(invoke);
+        await load(currentUrl, invoke);
+      },
+      // Only the renderer showing the current page may navigate it.
+      onNavigate: (url) => {
+        if (host !== current) return;
+        navigate(url).catch((error) => console.error(`buninu-browser: navigation failed: ${error.message}`));
+      },
+      onFrame: () => {
+        if (host === current) notify(frameListeners);
+      },
+      onLifecycle: (name, generation) => {
+        let generations = lifecycleSeen.get(host);
+        if (!generations) lifecycleSeen.set(host, generations = new Map());
+        // Only the latest few generations matter.
+        if (!generations.has(generation) && generations.size >= 8) generations.delete(generations.keys().next().value);
+        const names = generations.get(generation) ?? new Set();
+        generations.set(generation, names);
+        if (names.has(name)) return;
+        names.add(name);
+        if (committed.host === host && committed.generation === generation) notify(lifecycleListeners, name);
+      },
+    });
+    return host;
+  }
+
+  // With --mobile a viewport wider than a phone is laid out at phone width
+  // and scaled up by `pageScale`, so frames keep the client's pixel size and
+  // client coordinates are divided by it.
+  const pageScale = () => mobile && viewport.width > MOBILE_LAYOUT_WIDTH ? viewport.width / MOBILE_LAYOUT_WIDTH : 1;
+
+  function resizeArguments() {
+    const scale = pageScale();
+    if (scale === 1) return [viewport.width, viewport.height, viewport.deviceScaleFactor, 1];
+    return [MOBILE_LAYOUT_WIDTH, viewport.height / scale, viewport.deviceScaleFactor * scale, scale];
+  }
+
+  async function replayState(invoke) {
+    await invoke("resize", ...resizeArguments());
+    if (userAgent) await invoke("setUserAgent", userAgent);
+  }
+
+  function prepareSpare() {
+    if (!spareRenderer || closed || spare) return;
+    spare = createHost();
+    spare.start().catch(() => {
+      spare = null;
+    });
+  }
+
+  /** The renderer for a URL's origin, swapping processes on an origin change. */
+  async function rendererFor(url) {
+    const key = originKey(url);
+    if (current && key === currentKey) return current;
+    const next = spare ?? createHost();
+    spare = null;
+    await next.start();
+    await replayState((method, ...params) => next.call(method, ...params));
+    const previous = current;
+    current = next;
+    currentKey = key;
+    previous?.close();
+    prepareSpare();
+    return current;
+  }
+
+  const call = (method, ...params) => current.call(method, ...params);
+
+  /**
+   * 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) {
+    const started = performance.now();
+    currentUrl = url;
+    let document;
+    if (url === "about:blank") {
+      document = { url };
+    } else {
+      try {
+        const target = new URL(url);
+        const response = ["http:", "https:"].includes(target.protocol)
+          ? await network.navigate(target.href)
+          : await localDocument(target);
+        document = {
+          url: response.url,
+          source: new TextDecoder().decode(response.body),
+          contentType: response.contentType || "text/html",
+          status: response.status,
+          statusText: response.statusText,
+          cookie: network.documentCookie(response.url),
+        };
+      } catch (error) {
+        document = { url, error: String(error) };
+      }
+    }
+    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`);
+    const host = invoke ? current : await rendererFor(document.url);
+    const generation = await (invoke ?? ((method, ...params) => host.call(method, ...params)))("loadDocument", document);
+    committed = { 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`);
+  }
+
+  // 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);
+
+  async function rememberScroll() {
+    const offset = await composite("scrollOffset");
+    Object.assign(history[historyIndex], { x: offset.x, y: offset.y });
+  }
+
+  async function navigate(url) {
+    const resolved = new URL(url, currentUrl).href;
+    // A javascript: URL runs in the current document; history does not change.
+    if (resolved.startsWith("javascript:")) {
+      await call("runJavaScriptURL", resolved);
+      return;
+    }
+    await rememberScroll();
+    if (withoutHash(resolved) === withoutHash(currentUrl)) {
+      currentUrl = resolved;
+    } else {
+      await load(resolved);
+    }
+    await call("showFragment", resolved);
+    history.splice(historyIndex + 1);
+    history.push({ url: resolved, x: 0, y: 0 });
+    historyIndex = history.length - 1;
+  }
+
+  async function traverseHistory(index) {
+    if (index < 0 || index >= history.length || index === historyIndex) return;
+    await rememberScroll();
+    historyIndex = index;
+    const entry = history[index];
+    await load(entry.url);
+    await call("scrollTo", entry.x, entry.y);
+  }
+
+  const context = {
+    navigate,
+    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());
+    },
+    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;
+    },
+    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"),
+    scroll: (deltaX, deltaY) => composite("scroll", deltaX / pageScale(), deltaY / pageScale()),
+    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. */
+    onFrame(listener) {
+      frameListeners.add(listener);
+      return () => frameListeners.delete(listener);
+    },
+    /** Calls `listener(name)` for DOMContentLoaded and load of the committed document. */
+    onLifecycle(listener) {
+      lifecycleListeners.add(listener);
+      return () => lifecycleListeners.delete(listener);
+    },
+    /** Lifecycle events the committed document has already reached. */
+    lifecycleState() {
+      return [...reachedLifecycle(committed.host, committed.generation)];
+    },
+    async click(x, y) {
+      const href = await call("click", x / pageScale(), y / pageScale());
+      if (typeof href !== "string") return null;
+      await navigate(href);
+      return { url: href, title: await call("title") };
+    },
+    evaluate: (expression) => call("evaluate", String(expression)),
+    cdp() {
+      return {};
+    },
+  };
+
+  await rendererFor("about:blank");
+  await current.call("loadDocument", { url: "about:blank" });
+
+  return {
+    context,
+    network,
+    get sandbox() {
+      return current?.sandbox ?? null;
+    },
+    /** Diagnostics: the process currently rendering the page, and the warm spare. */
+    get rendererPid() {
+      return current?.pid ?? null;
+    },
+    get sparePid() {
+      return spare?.pid ?? null;
+    },
+    close() {
+      closed = true;
+      current?.close();
+      spare?.close();
+      current = null;
+      spare = null;
+    },
+  };
+}
+
+/** Process-isolation key: the origin for http(s), one shared key for opaque origins. */
+function originKey(url) {
+  try {
+    const target = new URL(url);
+    return ["http:", "https:"].includes(target.protocol) ? target.origin : "opaque";
+  } catch {
+    return "opaque";
+  }
+}
+
+/** data: (and other non-network) documents are read locally without cookies. */
+async function localDocument(url) {
+  const response = await fetch(url);
+  return {
+    url: url.href,
+    status: response.status,
+    statusText: response.statusText,
+    contentType: response.headers.get("content-type") ?? "text/html",
+    body: new Uint8Array(await response.arrayBuffer()),
+  };
+}
+
+function withoutHash(href) {
+  const copy = new URL(href);
+  copy.hash = "";
+  return copy.href;
+}

package/lib/input/hit-test.js

@@ -0,0 +1,78 @@
+const INTERACTIVE_TAGS = new Set(["A", "BUTTON", "INPUT", "SELECT", "SUMMARY", "TEXTAREA", "VIDEO"]);
+
+export function interactiveRegions(tree, layout, scroll = { x: 0, y: 0 }, viewport = {}) {
+  const regions = [];
+  const byElement = new Map();
+
+  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;
+      const top = fragment.y - scroll.y;
+      const left = run.x - scroll.x;
+      const right = left + run.width;
+      const bottom = top + fragment.height;
+      if (right <= 0 || bottom <= 0 || left >= (viewport.width ?? Infinity) || top >= (viewport.height ?? Infinity)) {
+        continue;
+      }
+      const rect = Object.freeze({ left, top, right, bottom, width: run.width, height: fragment.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),
+  }));
+}
+
+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;
+}
+
+/** Returns the content-coordinate bounds contributed by an element's text descendants. */
+export function elementBounds(tree, layout, element) {
+  const rects = [];
+  for (const fragment of layout.fragments) {
+    for (const run of fragment.runs) {
+      const renderNode = tree.nodesById.get(run.nodeId);
+      const owner = renderNode?.domNode?.nodeType === 1
+        ? renderNode.domNode
+        : renderNode?.domNode?.parentElement;
+      if (!owner || (owner !== element && !element.contains(owner))) continue;
+      rects.push({
+        left: run.x,
+        top: fragment.y,
+        right: run.x + run.width,
+        bottom: fragment.y + fragment.height,
+      });
+    }
+  }
+  if (!rects.length) return null;
+  const left = Math.min(...rects.map((rect) => rect.left));
+  const top = Math.min(...rects.map((rect) => rect.top));
+  const right = Math.max(...rects.map((rect) => rect.right));
+  const bottom = Math.max(...rects.map((rect) => rect.bottom));
+  return Object.freeze({ left, top, right, bottom, width: right - left, height: bottom - top });
+}
+
+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")) {
+      return current;
+    }
+  }
+  return null;
+}

package/lib/layout/scroll-viewport.js

@@ -0,0 +1,53 @@
+export class ScrollViewport {
+  width;
+  height;
+  contentWidth = 0;
+  contentHeight = 0;
+  x = 0;
+  y = 0;
+
+  constructor(width, height) {
+    this.resize(width, height);
+  }
+
+  resize(width, height) {
+    this.width = dimension(width);
+    this.height = dimension(height);
+    this.#clamp();
+  }
+
+  setContentSize(width, height) {
+    this.contentWidth = dimension(width);
+    this.contentHeight = dimension(height);
+    this.#clamp();
+  }
+
+  scrollBy(deltaX = 0, deltaY = 0) {
+    return this.scrollTo(this.x + finite(deltaX), this.y + finite(deltaY));
+  }
+
+  scrollTo(x = this.x, y = this.y) {
+    const previousX = this.x;
+    const previousY = this.y;
+    this.x = clamp(finite(x), 0, Math.max(0, this.contentWidth - this.width));
+    this.y = clamp(finite(y), 0, Math.max(0, this.contentHeight - this.height));
+    return this.x !== previousX || this.y !== previousY;
+  }
+
+  #clamp() {
+    this.scrollTo(this.x, this.y);
+  }
+}
+
+function dimension(value) {
+  return Math.max(0, finite(value));
+}
+
+function finite(value) {
+  return Number.isFinite(Number(value)) ? Number(value) : 0;
+}
+
+function clamp(value, minimum, maximum) {
+  return Math.min(maximum, Math.max(minimum, value));
+}
+