buninu-browser 0.1.0 → 0.2.1

package/AGENTS.md

@@ -7,6 +7,23 @@
   * Specifically, able to work with ../casty through CDP is an important goal
 - Only use Bun FFI to dlopen libc when other methods are clearly not enough
 
+## Implementing the browser
+- Do not treat any website specially when refining browser features like layout css js. Fix the actual problem that all websites can benefit from.
+- If you don't know how to fix a specific bug, look at ../chromium implementation but don't copy LGPL code.
+
+## Viewing files
+- No file is unviewable: every response the browser navigates to must show something, never a "cannot be shown" page
+  * HTML is shown as itself; images and video/audio get a generated page like Chromium's standalone image and media documents
+  * The formats bunmsh `serve` previews (md, json, json5, jsonc, jsonl, ndjson, yaml, yml, toml, xml) get its preview under a "Pretty-print" checkbox, checked by default; unchecked shows the raw text
+  * Everything else, binary included, is shown as text
+  * Large files must not stall the renderer: past a size limit only their start is shown (and previews fall back to the text), with a bar at the top that says so and points to `download`
+  * See `lib/document-types.js`; `download` still saves the response's original bytes
+
+## Screenshots
+- Use the headless CLI to inspect rendered pages: `bun index.js --headless --screenshot=/tmp/page.png --window-size=1280,800 URL` (or `bun buninu-browser.js ...`). It writes the image and exits; inspect it with the image viewer.
+- Capture waits for the page's `load` event. For content that appears later, add `--screenshot-wait=1000` to wait real milliseconds after load. This is not Chromium's virtual time budget.
+- `.png`, `.jpg`/`.jpeg`, and `.webp` filename extensions select the output format.
+
 ## Bun
 - Bun doesn't have `bun --check`
 - Bun has many built-in functions; use/check them first before implementing your own

package/LICENSES/brotli.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2009, 2010, 2013-2016 by the Brotli Authors.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -22,7 +22,7 @@ npm i -g bun
 npx buninu-browser
 
 # Open a URL
-npx buninu-browser github.com
+npx buninu-browser buninu.org
 
 # Arguments after -- go to the
 # browser engine; --mobile presents
@@ -35,8 +35,18 @@ npx buninu-browser github.com \
 # endpoint for any client
 npx buninu-browser --headless \
   --remote-debugging-port=9222
+
+# capture a page and exit
+npx buninu-browser --headless --screenshot=page.png \
+  --window-size=1280,800 https://example.com
 ```
 
+Screenshot mode waits for the page's `load` event before capture. For content
+that appears later, add `--screenshot-wait=1000` (real milliseconds). The output
+format follows the filename extension: PNG, JPEG, or WebP. Chromium's
+`--virtual-time-budget` is not implemented; a real-time delay does not advance
+page timers the same way.
+
 The first run downloads this package
 (about 50 MB: fonts, CanvasKit and
 the video decoder), then the terminal
@@ -206,11 +216,20 @@ When idle, the main thread rasterizes a tile reaching half a viewport above
 and one viewport below the visible area, so the compositor can scroll
 without waiting. Screenshots are encoded with `Bun.Image`.
 
-`<video>` can decode and display MP4 video frames after a click, with a basic
-play/pause control. Video bytes are fetched through the controller; the
-renderer uses vendored wasmpeg JavaScript and WebAssembly without native
-media bindings. Audio, seeking, and full HTML media controls are not yet
-implemented. No npm install is needed for the decoder.
+`<video>` can decode and display MP4 video frames with basic playback and
+seeking. Video bytes are fetched through the controller; the renderer uses
+vendored wasmpeg JavaScript and WebAssembly without native media bindings.
+Audio plays through a PulseAudio server on 127.0.0.1:4713, such as jspulse.
+No npm install is needed for the decoder.
+
+Clicked `a download` links (including `data:` and `blob:` URLs up to 64 MB) and responses with `Content-Disposition: attachment`
+save to the user's Downloads folder by default (including a relocated Windows
+Downloads folder); the directory is created when needed. A CDP
+client can set the directory with `Browser.setDownloadBehavior` and receive
+`Browser.downloadWillBegin` and `Browser.downloadProgress` events. Standalone
+text and structured-document previews have a Download button at the top right
+that saves the original response bytes. As in Chromium, `allowAndName` saves
+the file under its download GUID; `allow` keeps the suggested filename.
 
 Documents load in stages:
 
@@ -241,6 +260,21 @@ asked for; input coordinates are scaled back, and pages see the factor as
 CASTY_BROWSER="$PWD/buninu-browser.js" bun ../casty/bin/casty.js github.com -- --mobile
 ```
 
+### Video and audio
+
+`<video>` and `<audio>` share one pipeline; an `<audio controls>` is a
+300x32 control bar with no picture. Clicking plays or pauses, clicking the
+progress track seeks, and page script has `play()`, `pause()`,
+`currentTime` (settable), `duration`, `paused`, `ended` and the matching
+events. wasmpeg decodes what its LGPL build supports (H.264, HEVC, VP8/VP9,
+MPEG-4, Theora, MPEG-1/2; MP3, AAC, FLAC, Vorbis, Opus, WAV).
+
+Sound, a video's included, plays through a PulseAudio native-protocol server
+on `127.0.0.1:4713`, such as [jspulse](https://github.com/jjtseng93/jspulse)
+(`npx @drxiaozhi/jspulse`); without one, video plays silently. The controller
+holds the connection, since renderers cannot open sockets, and paces the
+stream to real time, so pausing stops the sound within half a second.
+
 ### Diagnostics
 
 casty does not show the browser's stderr. Set `BUNINU_LOG=1` to also write
@@ -271,7 +305,7 @@ The integration form is intentionally different for each upstream:
 | **Chromium** | Behavioural reference; Linux syscall tables and the renderer seccomp policy structure | Use only BSD-3-Clause files, with attribution; Blink files under other licenses (such as the LGPL `html.css`) are not used |
 | **WHATWG HTML Standard** | User-agent default styles | Adapt the suggested rendering rules (§15.3) with attribution under CC BY 4.0 |
 | **CanvasKit** | Skia-based WASM rasterization and text shaping (SkParagraph with its bundled HarfBuzz) | Pin the official `canvaskit-wasm` release artifacts and integrity; do not vendor the full Skia repository or a separate HarfBuzz |
-| **SES (Hardened JavaScript)** | First sandbox layer for page scripts: `lockdown()` and one compartment per document | Vendored unmodified at an exact npm release in [`vendor/ses/`](vendor/ses/); page globals are project-owned bindings, never Happy DOM objects |
+| **SES (Hardened JavaScript)** | First sandbox layer for page scripts: `lockdown()` and one compartment per document | Vendored at an exact npm release in [`vendor/ses/`](vendor/ses/), with local changes recorded in [`patches/ses/`](patches/ses/); page globals are project-owned bindings, never Happy DOM objects |
 | **Acorn** | JavaScript parser used to give classic scripts browser-style shared globals under SES | Vendored unmodified at an exact npm release in [`vendor/acorn/`](vendor/acorn/) |
 | **wasmpeg / FFmpeg** | CPU WebAssembly video decoding | Vendored `@wasmpeg/cpu` 1.0.1 under [`vendor/wasmpeg/`](vendor/wasmpeg/), licensed LGPL-2.1-or-later; the WASM remains a separate, replaceable file. See its [`VENDORING.md`](vendor/wasmpeg/VENDORING.md) and [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) |
 | **Web Platform Tests** | Conformance testing | Use a pinned external checkout or sparse test snapshot; do not place the complete WPT repository in the runtime vendor tree |

package/THIRD_PARTY_NOTICES.md

@@ -36,8 +36,11 @@ corresponding test.
   (core-js, MIT), `LICENSES/ses-v8.txt` (V8, BSD-3-Clause)
 
 The renderer calls `lockdown()` and runs page scripts in SES compartments
-(`lib/renderer/page-realm.js`). The bundle is used unmodified; its SHA-256 is
+(`lib/renderer/page-realm.js`). The upstream bundle's SHA-256 is
 `1e40a59ccf5e72da8e260dda007a19ebd20304394b1b7288d0aab21733b9cd95`.
+The local change allowing a `RegExp` instance to override its own `toString`
+is recorded in [`patches/ses/`](patches/ses/README.md). The patched bundle's
+SHA-256 is `2f6c0043af15b4f7a7b04bfae02ce266a32f92b1089c956697c6f7b439b063bf`.
 
 ## Acorn
 
@@ -148,6 +151,15 @@ reimplemented in JavaScript, and no Chromium source text is copied:
   tile (`lib/renderer/page-renderer.js`), after the display-item reuse in
   `third_party/blink/renderer/platform/graphics/paint/paint_controller.cc`.
 
+## PulseAudio native protocol (independent implementation)
+
+`lib/audio/pulse-client.js` is the client side of the PulseAudio native
+protocol (protocol version 8: command packets as tagstructs, audio frames with
+a 20-byte header), written for this project from the protocol's documented
+wire format. It contains no source code from PulseAudio or from jspulse, both
+of which are LGPL-licensed; jspulse was used only as a separate server process
+to test against, never imported by this repository's code or tests.
+
 ## WHATWG HTML Standard
 
 - Project: HTML Living Standard
@@ -214,12 +226,22 @@ binary and CanvasKit's upstream build configuration:
 | libwebp | `LICENSES/libwebp.txt` (BSD-3-Clause) | https://github.com/webmproject/libwebp |
 | Wuffs image decoding | `LICENSES/wuffs.txt` (MIT or Apache-2.0) | https://github.com/google/wuffs |
 | WOFF2 fonts | `LICENSES/woff2.txt` (MIT) | https://github.com/google/woff2 |
+| Brotli compression used by WOFF2 | `LICENSES/brotli.txt` (MIT) | https://github.com/google/brotli |
 | zlib | `LICENSES/zlib.txt` (zlib) | https://github.com/madler/zlib |
 | Emscripten-generated runtime | `LICENSES/emscripten.txt` (MIT or University of Illinois/NCSA) | https://github.com/emscripten-core/emscripten |
 
-The exact revisions of these libraries in the inherited CanvasKit binary
-have not been independently reconstructed; the top-level artifact is the
-official `canvaskit-wasm` 0.41.1 release.
+The top-level artifact is the official `canvaskit-wasm` 0.41.1 release,
+corresponding to Skia commit `3c68f3ffd7c9bc781494cdb85e718ff1e6f49d84`.
+That release's `DEPS` pins Brotli at
+`6d03dfbedda1615c4cba1211f8d81735575209c8`. The exact revisions of the
+remaining embedded libraries have not been independently reconstructed.
+
+## Project-generated test media
+
+`test/fixtures/tone.mp3` and `test/fixtures/video.mp4` are one-second synthetic
+fixtures generated for this project's audio and video tests. They contain no
+third-party creative content. Their container metadata identifies FFmpeg's
+Lavf/Lavc encoders; FFmpeg itself is not distributed in these fixture files.
 
 The source asset directory also retains the license files next to the fonts and
 CanvasKit artifacts. Versions and provenance above mirror

package/buninu-browser.js

@@ -36,7 +36,7 @@ export async function main(args = Bun.argv.slice(2)) {
   if (has("--help", "-h", "-help")) {
     console.log(`Buninu Browser ${packageInfo.version}
 
-Usage: buninu-browser [options]
+Usage: buninu-browser [options] [URL]
 
 Options:
   --remote-debugging-port=<port>  CDP port (0 picks a free one; default 9222)
@@ -45,6 +45,9 @@ Options:
   --mobile                        Present as a phone: mobile user agent and touch media
                                   features (hover: none, pointer: coarse); user agent
                                   overrides over CDP are ignored
+  --screenshot[=FILE]             Capture one PNG and exit (default screenshot.png)
+  --window-size=WIDTH,HEIGHT      Viewport size for the screenshot (default 800,600)
+  --screenshot-wait=MILLISECONDS  Wait after page load before capturing
   --version, -V                   Print the version
   --help, -h                      Print this help
 
@@ -56,7 +59,12 @@ Environment:
   }
 
   const { runHeadlessShell } = await import("./lib/headless-shell.js");
-  await runHeadlessShell(args);
+  if (args.some((arg) => arg === "--screenshot" || arg.startsWith("--screenshot="))) {
+    const { runScreenshot } = await import("./lib/screenshot-cli.js");
+    await runScreenshot(args);
+  } else {
+    await runHeadlessShell(args);
+  }
   return 0;
 }
 

package/lib/audio/pcm.js

@@ -0,0 +1,16 @@
+/** Interleaved Float32 samples in [-1, 1] (as audio decoders produce) as s16le bytes. */
+export function floatToS16(samples) {
+  const out = new Uint8Array(samples.length * 2);
+  const view = new DataView(out.buffer);
+  for (let index = 0; index < samples.length; index++) {
+    const value = Math.max(-1, Math.min(1, samples[index]));
+    view.setInt16(index * 2, Math.round(value < 0 ? value * 32768 : value * 32767), true);
+  }
+  return out;
+}
+
+/** Consume at most `bytes` of interleaved s16le output, leaving whole frames. */
+export function splitSamples(samples, channels, bytes) {
+  const count = Math.min(samples.length, Math.floor(bytes / (channels * 2)) * channels);
+  return [samples.subarray(0, count), samples.subarray(count)];
+}

package/lib/audio/piano.js

@@ -0,0 +1,109 @@
+import { floatToS16 } from "./pcm.js";
+
+// LazyI piano's sound-producing keyboard rows. The table
+// is relative to Space = MIDI 60 (C4). Change PIANO_DO alone to transpose
+// every key; the default A4 exactly matches LazyI's original octave.
+// The LazyI key intervals remain fixed in the table.
+// Browser control keys (Escape, Tab, CapsLock, Shift, Alt, Control, Backspace)
+// are intentionally omitted. Space and Enter remain playable as requested.
+export const PIANO_KEYS = Object.freeze({
+  F1: 29, F2: 36, F3: 41, F4: 45, F5: 48, F6: 53,
+  F7: 81, F8: 83, F9: 84, F10: 86, F11: 88, F12: 89,
+  "`": 33, "1": 36, "2": 43, "3": 48, "4": 52, "5": 55, "6": 49,
+  "7": 74, "8": 76, "9": 77, "0": 79, "-": 81, "=": 83,
+  q: 31, w: 38, e: 43, r: 47, t: 50, y: 79, u: 69,
+  i: 71, o: 72, p: 74, "[": 76, "]": 77, "\\": 79,
+  a: 33, s: 40, d: 45, f: 48, g: 52, h: 72, j: 62,
+  k: 64, l: 65, ";": 67, "'": 69, Enter: 71,
+  z: 28, x: 35, c: 40, v: 43, b: 47, n: 67, m: 57,
+  ",": 59, ".": 60, "/": 62, " ": 60,
+});
+export const PIANO_DO = 69; // A4, LazyI's original Space pitch.
+
+const CODE_KEYS = {
+  Backquote: "`", Minus: "-", Equal: "=", BracketLeft: "[", BracketRight: "]",
+  Backslash: "\\", Semicolon: ";", Quote: "'", Comma: ",", Period: ".", Slash: "/",
+  Space: " ", NumpadEnter: "Enter",
+};
+const SHIFTED_KEYS = {
+  "~": "`", "!": "1", "@": "2", "#": "3", "$": "4", "%": "5", "^": "6",
+  "&": "7", "*": "8", "(": "9", ")": "0", _: "-", "+": "=", "{": "[",
+  "}": "]", "|": "\\", ":": ";", '"': "'", "<": ",", ">": ".", "?": "/",
+};
+
+/** Prefer physical code when present; IME text falls back to event.key/data. */
+export function pianoNote(key, code = "") {
+  const physical = /^Key[A-Z]$/.test(code) ? code.slice(3).toLowerCase()
+    : /^Digit[0-9]$/.test(code) ? code.slice(5)
+      : CODE_KEYS[code] ?? (code.startsWith("F") ? code : null);
+  const typed = key.length === 1 ? (SHIFTED_KEYS[key] ?? key.toLowerCase())
+    : key === "Space" || key === "Spacebar" ? " " : key;
+  const note = PIANO_KEYS[physical ?? typed];
+  return note === undefined ? null : note + PIANO_DO - 60;
+}
+
+/** A short struck-string tone, mono 48 kHz s16le PCM. */
+export function pianoTone(note, rate = 48000) {
+  const frames = Math.round(rate * 0.7);
+  const samples = new Float32Array(frames);
+  const frequency = 440 * 2 ** ((note - 69) / 12);
+  // The original left-hand register is quiet on small speakers. Raise only
+  // its level; leave pitch and relative harmonic balance untouched.
+  const gain = 1 + Math.max(0, Math.min(1, (60 - note) / 24));
+  // Piano strings are slightly stiff and two strings of a note beat softly.
+  // These are partials of the requested pitch, not a transposition.
+  const partials = [1, 0.32, 0.13, 0.055, 0.025];
+  const phases = partials.map((_, index) => {
+    const harmonic = index + 1;
+    const stretched = harmonic * Math.sqrt(1 + 0.00015 * harmonic * harmonic);
+    return 2 * Math.PI * frequency * stretched;
+  });
+  for (let index = 0; index < frames; index++) {
+    const time = index / rate;
+    const attack = Math.min(1, time * 320);
+    const release = Math.min(1, (frames - index) / (rate * 0.035));
+    let sound = 0;
+    for (let partial = 0; partial < partials.length; partial++) {
+      const decay = Math.exp(-(3.5 + partial * 1.2) * time);
+      const phase = phases[partial] * time;
+      sound += partials[partial] * decay * (
+        0.82 * Math.sin(phase) + 0.18 * Math.sin(phase * 1.0017)
+      );
+    }
+    samples[index] = 0.28 * gain * attack * release * sound;
+  }
+  return floatToS16(samples);
+}
+
+/** Mixes all piano notes into one persistent mono PCM stream. */
+export class PianoMixer {
+  #cache = new Map();
+  #voices = [];
+
+  trigger(note) {
+    let tone = this.#cache.get(note);
+    if (!tone) {
+      const bytes = pianoTone(note);
+      tone = new Int16Array(bytes.buffer, bytes.byteOffset, bytes.byteLength / 2);
+      this.#cache.set(note, tone);
+    }
+    this.#voices.push({ tone, position: 0 });
+    if (this.#voices.length > 16) this.#voices.shift();
+  }
+
+  render(bytes) {
+    const frames = Math.max(0, Math.floor(bytes / 2));
+    const output = new Uint8Array(frames * 2);
+    const view = new DataView(output.buffer);
+    for (let frame = 0; frame < frames; frame++) {
+      let mixed = 0;
+      for (const voice of this.#voices) {
+        if (voice.position < voice.tone.length) mixed += voice.tone[voice.position++];
+      }
+      // Soft limiting avoids crackles when several struck notes overlap.
+      view.setInt16(frame * 2, Math.round(32767 * Math.tanh(mixed / 32768)), true);
+    }
+    this.#voices = this.#voices.filter((voice) => voice.position < voice.tone.length);
+    return output;
+  }
+}