chore: update

Author: route

docs/ferrum/1-introduction.md

@@ -118,6 +118,18 @@ browser.reset
 browser.quit
 ```
 
+`#quit` blocks by default until the browser process is confirmed dead and its user data directory removed. Killing a
+stubborn process (one that ignores `TERM` and needs `KILL`) can take a couple of seconds, which matters if you're
+quitting many browsers in a hot path. Pass `wait: false` to return immediately and run that cleanup on a background
+thread instead:
+
+```ruby
+browser = Ferrum::Browser.new
+thread = browser.quit(wait: false)
+# ... do other work while the browser is killed and its directory removed in the background ...
+thread.join # only needed if you must wait for cleanup to finish, e.g. before reusing a fixed port
+```
+
 ## Thread safety
 
 Ferrum is fully thread-safe. You can create one browser or a few as you wish and

docs/ferrum/14-emulation.md

@@ -6,14 +6,26 @@ sidebar_position: 14
 
 #### set_viewport
 
-Overrides device screen dimensions and emulates viewport.
+Overrides device screen dimensions and emulates viewport. When `:mobile` is
+`true`, this also enables touch emulation (`navigator.maxTouchPoints`,
+`ontouchstart`) alongside the mobile viewport metrics.
 
 * options `Hash`
   * :width `Integer`, viewport width. `0` by default
   * :height `Integer`, viewport height. `0` by default
   * :scale_factor `Float`, device scale factor. `0` by default
-  * :mobile `Boolean`, whether to emulate mobile device. `false` by default
+  * :mobile `Boolean`, whether to emulate mobile device and enable touch. `false` by default
 
 ```ruby
 page.set_viewport(width: 1000, height: 600, scale_factor: 3)
 ```
+
+`:width`, `:height`, and `:scale_factor` all default to `0`, which per the
+[DevTools protocol](https://chromedevtools.github.io/devtools-protocol/tot/Emulation/#method-setDeviceMetricsOverride)
+disables overriding that particular value. This means `mobile:` can be
+enabled on its own, at the page's current size, without specifying a device
+size preset:
+
+```ruby
+page.set_viewport(mobile: true)
+```

docs/ferrum/15-frames.md

@@ -74,6 +74,25 @@ One of the states frame's in:
 * `:navigated`
 * `:stopped_loading`
 
+#### loader_id : `String | nil`
+
+Id of the loader associated with the frame's current navigation, set once the frame navigates.
+
+#### lifecycle_events : `Array[Hash]`
+
+List of the frame's lifecycle events as reported by the browser, each a `{"name" => String, "timestamp" => Float}`
+hash, e.g. `init`, `networkIdle`, `firstPaint`.
+
+#### idle? : `Boolean`
+
+Whether the frame has finished loading (`:stopped_loading` state). Frames in `:canceled` state (execution context
+torn down mid-navigation) are not considered idle.
+
+```ruby
+page.go_to("https://example.com")
+page.main_frame.idle? # => true
+```
+
 #### url : `String`
 
 Returns current frame's location href.

docs/ferrum/2-customization.md

@@ -15,7 +15,9 @@ Ferrum::Browser.new(options)
     * `:incognito` (Boolean) - Create an incognito profile for the browser startup window, `true` by default.
     * `:dockerize` (Boolean) - Provide CLI flags to the browser to run it in a container, `false` by default.
     * `:xvfb` (Boolean) - Run browser in a virtual framebuffer, `false` by default.
-    * `:flatten` (Boolean) - Use one websocket connection to the browser and all the pages in flatten mode.
+    * `:flatten` (Boolean) - Use one websocket connection to the browser and all the pages in flatten mode,
+      `true` by default. When set to `false`, each page/target opens its own dedicated websocket connection instead
+      of sharing the browser's connection.
     * `:window_size` (Array) - The dimensions of the browser window in which to
       test, expressed as a 2-element array, e.g. [1024, 768]. Default: [1024, 768]
     * `:extensions` (Array[String | Hash]) - An array of paths to files or JS
@@ -42,7 +44,9 @@ Ferrum::Browser.new(options)
       options you put in `:browser_options` will be passed to the browser,
       except required ones of course.
     * `:port` (Integer) - Remote debugging port for headless Chrome.
-    * `:host` (String) - Remote debugging address for headless Chrome.
+    * `:host` (String) - Host we communicate with when spawning browser, `127.0.0.1` by default.
+      Chrome always listens on `127.0.0.1` regardless of this option, so the host must resolve to `127.0.0.1` for
+      Ferrum to actually be able to connect.
     * `:url` (String) - URL for a running instance of Chrome. If this is set, a
       browser process will not be spawned.
     * `:ws_url` (String) - Websocket url for a running instance of Chrome. If this is set, a
@@ -56,6 +60,78 @@ Ferrum::Browser.new(options)
     * `:save_path` (String) - Path to save attachments with [Content-Disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) header.
     * `:env` (Hash) - Environment variables you'd like to pass through to the process
 
+## The crashpad handler
+
+Chrome starts two `chrome_crashpad_handler` processes per browser on Linux. Their only job is to collect and upload
+crash reports, which no automated browser has any use for, but **Ferrum does not disable them**, because there is no
+safe way to.
+
+Handlers Chrome starts on Linux:
+
+| Chrome | `--headless` | `--headless=new` | headful |
+|---|---|---|---|
+| 127 and older | 0 | 2 | 2 |
+| 128 and newer | 2 | 2 | 2 |
+
+New headless always starts them. What changed in 128 is what bare `--headless` *means*: before it, that selected old
+headless, a separate lightweight shell with no crash handler; from 128 on it selects new headless, which is full
+Chrome. Headful has always behaved like new headless.
+
+### No flag turns them off safely
+
+| Flag | What it does |
+|---|---|
+| `--disable-breakpad` | Stops crash *reporting*, not the handler process |
+| `--disable-crash-reporter` | Same |
+| `--no-crashpad` | Not a Chromium switch at all, so Chrome ignores it |
+| `--disable-crashpad-for-testing` | Real, and it does stop them — but it breaks the browser |
+
+:::danger
+Do not pass `--disable-crashpad-for-testing`. It is named `for-testing` because it is meant for Chromium's own test
+harness, where the process tree is fully controlled. In a normally launched browser, child processes die at startup
+with `Crashing due to FD ownership violation`, and the network service crash-loops.
+
+The failure is near-invisible: the browser process survives, so it starts normally and CDP answers every command.
+There is simply no network service behind it, so every navigation returns `net::ERR_ABORTED` and the document stays
+`about:blank`.
+:::
+
+Ferrum shipped `--no-crashpad` as a default from 0.18.0 in an attempt at this. It never did anything, and has been
+removed.
+
+### Operating system differences
+
+On macOS one handler starts rather than two, and it exits when the browser does, so nothing accumulates.
+
+It is also invisible to `pstree`, because it double-forks and reparents to launchd and is therefore never a
+descendant of the process that started Chrome. Look for it globally instead:
+
+```console
+$ ps -Ao pid=,ppid=,comm= | grep crashpad
+13270     1 .../Helpers/chrome_crashpad_handler
+```
+
+`ppid` is `1`, and the pid usually lands just after Chrome's own.
+
+### Why this matters most in Docker
+
+The handler is not a problem outside a container, and killing the browser is not what deals with it. The handler is
+independent of Chrome's process group, so the signal Ferrum sends during teardown never reaches it — and does not
+need to. The handler watches the browser and exits by itself once Chrome is gone. Verified by sending `TERM` and
+`KILL` to the process group, and `KILL` and `SIGUSR1` to the browser pid directly: in every case it terminated on its
+own within a second.
+
+What is left behind is an exit status. Because the handler double-forks away from Chrome, its parent is pid 1, and
+pid 1 is what reaps it — systemd or launchd, silently, so nothing is left over and no cleanup is needed.
+
+In a container your own process is usually pid 1, and it does not wait on children it never spawned. Nothing reaps
+the handlers, so every browser leaves two more `<defunct>` entries behind, and they are never reclaimed.
+**They accumulate, until the process table fills up.**
+
+Run the container with an init — `docker run --init`, `init: true` in Compose, or tini as the entrypoint. It is worth
+doing regardless, since every other process in the image has the same problem, and there is no flag that avoids the
+need for it.
+
 ## Examples
 
 ```ruby

docs/ferrum/20-accessibility.md

@@ -0,0 +1,137 @@
+---
+sidebar_position: 20
+---
+
+# Accessibility
+
+Ferrum wraps the CDP [Accessibility](https://chromedevtools.github.io/devtools-protocol/tot/Accessibility/) domain,
+letting you read the accessibility (AX) tree that assistive technologies (like screen readers) rely on. The query
+methods below work without calling `enable` first; `enable`/`disable` exist only if you want live AX events.
+
+`page.accessibility` returns the `Ferrum::Accessibility` instance for a page.
+
+:::note
+The node-scoped methods (`node_for`, `partial_tree`, and `query` with a `node:`) issue their command against the
+node's owning page session. They support same-process (same-target) iframes; nodes living in an out-of-process
+iframe (OOPIF, a separate CDP target) are not resolvable and will error or return an empty result.
+:::
+
+#### node_for(node) : `AXNode | nil`
+
+Returns the single non-ignored `AXNode` for a DOM node, or `nil`.
+
+* node `Ferrum::Node`
+
+```ruby
+node = page.at_css("button")
+page.accessibility.node_for(node) # => #<Ferrum::Accessibility::AXNode ...>
+```
+
+You can also get to it directly from the node itself:
+
+#### axnode : `AXNode | nil`
+
+`Node#axnode` is a shortcut for `page.accessibility.node_for(self)`.
+
+```ruby
+page.at_css("button").axnode.role # => "button"
+```
+
+#### partial_tree(\*\*options) : `Array[AXNode]`
+
+Returns the partial AX tree for a DOM node.
+
+* options `Hash`
+    * :node `Ferrum::Node` **required**
+    * :fetch_relatives `Boolean` whether to include related nodes, `false` by default
+
+```ruby
+node = page.at_css("form")
+page.accessibility.partial_tree(node: node)
+```
+
+#### snapshot(\*\*options) : `Array[AXNode]`
+
+Returns the full AX tree for the page.
+
+* options `Hash`
+    * :depth `Integer` how many levels deep to fetch, unlimited by default
+    * :frame_id `String` restrict the snapshot to a given frame
+
+```ruby
+page.accessibility.snapshot
+```
+
+#### root(\*\*options) : `AXNode | nil`
+
+Returns the root `AXNode` of the (optionally framed) document.
+
+* options `Hash`
+    * :frame_id `String` restrict to a given frame
+
+```ruby
+page.accessibility.root
+```
+
+#### query(\*\*options) : `Array[AXNode]`
+
+Query the AX tree by accessible name and/or role.
+
+* options `Hash`
+    * :name `String` accessible name to match
+    * :role `String` AX role to match, e.g. `"button"`
+    * :node `Ferrum::Node` scope the query to this node's subtree, whole page by default
+
+```ruby
+page.accessibility.query(role: "button")
+page.accessibility.query(name: "Submit", role: "button")
+```
+
+#### enable : `self`
+#### disable : `self`
+
+Enable/disable the CDP Accessibility domain, only needed if you want live AX events; the query methods above work
+without it.
+
+## AXNode
+
+Represents a single [AXNode](https://chromedevtools.github.io/devtools-protocol/tot/Accessibility/#type-AXNode)
+from the CDP Accessibility domain. Instances are returned by the methods above, never constructed directly.
+
+#### role : `String | nil`
+
+The AX role, e.g. `"button"`, `"heading"`.
+
+#### name : `String | nil`
+
+The accessible name.
+
+#### description : `String | nil`
+
+The accessible description.
+
+#### value : `String | Numeric | Boolean | nil`
+
+The raw CDP `AXValue#value`; type varies by control (e.g. a checkbox's value is a boolean).
+
+#### properties : `Hash`
+
+ARIA/computed properties flattened to `name => value`, e.g. `{"focusable" => true}`.
+
+#### ignored? : `Boolean`
+
+Whether the node is ignored by the accessibility tree.
+
+#### ignored_reasons : `Array | nil`
+
+Why the node is ignored, if it is.
+
+#### node_id : `String | nil`
+#### backend_dom_node_id : `Integer | nil`
+#### child_ids : `Array | nil`
+
+Ids linking the AX node back to its DOM node and children in the AX tree.
+
+#### to_h : `Hash`
+
+The raw CDP AXNode hash.