buninu-browser 0.1.0 → 0.2.0

package/lib/document-types.js

@@ -0,0 +1,308 @@
+/**
+ * What a top-level response looks like in the viewport. HTML is shown as
+ * itself; anything else gets a small generated HTML document, as browsers do
+ * for "standalone" resources (HTML §7.4.4-§7.4.7):
+ *
+ * - images: the image alone on a dark background, centered and fitted to the
+ *   width (SVG inline, other formats as a data: URL so they are not fetched
+ *   twice);
+ * - video and audio: a <video> or <audio> element for the URL on the same
+ *   background, with the file's name and type under it;
+ * - the formats bunmsh's `serve` previews, handled the way it does: Markdown
+ *   rendered with Bun.markdown.html, and JSON, JSON5, JSONC, JSON Lines, YAML,
+ *   TOML and XML parsed with Bun's parsers and printed as highlighted JSON,
+ *   under a "Pretty-print" checkbox that is on by default and, unticked,
+ *   shows the text as sent;
+ * - everything else, whatever its bytes: the text in a <pre>. There is no
+ *   "cannot be shown" page (see AGENTS.md).
+ *
+ * Large files would stall layout (on a phone, 1 MB of text takes seconds and
+ * 4 MB never finished): past DISPLAY_LIMIT only the start of the text is
+ * shown, and past PRETTY_LIMIT the preview is skipped for the text, each
+ * with a bar at the top that says so and points to casty's `download`.
+ *
+ * The bytes kept for downloads are the response's own, not this HTML. Text is
+ * decoded with the Content-Type charset, UTF-8 when there is none.
+ */
+
+const HTML_TYPES = new Set(["text/html", "application/xhtml+xml"]);
+// Measured on a phone: 256 KiB of text lays out in about 2 s; a 32 KiB
+// preview (highlighted JSON, many spans) in about 2.5 s.
+export const DISPLAY_LIMIT = 256 * 1024;
+export const PRETTY_LIMIT = 32 * 1024;
+
+// From bunmsh serve.js (MIT, same author): the formats it previews, by file
+// extension, with its parser names, pretty() and highlightJson().
+const PARSERS = new Map([
+  ["json", { name: "JSON.parse", parse: JSON.parse }],
+  ["json5", { name: "Bun.JSON5.parse", parse: Bun.JSON5.parse }],
+  ["jsonc", { name: "Bun.JSONC.parse", parse: Bun.JSONC.parse }],
+  ["jsonl", { name: "Bun.JSONL.parse", parse: Bun.JSONL.parse }],
+  ["ndjson", { name: "Bun.JSONL.parse", parse: Bun.JSONL.parse }],
+  ["yaml", { name: "Bun.YAML.parse", parse: Bun.YAML.parse }],
+  ["yml", { name: "Bun.YAML.parse", parse: Bun.YAML.parse }],
+  ["toml", { name: "Bun.TOML.parse", parse: Bun.TOML.parse }],
+]);
+if (typeof Bun.XML?.parse === "function") {
+  PARSERS.set("xml", { name: "Bun.XML.parse", parse: Bun.XML.parse });
+}
+const MARKDOWN = "Bun.markdown.html";
+
+// A URL without one of those extensions: its Content-Type names the format.
+const EXTENSION_BY_TYPE = new Map([
+  ["text/markdown", "md"], ["text/x-markdown", "md"],
+  ["application/json", "json"], ["text/json", "json"], ["application/json5", "json5"], ["application/jsonc", "jsonc"],
+  ["application/jsonl", "jsonl"], ["application/x-ndjson", "ndjson"], ["application/jsonlines", "jsonl"],
+  ["text/yaml", "yaml"], ["application/yaml", "yaml"], ["application/x-yaml", "yaml"], ["text/x-yaml", "yaml"],
+  ["application/toml", "toml"], ["text/x-toml", "toml"],
+  ["application/xml", "xml"], ["text/xml", "xml"],
+]);
+
+/** "md", a PARSERS key, or null: what bunmsh serve would preview this as. */
+function previewKind(name, type) {
+  const byName = extension(name);
+  if (byName === "md" || PARSERS.has(byName)) return byName;
+  const byType = EXTENSION_BY_TYPE.get(type) ?? (type.endsWith("+json") ? "json" : type.endsWith("+xml") ? "xml" : null);
+  return byType === "md" || PARSERS.has(byType) ? byType : null;
+}
+
+/**
+ * @param {{ url: string, contentType?: string, body: Uint8Array }} response
+ * @returns {{ source: string, contentType: string }}
+ */
+export function displayDocument({ url, contentType = "", body }) {
+  const { type, charset } = parseContentType(contentType);
+  const name = fileName(url);
+  if (HTML_TYPES.has(type) || (type === "" && looksLikeHtml(body))) {
+    return { source: decode(body, charset), contentType: contentType || "text/html" };
+  }
+  if (type === "image/svg+xml") return html(name, IMAGE_STYLE, `<div class="image">${stripProlog(decode(body, charset))}</div>`);
+  if (type.startsWith("image/")) {
+    const src = `data:${type};base64,${Buffer.from(body).toString("base64")}`;
+    return html(name, IMAGE_STYLE, `<div class="image"><img src="${src}" alt="${Bun.escapeHTML(name)}"></div>`);
+  }
+  const media = mediaKind(type, name);
+  if (media) return mediaDocument(url, name, type || media, media, body.byteLength);
+  const kind = previewKind(name, type);
+  if (kind && body.byteLength <= PRETTY_LIMIT) return previewDocument(url, name, kind, decode(body, charset));
+  // Everything else is shown as text, whatever the bytes are: no file is unviewable.
+  const note = kind
+    ? `Too large to pretty-print quickly (${formatSize(body.byteLength)})${body.byteLength > DISPLAY_LIMIT ? `; showing the first ${formatSize(DISPLAY_LIMIT)}` : ""}.`
+    : body.byteLength > DISPLAY_LIMIT ? `Large file (${formatSize(body.byteLength)}); showing the first ${formatSize(DISPLAY_LIMIT)}.` : null;
+  const shown = body.byteLength > DISPLAY_LIMIT ? body.subarray(0, DISPLAY_LIMIT) : body;
+  const bar = `<div class="bar"><span>${note ? `${note} The whole file: casty's <code>download</code> (Ctrl+E).` : ""}</span>${downloadButton(url)}</div>`;
+  return html(name, TEXT_STYLE, `${bar}<pre>${Bun.escapeHTML(decode(shown, charset))}</pre>`);
+}
+
+/** Built-in audio diagnostics page; CSS keys work without SVG or page scripts. */
+export function audioDemoDocument() {
+  const whites = [["A4", 69], ["B4", 71], ["C5", 72], ["D5", 74],
+    ["E5", 76], ["F5", 77], ["G5", 79], ["A5", 81]]
+    .map(([name, note]) => `<button type="button" class="white-key" data-piano-note="${note}"><span>${name}</span></button>`).join("");
+  const blacks = [["A♯4", 70, "8.75"], ["C♯5", 73, "33.75"], ["D♯5", 75, "46.25"],
+    ["F♯5", 78, "71.25"], ["G♯5", 80, "83.75"]]
+    .map(([name, note, left]) => `<button type="button" class="black-key" data-piano-note="${note}" style="left:${left}%"><span>${name}</span></button>`).join("");
+  const style = `:root { color-scheme: dark }
+body { margin: 0; min-height: 100vh; background: #151820; color: #f4f5f7; font: 15px sans-serif }
+.demo { max-width: 560px; margin: 0 auto; padding: 42px 18px 24px; text-align: center }
+h1 { margin: 0 0 8px; font-size: 24px }
+.note { color: #abb1c0; font-size: 13px; line-height: 1.5 }
+.keyboard { display: flex; position: relative; width: 100%; max-width: 420px; height: 150px; margin: 32px auto 20px; box-shadow: 0 8px 22px #0008 }
+.white-key { flex: 1; position: relative; box-sizing: border-box; padding: 0; border: 1px solid #6f7683; border-radius: 0 0 6px 6px; background: #f5f3ed; color: #2c3039; cursor: pointer; font: inherit }
+.white-key span { position: absolute; bottom: 9px; left: 0; right: 0; font-size: 12px }
+.black-key { position: absolute; z-index: 1; top: 0; width: 8.6%; height: 92px; padding: 0; border: 0; border-radius: 0 0 5px 5px; background: #262b35; box-shadow: 0 4px 5px #0008; color: #e8e8e8; cursor: pointer; font: inherit }
+.black-key span { position: absolute; bottom: 8px; left: 0; right: 0; font-size: 10px }
+input { box-sizing: border-box; width: 100%; max-width: 420px; padding: 10px 12px; border: 1px solid #858da0; border-radius: 7px; background: #222735; color: white; font: 15px sans-serif }
+input:focus { outline: 2px solid #90b4ff; outline-offset: 2px }`;
+  return html("Audio demo", style, `<main class="demo"><h1>Audio demo</h1>`
+    + `<p class="note">Tap a key, or click the field and play with Space, J, K and the LazyI keyboard bindings.</p>`
+    + `<div class="keyboard" aria-label="Piano keyboard">${whites}${blacks}</div>`
+    + `<input id="buninu-piano-input" type="text" autocomplete="off" placeholder="Play Piano · 彈鋼琴 · ピアノを弾く" aria-label="Play Piano">`
+    + `<p class="note">Space = A4 · J = B4 · K = C♯5</p></main>`);
+}
+
+function formatSize(bytes) {
+  return bytes >= 1024 * 1024 ? `${(bytes / 1024 / 1024).toFixed(1)} MB` : `${Math.round(bytes / 1024)} KB`;
+}
+
+// Media the renderer's decoder (wasmpeg's FFmpeg) handles: by type, or by
+// extension when the server's type says nothing.
+const VIDEO_TYPES = new Set(["application/ogg", "application/mp4", "application/x-matroska", "application/mxf"]);
+const VIDEO_EXTENSIONS = new Set(["mp4", "m4v", "mov", "webm", "mkv", "avi", "ogv", "ogg", "ts", "mts", "m2ts",
+  "mpg", "mpeg", "3gp", "3g2", "wmv", "flv", "mxf", "y4m"]);
+const AUDIO_EXTENSIONS = new Set(["mp3", "wav", "flac", "oga", "opus", "m4a", "aac", "wma", "aiff", "aif", "amr", "ac3", "mka"]);
+
+/** "video", "audio" or null. */
+function mediaKind(type, name) {
+  if (type.startsWith("video/") || VIDEO_TYPES.has(type)) return "video";
+  if (type.startsWith("audio/")) return "audio";
+  if (!["", "application/octet-stream", "binary/octet-stream"].includes(type)) return null;
+  const ext = extension(name);
+  return VIDEO_EXTENSIONS.has(ext) ? "video" : AUDIO_EXTENSIONS.has(ext) ? "audio" : null;
+}
+
+/** A media document (HTML §7.4.6): the element alone, playing the URL itself. */
+function mediaDocument(url, name, type, kind, size) {
+  const src = Bun.escapeHTML(url);
+  const about = `${Bun.escapeHTML(name)} (${Bun.escapeHTML(type)}, ${size} bytes)`;
+  const element = kind === "video"
+    ? `<video controls autoplay src="${src}"></video><p class="note">${about}. Click the video to play.</p>`
+    : `<audio controls src="${src}"></audio><p class="note">${about}. Click to play; `
+      + "sound goes to a PulseAudio server on 127.0.0.1:4713, such as jspulse.</p>";
+  const piano = kind === "audio" && (type === "audio/mpeg" || extension(name) === "mp3")
+    ? `<label class="piano">鋼琴 <input id="buninu-piano-input" type="text" autocomplete="off" placeholder="Space J K · F1–F12" aria-label="鋼琴鍵盤"></label>`
+    : "";
+  return html(name, IMAGE_STYLE, `${piano}<div class="image">${element}</div>`);
+}
+
+/** bunmsh serve's preview (its previewResponse), under a Pretty-print checkbox over the text as sent. */
+function previewDocument(url, name, kind, source) {
+  const raw = (hidden) => `<pre id="raw"${hidden ? " hidden" : ""}>${Bun.escapeHTML(source)}</pre>`;
+  const parser = PARSERS.get(kind);
+  const previewer = kind === "md" ? MARKDOWN : parser.name;
+  let formatted;
+  try {
+    formatted = kind === "md"
+      ? `<div id="formatted">${Bun.markdown.html(source, { headings: true })}</div>`
+      : `<pre id="formatted"><code>${highlightJson(pretty(parser.parse(source)))}</code></pre>`;
+  } catch (error) {
+    return html(`Cannot preview ${name}`, TEXT_STYLE, `<div class="bar"><span></span>${downloadButton(url)}</div><h1>Cannot preview ${Bun.escapeHTML(name)}</h1>`
+      + `<pre>${Bun.escapeHTML(error?.stack ?? String(error))}</pre>${raw(false)}`);
+  }
+  return html(`${name} — ${previewer}`, TEXT_STYLE, `<div class="bar"><span><label><input type="checkbox" id="pretty-print" checked> Pretty-print</label>`
+    + ` <span class="note">(${previewer})</span></span>${downloadButton(url)}</div>${formatted}${raw(true)}`
+    + `<script>(() => {
+  const box = document.getElementById("pretty-print");
+  const show = () => {
+    document.getElementById("formatted").hidden = !box.checked;
+    document.getElementById("raw").hidden = box.checked;
+  };
+  box.addEventListener("change", show);
+})();</script>`);
+}
+
+function downloadButton(url) {
+  return `<a class="download" href="${Bun.escapeHTML(url)}" download>Download</a>`;
+}
+
+// Centered in the viewport both ways, as browsers show a standalone image.
+const IMAGE_STYLE = `body { margin: 0; background: #0e0e0e }
+.image { min-height: 100vh; display: flex; align-items: center; justify-content: center }
+.image { flex-direction: column }
+.image img, .image svg { max-width: 100%; height: auto; background: white }
+.image video { max-width: 100% }
+.image .note { color: #bbb; font-family: sans-serif; font-size: 13px }
+.piano { position: fixed; z-index: 2; top: 8px; left: 8px; display: flex; align-items: center; gap: 5px; color: #eee; font: 13px sans-serif }
+.piano input { width: 128px; padding: 3px 5px; font: 13px sans-serif }`;
+// The link style and highlight colors are bunmsh serve's.
+const TEXT_STYLE = `:root { color-scheme: light dark }
+body { margin: 8px }
+a { color: inherit; text-decoration: none }
+pre { margin: 0; white-space: pre-wrap; overflow-wrap: anywhere; font-family: monospace }
+code { font: inherit }
+.bar { display: flex; justify-content: space-between; align-items: center; gap: 16px; font-family: sans-serif; margin-bottom: 8px }
+.download { margin-left: auto; padding: 4px 9px; border: 1px solid currentColor; border-radius: 4px; white-space: nowrap }
+.note { font-family: sans-serif; color: #666 }
+.json-statement { color: #b0005a }
+.json-string { color: #6b5d00 }
+.json-special { color: #087f5b }
+.json-number, .json-constant { color: #5f3dc4 }
+@media (prefers-color-scheme: dark) {
+  .json-statement { color: #f92672 }
+  .json-string { color: #e6db74 }
+  .json-special { color: #a6e22e }
+  .json-number, .json-constant { color: #ae81ff }
+}`;
+
+function html(title, style, body) {
+  return {
+    source: `<!doctype html><html><head><meta charset="utf-8"><title>${Bun.escapeHTML(title)}</title>`
+      + `<style>${style}</style></head><body>${body}</body></html>`,
+    contentType: "text/html",
+  };
+}
+
+// bunmsh serve.js pretty(): BigInts (TOML integers) keep their digits as "123n".
+const pretty = (value) => {
+  try {
+    return JSON.stringify(value, (_key, item) =>
+      typeof item === "bigint" ? `${item}n` : item, 2) ?? String(value);
+  } catch {
+    return Bun.inspect(value, { colors: false, depth: Infinity });
+  }
+};
+
+// bunmsh serve.js highlightJson(): statement keys, strings and escapes,
+// numbers, and true/false/null constants of the JSON pretty() emits.
+export const highlightJson = (source) => {
+  const input = String(source);
+  const token = /"(?:\\(?:u[\da-fA-F]{4}|.)|[^"\\])*"|-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?|\b(?:true|false|null)\b/g;
+  let output = "", cursor = 0, match;
+  const stringHtml = (value) => {
+    let html = "", offset = 0;
+    for (const escape of value.matchAll(/\\(?:u[\da-fA-F]{4}|.)/g)) {
+      html += Bun.escapeHTML(value.slice(offset, escape.index));
+      html += `<span class="json-special">${Bun.escapeHTML(escape[0])}</span>`;
+      offset = escape.index + escape[0].length;
+    }
+    return html + Bun.escapeHTML(value.slice(offset));
+  };
+  while ((match = token.exec(input))) {
+    output += Bun.escapeHTML(input.slice(cursor, match.index));
+    const value = match[0];
+    let end = token.lastIndex;
+    if (value.startsWith('"')) {
+      const propertyEnd = /^\s*:/.exec(input.slice(end));
+      if (propertyEnd) {
+        end += propertyEnd[0].length;
+        output += `<span class="json-statement">${Bun.escapeHTML(input.slice(match.index, end))}</span>`;
+      } else {
+        output += `<span class="json-string">${stringHtml(value)}</span>`;
+      }
+    } else if (value === "true" || value === "false" || value === "null") {
+      output += `<span class="json-constant">${value}</span>`;
+    } else {
+      output += `<span class="json-number">${value}</span>`;
+    }
+    cursor = end;
+    token.lastIndex = end;
+  }
+  return output + Bun.escapeHTML(input.slice(cursor));
+};
+
+export function parseContentType(value) {
+  const [type = "", ...parameters] = String(value).split(";");
+  const charset = parameters.map((part) => part.trim().match(/^charset=["']?([^"';]+)/i)?.[1]).find(Boolean) ?? null;
+  return { type: type.trim().toLowerCase(), charset };
+}
+
+function decode(body, charset) {
+  try {
+    return new TextDecoder(charset ?? "utf-8").decode(body);
+  } catch {
+    return new TextDecoder().decode(body);
+  }
+}
+
+function fileName(url) {
+  try {
+    const segment = new URL(url).pathname.split("/").filter(Boolean).pop() ?? "";
+    return decodeURIComponent(segment) || new URL(url).hostname || url;
+  } catch {
+    return String(url);
+  }
+}
+
+function extension(name) {
+  const dot = name.lastIndexOf(".");
+  return dot > 0 ? name.slice(dot + 1).toLowerCase() : "";
+}
+
+function stripProlog(svg) {
+  return svg.replace(/^\s*<\?xml[^>]*>\s*/i, "").replace(/<!DOCTYPE[^>]*>\s*/i, "");
+}
+
+function looksLikeHtml(body) {
+  const head = new TextDecoder().decode(body.subarray(0, 512)).trimStart().toLowerCase();
+  return head.startsWith("<!doctype html") || head.startsWith("<html") || head.startsWith("<head") || head.startsWith("<body") || head === "";
+}

package/lib/download-directory.js

@@ -0,0 +1,28 @@
+import { homedir } from "node:os";
+import { join, win32 } from "node:path";
+
+// Windows can move the Downloads known folder away from %USERPROFILE%. Query
+// its registered location through PowerShell so non-ASCII paths stay UTF-8.
+const WINDOWS_DOWNLOADS = [
+  "$OutputEncoding = [Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)",
+  "$key = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\User Shell Folders')",
+  "if ($key) { $path = $key.GetValue('{374DE290-123F-4565-9164-39C4925E467B}'); if ($path) { [Console]::Write([Environment]::ExpandEnvironmentVariables($path)) } }",
+].join("; ");
+
+function windowsDownloads() {
+  try {
+    const result = Bun.spawnSync({ cmd: ["powershell.exe", "-NoProfile", "-NonInteractive", "-Command", WINDOWS_DOWNLOADS],
+      stdout: "pipe", stderr: "ignore" });
+    return result.exitCode === 0 ? new TextDecoder().decode(result.stdout).trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+export function downloadsDirectory({ platform = process.platform, home = homedir(), queryWindows = windowsDownloads } = {}) {
+  if (platform === "win32") {
+    const known = queryWindows();
+    return known && win32.isAbsolute(known) ? known : win32.join(home, "Downloads");
+  }
+  return join(home, "Downloads");
+}

package/lib/download.js

@@ -0,0 +1,63 @@
+import { mkdir, open, unlink } from "node:fs/promises";
+import { extname, join } from "node:path";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { downloadsDirectory } from "./download-directory.js";
+
+export const DEFAULT_DOWNLOAD_DIR = downloadsDirectory();
+
+export function isAttachment(value) {
+  return /^\s*attachment\s*(?:;|$)/i.test(value ?? "");
+}
+
+export function suggestedFilename(url, disposition = "", attributeName = "") {
+  const encoded = /(?:^|;)\s*filename\*\s*=\s*(?:UTF-8''|utf-8'[^']*')([^;]+)/i.exec(disposition)?.[1];
+  const plain = /(?:^|;)\s*filename\s*=\s*(?:"([^"]*)"|([^;]*))/i.exec(disposition);
+  let name = "";
+  if (encoded) { try { name = decodeURIComponent(encoded.trim().replace(/^"|"$/g, "")); } catch {} }
+  if (!name) name = plain?.[1] ?? plain?.[2]?.trim() ?? attributeName;
+  if (!name) {
+    const target = new URL(url);
+    const segment = target.pathname.split("/").filter(Boolean).at(-1);
+    try { name = decodeURIComponent(segment ?? ""); } catch { name = segment ?? ""; }
+    if (!name) name = target.hostname || "download";
+  }
+  name = name.split(/[\\/]/).at(-1).replace(/[<>:"|?*\x00-\x1f\x7f]/g, "_").replace(/^\.+/, "_").replace(/[. ]+$/, "").slice(0, 200);
+  return name || "download";
+}
+
+/** Save a response stream or already held bytes without replacing an existing file. */
+export async function saveDownload({ url, disposition = "", attributeName = "", filename = null, body, dir = DEFAULT_DOWNLOAD_DIR }) {
+  await mkdir(dir, { recursive: true });
+  const name = filename ?? suggestedFilename(url, disposition, attributeName);
+  const extension = extname(name);
+  const stem = name.slice(0, name.length - extension.length);
+  let file;
+  let path;
+  for (let number = 1; ; number++) {
+    path = join(dir, number === 1 ? name : `${stem} (${number})${extension}`);
+    try { file = await open(path, "wx"); break; }
+    catch (error) { if (error.code !== "EEXIST") throw error; }
+  }
+  try {
+    let bytes = 0;
+    if (body instanceof Uint8Array) {
+      bytes = body.byteLength;
+      await file.writeFile(body);
+    } else if (body) {
+      const count = new Transform({ transform(chunk, _encoding, done) {
+        bytes += chunk.byteLength;
+        done(null, chunk);
+      } });
+      await pipeline(Readable.fromWeb(body), count, file.createWriteStream());
+    }
+    else await file.close();
+    return { path, name: path.slice(dir.length + 1), bytes };
+  } catch (error) {
+    await file.close().catch(() => {});
+    await unlink(path).catch(() => {});
+    throw error;
+  } finally {
+    await file.close().catch(() => {});
+  }
+}

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";
@@ -70,10 +73,12 @@ 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;
+  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;
@@ -84,6 +89,8 @@ export async function createBrowser({
   // 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 +111,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 +146,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);
@@ -184,22 +223,36 @@ export async function createBrowser({
    * 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,6 +261,7 @@ 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}`}`
@@ -228,7 +282,7 @@ export async function createBrowser({
     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 +290,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 +302,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,6 +323,14 @@ 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),
@@ -277,6 +350,22 @@ export async function createBrowser({
       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 +385,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() {