bidi2pdf 0.1.20 → 0.1.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 523b63ba5c422c92dd950e0045261ebcd9b888d042d930fa312b87b4c94f3e31
-  data.tar.gz: b6aeb5c8ba74244bd890434a0c46ed18c92afd827dfaa47a9520fca20039d676
+  metadata.gz: '008d5b0569ba4b7f8bbcd4092da72ce14e5d0e42589a97813f7c64c8bc6a0d9f'
+  data.tar.gz: 8266f91bfa7606d843bed392cee203060cc3b13d98435cc9a0c4a679b5041285
 SHA512:
-  metadata.gz: 7dbae17f4831478c506f67a0b1e72ca4890b2716c183e5c25b40a68e9009c78f12d8414bae9f9fc4e5f6eab52e51d04c9c217ed0b48cd73f8d54af3d4feca9e6
-  data.tar.gz: 000bc92f8ea29444b652f45e48ef9daca4f460e90d71cc731b84e825e32e20296b24df6161febc2efc214bd4fa74577079634a23260785235c4bf977ec49c53b
+  metadata.gz: 27ce2475fa8d30bc9c5447353767c6d2c06db59f57daa7fab7e7a337e26703cc1a0df04439d2b8b68455e5a872138775321a7f31988beb02dba47df0dd06d48d
+  data.tar.gz: acb216b0c656916ee8e8ea797b1fccd026c67fa6260ac5f230f1c44190ffb00455fd83efb5238826c97af0f0051cf68a7335d09e51e0aaa25b85c2efdc802290

data/CHANGELOG.md

@@ -8,10 +8,47 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-[unreleased]: https://github.com/dieter-medium/bidi2pdf/compare/v0.1.20..HEAD
+[unreleased]: https://github.com/dieter-medium/bidi2pdf/compare/v0.1.22..HEAD
 
 <!-- generated by git-cliff end -->
 
+## [0.1.22] - 2026-10-11
+
+### 🐛 Fixed
+- Report a network-idle timeout as a timeout
+- Let the network-idle wait time out cleanly
+
+### 🔄 Changed
+- Merge pull request #164 from dieter-medium/fix/network-idle-timeout
+- Merge pull request #163 from dieter-medium/feat/disable-script-execution
+
+### 🚀 Added
+- Let a tab switch off script execution
+
+## [0.1.21] - 2026-10-09
+
+### 🐛 Fixed
+- Define the word the hyphenation control prints
+- Run image specs against the image from the PR
+- Pin hyphenation data to a fixed language set
+- Check hyphenation in the published image
+- Move the hyphenation spec to its own PR
+- Build chromedriver images one at a time
+- Read watchdog settings as decimal numbers
+- Close spares first and free their leases
+
+### 🔄 Changed
+- Merge pull request #159 from dieter-medium/feat/hyphenation-spec
+- Merge pull request #158 from dieter-medium/feat/hyphenation-data
+- Merge pull request #157 from dieter-medium/fix/chromedriver-build-race
+- Merge pull request #156 from dieter-medium/feat/chromedriver-watchdog
+- Merge pull request #155 from dieter-medium/feat/shutdown-deadline
+
+### 🚀 Added
+- Install hyphenation dictionaries in the images
+- Restart a stuck chromedriver container
+- Bound the warmer shutdown by a deadline
+
 ## [0.1.20] - 2026-09-30
 
 ### 🐛 Fixed
@@ -531,7 +568,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### 🔄 Released
 
-- [unreleased](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.20..HEAD)
+- [unreleased](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.22..HEAD)
+- [0.1.22](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.21..v0.1.22)
+- [0.1.21](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.20..v0.1.21)
 - [0.1.20](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.19..v0.1.20)
 - [0.1.19](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.18..v0.1.19)
 - [0.1.18](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.17..v0.1.18)

data/README.md

@@ -347,6 +347,9 @@ tab.navigate_to "https://example.com/invoice/14432423"
 # or inline
 # tab.inject_style content: "body { background-color: red; }"
 
+# Printing HTML you do not trust? Switch its scripts off before navigating:
+# tab.disable_script_execution
+
 tab.wait_until_network_idle
 tab.print("my.pdf")
 
@@ -459,6 +462,67 @@ the box in either image, no extra install step needed.
 Chromium comes from Debian's packages at build time, so every build can carry a different
 Chromium - for a byte-exact pin use the digest (`docker buildx imagetools inspect <image:tag>`).
 
+### Hyphenation
+
+The images (`chromedriver`, `bidi2pdf` and its slim variant) ship Chromium's hyphenation dictionaries
+in `/usr/lib/chromium/hyphen-data/`, so CSS `hyphens: auto` breaks long words in the page's language
+(`lang="de"` on the element or the document) - for exactly these languages, by the `lang` tag Blink
+maps to each dictionary (case does not matter; Blink drops trailing subtags until one matches):
+
+| `lang` | Dictionary |
+|---|---|
+| `de`, `de-DE`, `de-AT`, `de-CH` (and `de-DE-1901` - the region wins) | German, 1996 spelling (`de-1996`) |
+| `de-1901` | German, traditional spelling |
+| `de-CH-1901`, `de-LI-1901` | Swiss German, traditional spelling |
+| `en`, `en-US` | US English |
+| `en-GB`, `en-AU`, `en-IE`, ... (every other `en-*`) | British English |
+| `fr`, `es`, `it`, `nl`, `pt` (with any region, e.g. `pt-BR`) | French, Spanish, Italian, Dutch, Portuguese |
+
+The hyphenation spec prints one word in each of these, against a control without hyphenation.
+Debian's Chromium has none, and the component it would download needs a profile that outlives the
+session. `docker/install-hyphen-data.sh` fetches them at build time from Chromium's source, pinned by
+the `HYPHEN_DATA_REF` build argument - deliberately independent of the Debian Chromium the image
+installs, since the pattern data and its format change far more rarely; the hyphenation spec catches a
+Chromium that stops reading them - with their licence notice (`LICENSE` next to them). Do not pass `--disable-component-update` in
+`chrome_args`: Chromium then skips the dictionaries.
+
+### ChromeDriver health check and watchdog
+
+The image has a Docker `HEALTHCHECK` (chromedriver's `/status`), so `docker ps` shows a
+chromedriver that stopped answering as `unhealthy`. It does not see a Chrome that is wedged behind
+a chromedriver that still answers - memory thrashing shows only to the watchdog. And Docker does
+not restart a container for being unhealthy - only when its main process exits.
+
+That is what the opt-in watchdog does. With `WATCHDOG_ENABLED=true` it checks every
+`WATCHDOG_INTERVAL` seconds and, after `WATCHDOG_FAILURES` failed checks in a row, stops
+chromedriver; the container exits non-zero and its restart policy starts a fresh one - any policy
+but `no` (`--restart unless-stopped` or `on-failure`, `restart:` in Compose; Kamal sets
+`unless-stopped` for accessories). Without one, a watchdog restart just stops the container. A
+check fails when chromedriver does not answer `/status`, or when the
+container's memory thrashes: Linux's pressure stall information (`memory.pressure`, "full") shows
+every task stalled on memory for at least `WATCHDOG_MEMORY_PRESSURE` percent of the last 10 s - a
+Chrome swapping at its memory limit, which answers no command but never crashes.
+
+Renders still running on that Chrome fail when it restarts; a client with a sweeper retries them.
+
+| Variable                   | Default                          | Description                                                  |
+|----------------------------|----------------------------------|--------------------------------------------------------------|
+| `WATCHDOG_ENABLED`         | `false`                          | `true` starts the watchdog.                                  |
+| `WATCHDOG_INTERVAL`        | `15`                             | Seconds between checks.                                      |
+| `WATCHDOG_FAILURES`        | `3`                              | Failed checks in a row before the restart.                   |
+| `WATCHDOG_STATUS_TIMEOUT`  | `5`                              | Seconds `/status` may take.                                  |
+| `WATCHDOG_MEMORY_PRESSURE` | `50`                             | "full avg10" percent that fails a check; `0` turns it off.   |
+| `WATCHDOG_STOP_GRACE`      | `10`                             | Seconds between stopping chromedriver (TERM) and killing it. |
+| `WATCHDOG_PRESSURE_FILE`   | `/sys/fs/cgroup/memory.pressure` | The PSI file; without one (cgroup v1, PSI off) only `/status` counts. |
+
+All values are whole numbers (seconds, percent). A malformed value stops the watchdog from
+starting - chromedriver keeps running unwatched, and the container log says why.
+
+Picking `WATCHDOG_MEMORY_PRESSURE`: "full" counts only the time *every* task waited on memory, so it
+stays near 0 while renders merely run; 50 % of the last 10 s is a container that is stuck, not busy.
+Before lowering it, watch `/sys/fs/cgroup/memory.pressure` inside the container under your usual
+render load and stay well above what you see there.
+
 ### Docker Compose
 
 ```bash
@@ -574,6 +638,7 @@ Bidi2pdf::SessionWarmer.shutdown
 | `registry_dir`       | `Dir.tmpdir`          | Where the session registry file lives - every process that should clean up after the others must share it. |
 | `sweeper`            | `nil`                 | Remote only: settings for a [`ChromeSweeper`](#leaked-chrome-sessions-bidi2pdfchromesweeper) on the same chromedriver, e.g. `{ scope: :all, max_sessions: :auto, pids_limit: 1024, interval: 60 }`. The warmer's own sessions are never touched; `Bidi2pdf::SessionWarmer.sweep!` sweeps on demand. |
 | `retry_refused_sessions` | `true`         | With a `sweeper`: when chromedriver refuses a new session, sweep under pressure and try once more. `false` leaves it to the caller. |
+| `shutdown_timeout`   | `10`                  | Seconds `shutdown` waits, all in all, for its background threads and for closing the warm sessions. `nil` waits for ever. |
 
 #### Leftover sessions on a shared chromedriver
 
@@ -595,6 +660,13 @@ With a `sweeper` configured, the warmer also sweeps in the background every `int
 and when chromedriver refuses a new session ("session not created" - typically a container out of
 room for another Chrome) it sweeps once and tries once more.
 
+`shutdown` is bounded by `shutdown_timeout`. A Chrome that hangs or ran out of memory answers no
+command, and closing each of its sessions would wait out every command timeout in turn - long
+enough that a stopping server looks hung. At the deadline the warmer stops waiting, logs what is
+still running and instruments `session_warmer.shutdown_timeout.bidi2pdf` (`timeout`, `pending`);
+`shutdown` returns the same tally, e.g. `{ "spare" => 1 }`, and `{}` when everything finished.
+Sessions it could not close stay in the registry, so a later sweep closes them.
+
 > **Security note:** an idle warm session is an open, unauthenticated automation endpoint
 > (chromedriver's port, Chrome's debugging port - loopback only for a local chromedriver) for as
 > long as it waits. `max_idle_age` bounds that window; keep it set unless the process runs somewhere
@@ -663,7 +735,7 @@ session is refused.
 | `pids_limit`          | `nil`       | The chromedriver container's pids limit (Docker counts threads). `:auto` without it means no limit.         |
 | `pids_budget`         | `0.8`       | Share of `pids_limit` the Chrome sessions may use.                                                           |
 | `threads_per_session` | `110`       | Threads one Chrome session uses.                                                                             |
-| `interval`            | `nil`       | Seconds between background sweeps (`start`/`stop`).                                                          |
+| `interval`            | `nil`       | Seconds between background sweeps (`start`/`stop`). `stop(timeout: 10)` waits that long for a sweep in progress, then stops waiting and returns `false` (`nil` waits for ever). |
 | `dry_run`             | `false`     | Report what would be closed, close nothing.                                                                  |
 | `registry_dir`        | `Dir.tmpdir`| The registry to read and update - same meaning as the warmer's setting.                                      |
 | `own_sessions`        | `-> { [] }` | A callable returning the caller's live session ids; they are never touched.                                  |

data/docker/Dockerfile

@@ -13,11 +13,23 @@ RUN apt-get update && apt-get upgrade -y &&\
     libatk-bridge2.0-0 \
     libgtk-3-0 \
     libdrm2 \
-    curl \
+    curl ca-certificates \
     unzip \
     xvfb \
     && rm -rf /var/lib/apt/lists/*
 
+# Chromium's hyphenation dictionaries, so that `hyphens: auto` works in the PDFs. Debian's chromium
+# ships none and Chrome cannot download them here - see docker/install-hyphen-data.sh for the whole
+# story. They go next to the chromium binary, where the component installer looks for a bundled copy.
+# The patterns are data files and intentionally do not track the Debian Chromium installed above (the
+# minikin .hyb format is unchanged since 2016, the files since 2023): update this ref when the pattern
+# data itself changes. The hyphenation integration spec, run against the image's own Chromium, catches
+# a Chromium that stops reading them.
+ARG HYPHEN_DATA_REF=refs/tags/154.0.8037.92
+COPY ./docker/install-hyphen-data.sh /usr/local/bin/install-hyphen-data.sh
+RUN chmod +x /usr/local/bin/install-hyphen-data.sh && \
+    /usr/local/bin/install-hyphen-data.sh "${HYPHEN_DATA_REF}" /usr/lib/chromium/hyphen-data
+
 # Create a non-root user
 RUN groupadd -r appuser && useradd -r -g appuser -m -d /home/appuser appuser
 

data/docker/Dockerfile.chromedriver

@@ -18,7 +18,7 @@ RUN echo "deb http://deb.debian.org/debian bookworm contrib non-free" > /etc/apt
     libatk-bridge2.0-0 \
     libgtk-3-0 \
     libdrm2 \
-    curl \
+    curl ca-certificates \
     unzip \
     xvfb \
     x11vnc \
@@ -34,11 +34,24 @@ RUN echo "deb http://deb.debian.org/debian bookworm contrib non-free" > /etc/apt
     && locale-gen en_US.UTF-8 \
     && rm -rf /var/lib/apt/lists/*
 
+# Chromium's hyphenation dictionaries, so that `hyphens: auto` works in the PDFs. Debian's chromium
+# ships none and Chrome cannot download them here - see docker/install-hyphen-data.sh for the whole
+# story. They go next to the chromium binary, where the component installer looks for a bundled copy.
+# The patterns are data files and intentionally do not track the Debian Chromium installed above (the
+# minikin .hyb format is unchanged since 2016, the files since 2023): update this ref when the pattern
+# data itself changes. The hyphenation integration spec, run against the image's own Chromium, catches
+# a Chromium that stops reading them.
+ARG HYPHEN_DATA_REF=refs/tags/154.0.8037.92
+COPY ./docker/install-hyphen-data.sh /usr/local/bin/install-hyphen-data.sh
+RUN chmod +x /usr/local/bin/install-hyphen-data.sh && \
+    /usr/local/bin/install-hyphen-data.sh "${HYPHEN_DATA_REF}" /usr/lib/chromium/hyphen-data
+
 # Create a non-root user
 RUN groupadd -r appuser && useradd -r -g appuser -G audio,video -m -d /home/appuser appuser
 
 COPY ./docker/entrypoint.sh /usr/local/bin/entrypoint.sh
-RUN chmod +x /usr/local/bin/entrypoint.sh
+COPY ./docker/chromedriver-watchdog.sh /usr/local/bin/chromedriver-watchdog.sh
+RUN chmod +x /usr/local/bin/entrypoint.sh /usr/local/bin/chromedriver-watchdog.sh
 
 # ARM compatibility workaround:
 # On ARM architectures (such as Apple Silicon), downloading chromedriver via automated scripts may fail or cause ELF binary errors,
@@ -69,4 +82,9 @@ EXPOSE ${CHROMEDRIVER_PORT}
 # VNC
 EXPOSE 5900
 
+# Marks the container "unhealthy" in docker ps when chromedriver stops answering. Docker does not
+# restart it for that - WATCHDOG_ENABLED=true does (chromedriver-watchdog.sh).
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+  CMD curl -fs -m 4 -o /dev/null "http://127.0.0.1:${CHROMEDRIVER_PORT}/status" || exit 1
+
 CMD ["/usr/local/bin/entrypoint.sh"]

data/docker/Dockerfile.slim

@@ -50,13 +50,25 @@ RUN apt-get update && apt-get upgrade -y &&\
     libatk-bridge2.0-0 \
     libgtk-3-0 \
     libdrm2 \
-    curl \
+    curl ca-certificates \
     unzip \
     xvfb \
     && rm -rf /var/lib/apt/lists/*
 
 COPY --from=builder /usr/local/bundle /usr/local/bundle
 
+# Chromium's hyphenation dictionaries, so that `hyphens: auto` works in the PDFs. Debian's chromium
+# ships none and Chrome cannot download them here - see docker/install-hyphen-data.sh for the whole
+# story. They go next to the chromium binary, where the component installer looks for a bundled copy.
+# The patterns are data files and intentionally do not track the Debian Chromium installed above (the
+# minikin .hyb format is unchanged since 2016, the files since 2023): update this ref when the pattern
+# data itself changes. The hyphenation integration spec, run against the image's own Chromium, catches
+# a Chromium that stops reading them.
+ARG HYPHEN_DATA_REF=refs/tags/154.0.8037.92
+COPY ./docker/install-hyphen-data.sh /usr/local/bin/install-hyphen-data.sh
+RUN chmod +x /usr/local/bin/install-hyphen-data.sh && \
+    /usr/local/bin/install-hyphen-data.sh "${HYPHEN_DATA_REF}" /usr/lib/chromium/hyphen-data
+
 # Create a non-root user
 RUN groupadd -r appuser && useradd -r -g appuser -m -d /home/appuser appuser
 

data/docker/chromedriver-watchdog.sh

@@ -0,0 +1,115 @@
+#!/bin/bash
+# Restarts the chromedriver container when Chrome is in a state it does not recover from by itself:
+# chromedriver no longer answers /status, or the container's memory is thrashing (PSI "full" - every
+# task stalled on memory for that share of the last 10 s). It stops chromedriver, entrypoint.sh
+# exits, and the container's restart policy (unless-stopped, also Kamal's for accessories) starts a
+# fresh one. Docker itself never restarts a merely "unhealthy" container. Renders still running on
+# that Chrome fail - the client's retry and sweeper handle that.
+#
+# Opt-in: entrypoint.sh starts it when WATCHDOG_ENABLED=true.
+# Usage: chromedriver-watchdog.sh <chromedriver pid> [marker file]
+# Before a restart it creates the marker file, so entrypoint.sh can exit non-zero and a restart
+# policy of on-failure restarts the container too.
+#
+#   WATCHDOG_INTERVAL         seconds between checks                 (default 15)
+#   WATCHDOG_FAILURES         failed checks in a row before restart  (default 3)
+#   WATCHDOG_STATUS_TIMEOUT   seconds /status may take               (default 5)
+#   WATCHDOG_MEMORY_PRESSURE  PSI full avg10 percent that fails a check, 0 = off (default 50)
+#   WATCHDOG_STOP_GRACE       seconds between TERM and KILL          (default 10)
+#   WATCHDOG_PRESSURE_FILE    the cgroup's PSI file (default /sys/fs/cgroup/memory.pressure)
+set -euo pipefail
+
+pid="${1:-}"
+marker="${2:-}"
+port="${CHROMEDRIVER_PORT:-3000}"
+interval="${WATCHDOG_INTERVAL:-15}"
+failures="${WATCHDOG_FAILURES:-3}"
+status_timeout="${WATCHDOG_STATUS_TIMEOUT:-5}"
+pressure_limit="${WATCHDOG_MEMORY_PRESSURE:-50}"
+stop_grace="${WATCHDOG_STOP_GRACE:-10}"
+pressure_file="${WATCHDOG_PRESSURE_FILE:-/sys/fs/cgroup/memory.pressure}"
+reason=""
+
+log() {
+  printf 'chromedriver-watchdog: %s\n' "$*" >&2
+}
+
+# Prints the value as a plain decimal - "050" is 50, never bash's octal 40 - or fails closed on a
+# malformed setting: the watchdog does not start (chromedriver keeps running).
+decimal() {
+  local name="$1" value="$2" min="$3"
+  case "$value" in
+    '' | *[!0-9]*) ;;
+    *)
+      if ((10#$value >= min)); then
+        printf '%d\n' "$((10#$value))"
+        return
+      fi
+      ;;
+  esac
+  log "error: ${name} must be an integer >= ${min}, got '${value}' - not watching"
+  exit 1
+}
+
+pid="$(decimal "chromedriver pid" "$pid" 1)"
+port="$(decimal CHROMEDRIVER_PORT "$port" 1)"
+interval="$(decimal WATCHDOG_INTERVAL "$interval" 1)"
+failures="$(decimal WATCHDOG_FAILURES "$failures" 1)"
+status_timeout="$(decimal WATCHDOG_STATUS_TIMEOUT "$status_timeout" 1)"
+pressure_limit="$(decimal WATCHDOG_MEMORY_PRESSURE "$pressure_limit" 0)"
+stop_grace="$(decimal WATCHDOG_STOP_GRACE "$stop_grace" 1)"
+
+# Whole percent of the last 10 s in which every task of this cgroup stalled on memory; 0 when the
+# kernel offers no PSI file (cgroup v1, PSI disabled). Truncated, not rounded: 49.9 is 49, so a
+# limit of 50 means at least 50.0.
+memory_pressure() {
+  if [[ ! -r "$pressure_file" ]]; then
+    printf '0\n'
+    return
+  fi
+  awk '$1 == "full" { split($2, kv, "="); printf "%d\n", kv[2]; found = 1 } END { if (!found) print 0 }' "$pressure_file"
+}
+
+check() {
+  local pressure
+  if ! curl -fs -m "$status_timeout" -o /dev/null "http://127.0.0.1:${port}/status"; then
+    reason="chromedriver did not answer /status within ${status_timeout}s"
+    return 1
+  fi
+  if ((pressure_limit > 0)); then
+    pressure="$(memory_pressure)"
+    if ((pressure >= pressure_limit)); then
+      reason="memory pressure ${pressure}% (full avg10), limit ${pressure_limit}%"
+      return 1
+    fi
+  fi
+}
+
+restart() {
+  log "restarting: stopping chromedriver (pid ${pid}) so the container exits and its restart policy starts a fresh one"
+  if [[ -n "$marker" ]] && ! : >"$marker"; then
+    log "could not write ${marker} - the container may exit 0"
+  fi
+  kill -TERM "$pid" 2>/dev/null || true
+  for ((waited = 0; waited < stop_grace; waited++)); do
+    kill -0 "$pid" 2>/dev/null || exit 0
+    sleep 1
+  done
+  kill -KILL "$pid" 2>/dev/null || true
+  exit 0
+}
+
+log "watching chromedriver (pid ${pid}) every ${interval}s, restart after ${failures} failed checks"
+failed=0
+while kill -0 "$pid" 2>/dev/null; do
+  sleep "$interval"
+  if check; then
+    failed=0
+    continue
+  fi
+  failed=$((failed + 1))
+  log "check ${failed}/${failures} failed: ${reason}"
+  if ((failed >= failures)); then
+    restart
+  fi
+done

data/docker/entrypoint.sh

@@ -17,7 +17,7 @@ if [ "$ENABLE_XVFB" = "true" ]; then
 
   xauth generate :99 . trusted
 
-  umask $old_umask
+  umask "$old_umask"
 
 
 
@@ -38,17 +38,45 @@ if [ "$ENABLE_VNC" = "true" ]; then
   old_umask=$(umask)
   umask 077
   mkdir -p /home/appuser/.vnc
-  x11vnc -storepasswd $VNC_PASS /home/appuser/.vnc/passwd
-  umask $old_umask
+  x11vnc -storepasswd "$VNC_PASS" /home/appuser/.vnc/passwd
+  umask "$old_umask"
   x11vnc -display WAIT:99 -xkb -noxrecord -noxfixes -noxdamage -forever -shared -noshm -usepw -rfbauth /home/appuser/.vnc/passwd &
 fi
 
 # DISPLAY=:99 /home/appuser/.webdrivers/chromedriver --port=33259 --whitelisted-ips=""  --allowed-origins="*" --disable-dev-shm-usage --disable-gpu  --verbose
-/home/appuser/.webdrivers/chromedriver --port=${CHROMEDRIVER_PORT} \
+/home/appuser/.webdrivers/chromedriver --port="${CHROMEDRIVER_PORT}" \
                                        --allowed-ips="" \
                                        --allowed-origins="*" \
                                        --disable-dev-shm-usage \
                                        --disable-gpu \
-                                       --user-data-dir=${USER_DATA_DIR} \
-                                       --log-level=${CHROMEDRIVER_LOG_LEVEL:-INFO} \
-                                       --readable-timestamp
+                                       --user-data-dir="${USER_DATA_DIR}" \
+                                       --log-level="${CHROMEDRIVER_LOG_LEVEL:-INFO}" \
+                                       --readable-timestamp &
+chromedriver_pid=$!
+
+# docker stop sends TERM to this script (PID 1): pass it on so chromedriver ends its sessions.
+trap 'kill -TERM "$chromedriver_pid" 2>/dev/null' TERM INT
+
+# Opt-in watchdog (see chromedriver-watchdog.sh): stops chromedriver when it no longer answers or
+# memory thrashes, so this script exits and the restart policy starts a fresh container. It leaves
+# a marker first, in a private temp dir, so the exit below is non-zero for any restart policy.
+watchdog_marker=""
+if [ "${WATCHDOG_ENABLED:-false}" = "true" ]; then
+  if watchdog_dir="$(mktemp -d)"; then
+    watchdog_marker="${watchdog_dir}/restarted"
+  fi
+  /usr/local/bin/chromedriver-watchdog.sh "$chromedriver_pid" "$watchdog_marker" &
+fi
+
+# A trapped signal interrupts wait before chromedriver has ended: wait again until it has.
+status=0
+wait "$chromedriver_pid" || status=$?
+while kill -0 "$chromedriver_pid" 2>/dev/null; do
+  status=0
+  wait "$chromedriver_pid" || status=$?
+done
+
+if [ -n "$watchdog_marker" ] && [ -e "$watchdog_marker" ] && [ "$status" -eq 0 ]; then
+  status=1
+fi
+exit "$status"

data/docker/install-hyphen-data.sh

@@ -0,0 +1,96 @@
+#!/bin/bash
+# Installs Chromium's hyphenation dictionaries so that `hyphens: auto` works in the PDFs.
+#
+# Why this exists: Chromium on Linux does not ship its hyphenation dictionaries in the binary. They
+# come as a "Hyphenation" component which the component updater downloads at runtime into
+# <user-data-dir>/hyphen-data/<version>/. In our containers that never sticks: chromedriver makes a
+# fresh, throw-away user-data-dir for every session (a download would be gone with it), a sandboxed
+# remote-chrome has no internet access to download from, and Debian's chromium package (chromium,
+# chromium-common) ships no hyphen-data at all. So `hyphens: auto` silently renders as
+# `hyphens: manual` - no automatic word breaks, however `lang` is set.
+#
+# How it works: before looking in the user-data-dir, Chromium's component installer looks for a
+# "preinstalled" copy of every component next to its own binary (ComponentInstaller::StartRegistration ->
+# FindPreinstallation, rooted at chrome::DIR_COMPONENTS = base::DIR_ASSETS = the directory of the chromium
+# executable, /usr/lib/chromium on Debian). It expects <root>/hyphen-data/manifest.json with a valid
+# "version" plus the hyph-<locale>.hyb files. That is exactly how Chrome for Testing bundles them
+# (chrome/BUILD.gn -> third_party/hyphenation-patterns:bundle_hyphen_data), with the same bogus version
+# "1.0.0.0" that is used below. The dictionaries themselves are the AOSP minikin .hyb files that live in
+# chromium/src at third_party/hyphenation-patterns/hyb and are fetched from there, pinned to a Chromium tag
+# (unchanged since 2023 - the de/en files of 151 and 154 are byte-identical). The pin intentionally does
+# not follow the Debian Chromium the image installs: the patterns are data in a format unchanged since
+# 2016, updated when the pattern data changes; the hyphenation integration spec, run against the
+# image's own Chromium, catches a Chromium that stops reading them.
+#
+# The component is only registered by the full browser (chrome_browser_main.cc), never by the old
+# headless shell - fine for Debian's chromium >= 132, where --headless is the new headless mode - and
+# not when --disable-component-update is passed, which neither chromedriver nor bidi2pdf does. Never add it.
+#
+# Usage: install-hyphen-data.sh [chromium-ref] [target-dir]
+set -euo pipefail
+
+ref="${1:-${HYPHEN_DATA_REF:-refs/tags/154.0.8037.92}}"
+target="${2:-/usr/lib/chromium/hyphen-data}"
+source_dir="third_party/hyphenation-patterns"
+archive_url="https://chromium.googlesource.com/chromium/src/+archive/${ref}/${source_dir}.tar.gz"
+
+# The image's language contract: exactly these dictionaries are installed, and each must be in the
+# download or the build fails - a renamed or dropped dictionary shows up at build time, not as a silent
+# fallback to no hyphenation, and the image does not grow when Chromium adds languages. The archive
+# carries ~50; add a language here (and to README "Hyphenation") to support it. Inside Blink "de" maps
+# to de-1996, "en" tries en-gb, then en-us
+# (third_party/blink/renderer/platform/text/hyphenation/hyphenation_minikin.cc, MapLocale).
+dictionaries="hyph-de-1996.hyb hyph-de-1901.hyb hyph-de-ch-1901.hyb hyph-en-us.hyb hyph-en-gb.hyb hyph-fr.hyb hyph-es.hyb hyph-it.hyb hyph-nl.hyb hyph-pt.hyb"
+
+workdir="$(mktemp -d)"
+trap 'rm -rf "$workdir"' EXIT
+mkdir -p "${workdir}/src/hyb"
+
+# Gitiles exports a subtree as one tarball. If that is unreachable, fall back to the GitHub mirror of
+# chromium/src (tags are mirrored), one file at a time, with the file list taken from the same BUILD.gn
+# that Chrome for Testing bundles from.
+fetch_from_gitiles() {
+  echo "Fetching Chromium hyphenation dictionaries from ${archive_url}"
+  curl -fsSL --retry 3 --retry-delay 2 -o "${workdir}/hyb.tar.gz" "${archive_url}" &&
+    tar -xzf "${workdir}/hyb.tar.gz" -C "${workdir}/src"
+}
+
+fetch_from_github() {
+  local raw="https://raw.githubusercontent.com/chromium/chromium/${ref#refs/tags/}/${source_dir}"
+  echo "Fetching Chromium hyphenation dictionaries from ${raw}"
+  curl -fsSL --retry 3 --retry-delay 2 -o "${workdir}/BUILD.gn" "${raw}/BUILD.gn"
+  curl -fsSL --retry 3 --retry-delay 2 -o "${workdir}/src/LICENSE" "${raw}/LICENSE"
+  grep -o '"hyb/hyph-[^"]*\.hyb"' "${workdir}/BUILD.gn" | tr -d '"' | sort -u | while read -r file; do
+    curl -fsSL --retry 3 --retry-delay 2 -o "${workdir}/src/${file}" "${raw}/${file}"
+  done
+}
+
+fetch_from_gitiles || { echo "gitiles download failed, trying the GitHub mirror" >&2; fetch_from_github; }
+
+mkdir -p "${target}"
+for file in ${dictionaries}; do
+  if [ ! -s "${workdir}/src/hyb/${file}" ]; then
+    echo "hyphenation dictionary ${file} missing from ${archive_url}" >&2
+    exit 1
+  fi
+  install -m 0644 "${workdir}/src/hyb/${file}" "${target}/${file}"
+done
+# The patterns are TeX hyphenation patterns under a mix of licenses; keep their notice with the data
+# (Chromium's file covers every language, these included).
+install -m 0644 "${workdir}/src/LICENSE" "${target}/LICENSE"
+
+# Chromium's component installer only accepts the directory with a manifest carrying a valid version.
+# 1.0.0.0 is what Chrome for Testing uses for its bundled copy: lower than anything the component
+# updater would ever serve, and not all zeros (that means "no component").
+cat > "${target}/manifest.json" <<'EOF'
+{
+  "manifest_version": 2,
+  "name": "hyphens-data",
+  "version": "1.0.0.0"
+}
+EOF
+chmod 0644 "${target}/manifest.json"
+chmod 0755 "${target}"
+
+dictionaries=("${target}"/*.hyb)
+echo "Installed ${#dictionaries[@]} hyphenation dictionaries to ${target}"

data/lib/bidi2pdf/bidi/browser_tab.rb

@@ -334,15 +334,20 @@ module Bidi2pdf
         end
       end
 
-      # Waits until the network is idle in the browser tab.
+      # Waits until the network is idle in the browser tab. A timeout does not raise: the
+      # network_idle.bidi2pdf event then carries +timed_out: true+, so subscribers never report a busy
+      # page as idle.
       #
       # @param [Integer] timeout The timeout duration in seconds. Defaults to 10.
       # @param [Float] poll_interval The polling interval in seconds. Defaults to 0.1.
+      # @return [Symbol] :idle or :timeout
       def wait_until_network_idle(timeout: 10, poll_interval: 0.1)
         Bidi2pdf.notification_service.instrument("network_idle.bidi2pdf") do |instrumentation_payload|
-          network_events.wait_until_network_idle(timeout: timeout, poll_interval: poll_interval)
+          status = network_events.wait_until_network_idle(timeout: timeout, poll_interval: poll_interval)
 
           instrumentation_payload[:requests] = network_events.all_events.dup
+          instrumentation_payload[:timed_out] = status == :timeout
+          status
         end
       end
 
@@ -496,6 +501,18 @@ module Bidi2pdf
         client.send_cmd_and_wait(cmd) { |response| response }
       end
 
+      # Switches JavaScript off (or on again) for this tab, through Chrome's own
+      # Emulation.setScriptExecutionDisabled (CDP, via goog:cdp.sendCommand). Call it before
+      # navigating: it holds for every later navigation in the tab, so a page printed from untrusted
+      # HTML runs none of its scripts.
+      #
+      # @param [Boolean] disabled Defaults to true.
+      def disable_script_execution(disabled: true)
+        cmd = Commands::CdpSendCommand.new(method: "Emulation.setScriptExecutionDisabled", params: { value: disabled },
+                                           session: cdp_session)
+        client.send_cmd_and_wait(cmd) { |response| response }
+      end
+
       private
 
       def build_command_and_extractor(print_options)

data/lib/bidi2pdf/bidi/network_events.rb

@@ -95,24 +95,33 @@ module Bidi2pdf
         end
       end
 
+      # Waits until no request is in flight, or until +timeout+ seconds passed.
+      #
+      # @return [Symbol] :idle when every request completed, :timeout when some were still open -
+      #   it never raises for a timeout, so a caller decides whether a busy page is good enough.
       def wait_until_network_idle(timeout: 10, poll_interval: 0.01)
         start_time = Time.now
 
         loop do
           unless events.values.any?(&:in_progress?)
             Bidi2pdf.logger.debug "✅ All network events completed."
-            break
+            return :idle
           end
 
           if Time.now - start_time > timeout
-            Bidi2pdf.logger.warn "⏰ Timeout while waiting for network events to complete. Still in progress: #{in_progress.map(&:id)}"
-            # rubocop:enable Layout/LineLength
-            break
+            log_idle_timeout
+            return :timeout
           end
 
           sleep(poll_interval)
         end
       end
+
+      # Names the requests still open when the wait gives up - it carries on, it does not raise.
+      def log_idle_timeout
+        in_progress = events.values.select(&:in_progress?)
+        Bidi2pdf.logger.warn "⏰ Timeout while waiting for network events to complete. Still in progress: #{in_progress.map(&:id)}"
+      end
     end
   end
 end

data/lib/bidi2pdf/chrome_sweeper/settings.rb

@@ -9,6 +9,7 @@ module Bidi2pdf
     DEFAULT_PIDS_BUDGET = 0.8
     DEFAULT_THREADS_PER_SESSION = 110
     DEFAULT_LEASE_TTL = SessionRegistry::DEFAULT_LEASE_TTL
+    DEFAULT_STOP_TIMEOUT = 10
 
     # What a ChromeSweeper closes and when - validated on construction; an unknown setting raises
     # ArgumentError.

data/lib/bidi2pdf/chrome_sweeper.rb

@@ -167,21 +167,32 @@ module Bidi2pdf
       end
     end
 
-    # Starts the periodic sweep thread (needs an +interval+). Idempotent.
+    # Starts the periodic sweep thread (needs an +interval+). Idempotent. Each thread has its own
+    # wakeup queue, so one that #stop stopped waiting for can never take a later thread's :stop.
+    # After such a #stop, a new thread can sweep while the abandoned sweep is still running: the
+    # lock file lets only one of them sweep at a time, the other's sweep is skipped.
     def start
       raise Bidi2pdf::InvalidConfigError, "chrome_sweeper: start needs an interval" unless interval
+      return self if @thread
 
-      @thread ||= Thread.new { sweep!(reason: :periodic) until @wakeup.pop(timeout: interval) == :stop }
+      wakeup = @wakeup = Thread::Queue.new
+      @thread = Thread.new { sweep!(reason: :periodic) until wakeup.pop(timeout: interval) == :stop }
       self
     end
 
-    # Stops the periodic sweep thread and waits for a sweep in progress to finish.
-    def stop
-      return unless @thread
+    # Stops the periodic sweep thread and waits up to +timeout+ seconds (nil: for ever) for a sweep
+    # in progress to finish - one inspecting sessions of a Chrome that no longer answers can take
+    # far longer. A sweep still running then is left to finish on its own; the thread ends after it.
+    #
+    # @return [Boolean] true when the thread has ended.
+    def stop(timeout: DEFAULT_STOP_TIMEOUT)
+      return true unless @thread
 
       @wakeup << :stop
-      @thread.join
+      stopped = !@thread.join(timeout).nil?
+      Bidi2pdf.logger.warn "chrome_sweeper: a sweep of #{@session_url} still running after #{timeout}s - not waiting for it" unless stopped
       @thread = nil
+      stopped
     end
 
     private

data/lib/bidi2pdf/notifications/json_subscriber.rb

@@ -53,8 +53,9 @@ module Bidi2pdf
         write(event: "page_loaded")
       end
 
-      def on_network_idle(_event)
-        write(event: "network_idle")
+      # A wait that timed out is its own event: a consumer reading "network_idle" can trust it.
+      def on_network_idle(event)
+        write(event: event.payload[:timed_out] ? "network_idle_timeout" : "network_idle")
       end
 
       def on_console(event)

data/lib/bidi2pdf/notifications/logging_subscriber.rb

@@ -61,7 +61,7 @@ module Bidi2pdf
       def network_idle(event)
         return unless logger.info?
 
-        requests = event.payload[:requests]
+        requests = event.payload[:requests] || []
         transfered = requests.map { |request| request.bytes_received || 0 }.sum
         status_counts = requests
                           .group_by { |evt| evt.http_status_code || 0 }
@@ -70,8 +70,12 @@ module Bidi2pdf
                           .map { |code, count| "#{code}: #{count}" }
                           .join(", ")
 
-        logger.info "Network was idle after #{event.duration.round(1)}ms, #{requests.size} requests, " \
-                      "transferred #{transfered} bytes (status codes: #{status_counts})"
+        summary = "#{requests.size} requests, transferred #{transfered} bytes (status codes: #{status_counts})"
+        if event.payload[:timed_out]
+          logger.warn "Network was still busy after #{event.duration.round(1)}ms (timed out), #{summary}"
+        else
+          logger.info "Network was idle after #{event.duration.round(1)}ms, #{summary}"
+        end
       end
 
       # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity

data/lib/bidi2pdf/schema.rb

@@ -196,7 +196,8 @@ module Bidi2pdf
       "properties" => {
         "schema_version" => { "const" => 1 },
         "t_ms" => { "type" => "integer", "description" => "milliseconds since the render started" },
-        "event" => { "type" => "string", "enum" => %w[navigate page_loaded network_idle console print screenshot result] },
+        "event" => { "type" => "string", "enum" => %w[navigate page_loaded network_idle network_idle_timeout console print screenshot result],
+                     "description" => "network_idle_timeout: the wait for an idle network gave up with requests still open" },
         "url" => { "type" => "string", "description" => "present on a navigate event" },
         "level" => { "type" => "string", "description" => "present on a console event" },
         "text" => { "type" => "string", "description" => "present on a console event" },

data/lib/bidi2pdf/session_warmer.rb

@@ -72,7 +72,15 @@ module Bidi2pdf
       #   pressure and try once more. Default true; false leaves a refused session to the caller.
       attr_accessor :retry_refused_sessions
 
+      # @return [Numeric, nil] Seconds #shutdown waits, all in all, for its background threads and
+      #   for closing the warm spares. A Chrome that hangs or ran out of memory answers no command,
+      #   and every close would wait out its own timeout - an exiting process must not hang on that.
+      #   What is still running then is left behind (a warning, +session_warmer.shutdown_timeout+);
+      #   its sessions stay in the registry and a later sweep closes them. +nil+ waits for ever.
+      attr_accessor :shutdown_timeout
+
       DEFAULT_MAX_IDLE_AGE = 300
+      DEFAULT_SHUTDOWN_TIMEOUT = 10
 
       def initialize
         @size = 1
@@ -85,6 +93,7 @@ module Bidi2pdf
         @registry_dir = nil
         @sweeper = nil
         @retry_refused_sessions = true
+        @shutdown_timeout = DEFAULT_SHUTDOWN_TIMEOUT
       end
 
       # The orphan age in seconds, or nil when the sweep is off (also when +:auto+ has no
@@ -93,12 +102,20 @@ module Bidi2pdf
         orphan_age == :auto ? max_idle_age && (max_idle_age * 2) : orphan_age
       end
 
+      # nil (no limit) or a positive number of seconds - for shutdown_timeout and #shutdown's argument.
+      def self.validate_timeout!(name, value)
+        return if value.nil? || (value.is_a?(Numeric) && value.positive?)
+
+        raise ArgumentError, "#{name} must be nil or a positive number of seconds, got #{value.inspect}"
+      end
+
       # @raise [ArgumentError] if a setting can't be honored - checked once, at construction.
       def validate!
         validate_size!
         validate_max_idle_age!
         validate_orphan_age!
         validate_sweeper!
+        validate_shutdown_timeout!
       end
 
       private
@@ -121,6 +138,10 @@ module Bidi2pdf
         raise ArgumentError, "orphan_age must be :auto, nil or a positive number of seconds, got #{orphan_age.inspect}"
       end
 
+      def validate_shutdown_timeout!
+        Configuration.validate_timeout!("shutdown_timeout", shutdown_timeout)
+      end
+
       def validate_sweeper!
         return if sweeper.nil? || sweeper.is_a?(Hash)
 
@@ -273,20 +294,78 @@ module Bidi2pdf
     # finish (each of those, seeing @shutdown, retires its own result instead of stashing it - see
     # #stash_or_retire). A subsequent #with_tab still works - it just falls back to a synchronous
     # slot, since checkout never depends on a warm one being there.
-    def shutdown
-      spares, threads = @mutex.synchronize do
+    #
+    # All of that within +timeout+ seconds together (Configuration#shutdown_timeout; nil waits for
+    # ever). The spares start closing first, side by side, so a hung sweep cannot use up their share
+    # of the deadline. Whatever is still running at the deadline is left to finish on its own, or to
+    # die with the process; a spare still closing loses its lease (it keeps its registry entry), so
+    # a sweeper can take its session even while this process lives on.
+    #
+    # @return [Hash{String => Integer}] what was still running at the deadline ("spare" => 1, ...) -
+    #   empty when everything finished in time.
+    # @raise [ArgumentError] for a +timeout+ that is neither nil nor a positive number.
+    def shutdown(timeout: @config.shutdown_timeout)
+      Configuration.validate_timeout!("timeout", timeout)
+      spares, threads = stop_accepting
+      deadline = timeout && (now + timeout)
+      closers = retire_all(spares)
+      pending = (stop_background(threads, deadline) + abandoned_spares(closers, deadline)).tally
+      warn_abandoned(pending, timeout) unless pending.empty?
+      pending
+    end
+
+    private
+
+    def stop_accepting
+      @mutex.synchronize do
         @shutdown = true
         [@available.dup.tap { @available.clear }, @replenish_threads.dup.tap { @replenish_threads.clear }]
       end
+    end
 
+    # The labels of whatever is still running at the deadline: reaper, sweeper, replenishments.
+    def stop_background(threads, deadline)
       @reaper_wakeup << :stop
-      @reaper&.join
-      @sweeper&.stop
-      threads.each(&:join)
-      spares.each { |slot| retire(slot) }
+      pending = unfinished([@reaper].compact, deadline, "reaper")
+      pending << "sweeper" unless @sweeper.nil? || @sweeper.stop(timeout: remaining(deadline))
+      pending + unfinished(threads, deadline, "replenishment")
     end
 
-    private
+    def remaining(deadline)
+      deadline && [deadline - now, 0].max
+    end
+
+    # Thread#join returns nil when the time ran out first.
+    def unfinished(threads, deadline, label)
+      threads.reject { |thread| thread.join(remaining(deadline)) }.map { label }
+    end
+
+    # [slot, closing thread] pairs.
+    def retire_all(slots)
+      slots.map do |slot|
+        closer = Thread.new do
+          retire(slot)
+        rescue StandardError => e
+          Bidi2pdf.logger.warn "session_warmer: retiring a spare failed: #{e.message}"
+        end
+        [slot, closer]
+      end
+    end
+
+    # Spares still closing at the deadline, with their lease released: the heartbeat would otherwise
+    # keep renewing it, and no sweeper takes a leased session.
+    def abandoned_spares(closers, deadline)
+      closers.reject { |_, closer| closer.join(remaining(deadline)) }.map do |slot, _|
+        @registry&.release(session_id_of(slot))
+        "spare"
+      end
+    end
+
+    # Only called with something pending, which needs a deadline - so +timeout+ is a number here.
+    def warn_abandoned(pending, timeout)
+      Bidi2pdf.logger.warn "session_warmer: shutdown gave up after #{timeout}s, still running: #{pending.map { |what, count| "#{count} #{what}" }.join(", ")}"
+      Bidi2pdf.notification_service.instrument("session_warmer.shutdown_timeout.bidi2pdf", { timeout: timeout, pending: pending })
+    end
 
     # Fail-fast on purpose (a Chrome that can't start at boot should be loud), but not leaky: if slot
     # N fails, no instance is returned to own slots 1..N-1, so they are retired here first.

data/lib/bidi2pdf/test_helpers/testcontainers/chromedriver_container.rb

@@ -10,6 +10,14 @@ module Bidi2pdf
         # then sits silently in the pull for many minutes.
         DEFAULT_IMAGE = "dieters877565/chromedriver:latest"
 
+        # BIDI2PDF_BUILD_CHROMEDRIVER_IMAGE=true: build the image from the checkout (build_dir,
+        # docker_file) and run that, so a change to the image is tested before it is published -
+        # bidi2pdf's own CI sets it. Unset, the published image is pulled. Testcontainers' #start
+        # always pulls, so a locally built tag cannot go through it; #start_local_image builds instead.
+        def self.build_locally?(env = ENV)
+          env["BIDI2PDF_BUILD_CHROMEDRIVER_IMAGE"] == "true"
+        end
+
         attr_reader :docker_file, :build_dir
 
         def initialize(image = DEFAULT_IMAGE, **options)

data/lib/bidi2pdf/test_helpers/testcontainers/chromedriver_test_helper.rb

@@ -132,7 +132,7 @@ def start_chromedriver_container(build_dir:, mounts:, shared_network:, chromedri
 
   container.with_filesystem_binds(mounts) if mounts&.any?
 
-  container.start
+  ChromedriverTestcontainer.build_locally? ? container.start_local_image : container.start
 
   container
 end

data/lib/bidi2pdf/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bidi2pdf
-  VERSION = "0.1.20"
+  VERSION = "0.1.22"
 end

data/sig/bidi2pdf/bidi/browser_tab.rbs

@@ -169,10 +169,13 @@ module Bidi2pdf
       # @return [Object] The result from the style creation promise.
       def inject_style: (?url: untyped?, ?content: untyped?, ?id: untyped?) -> untyped
 
-      # Waits until the network is idle in the browser tab.
+      # Waits until the network is idle in the browser tab. A timeout does not raise: the
+      # network_idle.bidi2pdf event then carries +timed_out: true+, so subscribers never report a busy
+      # page as idle.
       #
       # @param [Integer] timeout The timeout duration in seconds. Defaults to 10.
       # @param [Float] poll_interval The polling interval in seconds. Defaults to 0.1.
+      # @return [Symbol] :idle or :timeout
       def wait_until_network_idle: (?timeout: ::Integer, ?poll_interval: ::Float) -> untyped
 
       # Waits until the page is fully loaded in the browser tab.
@@ -227,6 +230,14 @@ module Bidi2pdf
       # @param [Float, nil] device_pixel_ratio Defaults to nil (browser default).
       def set_viewport: (width: untyped, height: untyped, ?device_pixel_ratio: untyped?) -> untyped
 
+      # Switches JavaScript off (or on again) for this tab, through Chrome's own
+      # Emulation.setScriptExecutionDisabled (CDP, via goog:cdp.sendCommand). Call it before
+      # navigating: it holds for every later navigation in the tab, so a page printed from untrusted
+      # HTML runs none of its scripts.
+      #
+      # @param [Boolean] disabled Defaults to true.
+      def disable_script_execution: (?disabled: bool) -> untyped
+
       private
 
       def build_command_and_extractor: (untyped print_options) -> ::Array[untyped]

data/sig/bidi2pdf/bidi/network_events.rbs

@@ -24,7 +24,14 @@ module Bidi2pdf
 
       def log_network_traffic: (?format: ::Symbol) -> untyped
 
-      def wait_until_network_idle: (?timeout: ::Integer, ?poll_interval: ::Float) -> untyped
+      # Waits until no request is in flight, or until +timeout+ seconds passed.
+      #
+      # @return [Symbol] :idle when every request completed, :timeout when some were still open -
+      #   it never raises for a timeout, so a caller decides whether a busy page is good enough.
+      def wait_until_network_idle: (?timeout: ::Integer, ?poll_interval: ::Float) -> (:idle | :timeout | untyped)
+
+      # Names the requests still open when the wait gives up - it carries on, it does not raise.
+      def log_idle_timeout: () -> untyped
     end
   end
 end

data/sig/bidi2pdf/chrome_sweeper/settings.rbs

@@ -14,6 +14,8 @@ module Bidi2pdf
 
     DEFAULT_LEASE_TTL: untyped
 
+    DEFAULT_STOP_TIMEOUT: 10
+
     # What a ChromeSweeper closes and when - validated on construction; an unknown setting raises
     # ArgumentError.
     #

data/sig/bidi2pdf/chrome_sweeper.rbs

@@ -133,11 +133,18 @@ module Bidi2pdf
     # @return [Result]
     def sweep!: (?reason: ::Symbol, ?check_interval: untyped?, ?pressure: bool) -> untyped
 
-    # Starts the periodic sweep thread (needs an +interval+). Idempotent.
+    # Starts the periodic sweep thread (needs an +interval+). Idempotent. Each thread has its own
+    # wakeup queue, so one that #stop stopped waiting for can never take a later thread's :stop.
+    # After such a #stop, a new thread can sweep while the abandoned sweep is still running: the
+    # lock file lets only one of them sweep at a time, the other's sweep is skipped.
     def start: () -> self
 
-    # Stops the periodic sweep thread and waits for a sweep in progress to finish.
-    def stop: () -> (nil | untyped)
+    # Stops the periodic sweep thread and waits up to +timeout+ seconds (nil: for ever) for a sweep
+    # in progress to finish - one inspecting sessions of a Chrome that no longer answers can take
+    # far longer. A sweep still running then is left to finish on its own; the thread ends after it.
+    #
+    # @return [Boolean] true when the thread has ended.
+    def stop: (?timeout: untyped) -> (true | untyped)
 
     private
 

data/sig/bidi2pdf/notifications/json_subscriber.rbs

@@ -31,7 +31,8 @@ module Bidi2pdf
 
       def on_page_loaded: (untyped _event) -> untyped
 
-      def on_network_idle: (untyped _event) -> untyped
+      # A wait that timed out is its own event: a consumer reading "network_idle" can trust it.
+      def on_network_idle: (untyped event) -> untyped
 
       def on_console: (untyped event) -> untyped
 

data/sig/bidi2pdf/schema.rbs

@@ -26,7 +26,7 @@ module Bidi2pdf
 
     MANIFEST: { "$schema" => "https://json-schema.org/draft/2020-12/schema", "title" => "Bidi2pdf render manifest", "description" => "--manifest FILE output", "type" => "object", "required" => ::Array["schema_version" | "bidi2pdf_version" | "created_at" | "input" | "output" | "navigation" | "render"], "properties" => { "schema_version" => { "const" => 1 }, "bidi2pdf_version" => { "type" => "string" }, "created_at" => { "type" => "string", "format" => "date-time" }, "input" => { "type" => "object", "required" => ::Array["type"], "properties" => { "type" => { "type" => "string", "enum" => ::Array["url" | "html_file" | "stdin"] }, "url" => { "type" => ::Array["string" | "null"] } } }, "output" => { "type" => "object", "properties" => { "path" => { "type" => ::Array["string" | "null"] }, "pages" => { "type" => ::Array["integer" | "null"] }, "bytes" => { "type" => ::Array["integer" | "null"] }, "sha256" => { "type" => ::Array["string" | "null"] } } }, "browser" => { "type" => "object" }, "navigation" => untyped, "render" => { "type" => "object", "properties" => { "duration_ms" => { "type" => ::Array["integer" | "null"] } } }, "console" => untyped, "network_failures" => untyped, "warnings" => untyped, "headers" => { "type" => "object", "description" => "present only when custom headers were given; secret-bearing values are redacted" } } }
 
-    EVENT: { "$schema" => "https://json-schema.org/draft/2020-12/schema", "title" => "Bidi2pdf --json-stream event", "description" => "one JSON object per stderr line while --json-stream is active. In structured mode (--json/--output -), the last line is always {event: \"result\", result: <the matching command's own schema - see \"result\"'s own oneOf>}. In human mode (--json-stream given alone), only progress events are emitted - there is no synthetic final \"result\" event, since there is no structured result being built; the human-readable log is the completion/failure signal.", "type" => "object", "required" => ::Array["schema_version" | "t_ms" | "event"], "properties" => { "schema_version" => { "const" => 1 }, "t_ms" => { "type" => "integer", "description" => "milliseconds since the render started" }, "event" => { "type" => "string", "enum" => ::Array["navigate" | "page_loaded" | "network_idle" | "console" | "print" | "screenshot" | "result"] }, "url" => { "type" => "string", "description" => "present on a navigate event" }, "level" => { "type" => "string", "description" => "present on a console event" }, "text" => { "type" => "string", "description" => "present on a console event" }, "result" => { "description" => "present only on the final \"result\" event (structured mode only); shape depends on which command produced this stream - each branch's own \"command\" value disambiguates", "oneOf" => ::Array[untyped] } } }
+    EVENT: { "$schema" => "https://json-schema.org/draft/2020-12/schema", "title" => "Bidi2pdf --json-stream event", "description" => "one JSON object per stderr line while --json-stream is active. In structured mode (--json/--output -), the last line is always {event: \"result\", result: <the matching command's own schema - see \"result\"'s own oneOf>}. In human mode (--json-stream given alone), only progress events are emitted - there is no synthetic final \"result\" event, since there is no structured result being built; the human-readable log is the completion/failure signal.", "type" => "object", "required" => ::Array["schema_version" | "t_ms" | "event"], "properties" => { "schema_version" => { "const" => 1 }, "t_ms" => { "type" => "integer", "description" => "milliseconds since the render started" }, "event" => { "type" => "string", "enum" => ::Array["navigate" | "page_loaded" | "network_idle" | "network_idle_timeout" | "console" | "print" | "screenshot" | "result"], "description" => "network_idle_timeout: the wait for an idle network gave up with requests still open" }, "url" => { "type" => "string", "description" => "present on a navigate event" }, "level" => { "type" => "string", "description" => "present on a console event" }, "text" => { "type" => "string", "description" => "present on a console event" }, "result" => { "description" => "present only on the final \"result\" event (structured mode only); shape depends on which command produced this stream - each branch's own \"command\" value disambiguates", "oneOf" => ::Array[untyped] } } }
 
     RECIPE_SOURCE: { "description" => "exactly one of url, file, stdin", "oneOf" => ::Array[{ "type" => "object", "required" => ::Array["url"], "properties" => { "url" => { "type" => "string" } }, "additionalProperties" => false } | { "type" => "object", "required" => ::Array["file"], "properties" => { "file" => { "type" => "string" } }, "additionalProperties" => false } | { "type" => "object", "required" => ::Array["stdin"], "properties" => { "stdin" => { "const" => true } }, "additionalProperties" => false }] }
 

data/sig/bidi2pdf/session_warmer.rbs

@@ -72,6 +72,8 @@ module Bidi2pdf
 
       @retry_refused_sessions: untyped
 
+      @shutdown_timeout: untyped
+
       # @return [Integer] Number of Chrome slots to keep pre-warmed.
       attr_accessor size: untyped
 
@@ -120,14 +122,26 @@ module Bidi2pdf
       #   pressure and try once more. Default true; false leaves a refused session to the caller.
       attr_accessor retry_refused_sessions: untyped
 
+      # @return [Numeric, nil] Seconds #shutdown waits, all in all, for its background threads and
+      #   for closing the warm spares. A Chrome that hangs or ran out of memory answers no command,
+      #   and every close would wait out its own timeout - an exiting process must not hang on that.
+      #   What is still running then is left behind (a warning, +session_warmer.shutdown_timeout+);
+      #   its sessions stay in the registry and a later sweep closes them. +nil+ waits for ever.
+      attr_accessor shutdown_timeout: untyped
+
       DEFAULT_MAX_IDLE_AGE: 300
 
+      DEFAULT_SHUTDOWN_TIMEOUT: 10
+
       def initialize: () -> void
 
       # The orphan age in seconds, or nil when the sweep is off (also when +:auto+ has no
       # max_idle_age to derive it from).
       def effective_orphan_age: () -> untyped
 
+      # nil (no limit) or a positive number of seconds - for shutdown_timeout and #shutdown's argument.
+      def self.validate_timeout!: (untyped name, untyped value) -> (nil | untyped)
+
       # @raise [ArgumentError] if a setting can't be honored - checked once, at construction.
       def validate!: () -> untyped
 
@@ -139,6 +153,8 @@ module Bidi2pdf
 
       def validate_orphan_age!: () -> (nil | untyped)
 
+      def validate_shutdown_timeout!: () -> untyped
+
       def validate_sweeper!: () -> (nil | untyped)
     end
 
@@ -204,10 +220,40 @@ module Bidi2pdf
     # finish (each of those, seeing @shutdown, retires its own result instead of stashing it - see
     # #stash_or_retire). A subsequent #with_tab still works - it just falls back to a synchronous
     # slot, since checkout never depends on a warm one being there.
-    def shutdown: () -> untyped
+    #
+    # All of that within +timeout+ seconds together (Configuration#shutdown_timeout; nil waits for
+    # ever). The spares start closing first, side by side, so a hung sweep cannot use up their share
+    # of the deadline. Whatever is still running at the deadline is left to finish on its own, or to
+    # die with the process; a spare still closing loses its lease (it keeps its registry entry), so
+    # a sweeper can take its session even while this process lives on.
+    #
+    # @return [Hash{String => Integer}] what was still running at the deadline ("spare" => 1, ...) -
+    #   empty when everything finished in time.
+    # @raise [ArgumentError] for a +timeout+ that is neither nil nor a positive number.
+    def shutdown: (?timeout: untyped) -> untyped
 
     private
 
+    def stop_accepting: () -> untyped
+
+    # The labels of whatever is still running at the deadline: reaper, sweeper, replenishments.
+    def stop_background: (untyped threads, untyped deadline) -> untyped
+
+    def remaining: (untyped deadline) -> untyped
+
+    # Thread#join returns nil when the time ran out first.
+    def unfinished: (untyped threads, untyped deadline, untyped label) -> untyped
+
+    # [slot, closing thread] pairs.
+    def retire_all: (untyped slots) -> untyped
+
+    # Spares still closing at the deadline, with their lease released: the heartbeat would otherwise
+    # keep renewing it, and no sweeper takes a leased session.
+    def abandoned_spares: (untyped closers, untyped deadline) -> untyped
+
+    # Only called with something pending, which needs a deadline - so +timeout+ is a number here.
+    def warn_abandoned: (untyped pending, untyped timeout) -> untyped
+
     # Fail-fast on purpose (a Chrome that can't start at boot should be loud), but not leaky: if slot
     # N fails, no instance is returned to own slots 1..N-1, so they are retired here first.
     def prewarm: () -> untyped

data/sig/bidi2pdf/test_helpers/testcontainers/chromedriver_container.rbs

@@ -23,6 +23,12 @@ module Bidi2pdf
         # then sits silently in the pull for many minutes.
         DEFAULT_IMAGE: "dieters877565/chromedriver:latest"
 
+        # BIDI2PDF_BUILD_CHROMEDRIVER_IMAGE=true: build the image from the checkout (build_dir,
+        # docker_file) and run that, so a change to the image is tested before it is published -
+        # bidi2pdf's own CI sets it. Unset, the published image is pulled. Testcontainers' #start
+        # always pulls, so a locally built tag cannot go through it; #start_local_image builds instead.
+        def self.build_locally?: (?untyped env) -> untyped
+
         attr_reader docker_file: untyped
 
         attr_reader build_dir: untyped

data/sig/bidi2pdf/version.rbs

@@ -1,3 +1,3 @@
 module Bidi2pdf
-  VERSION: "0.1.20"
+  VERSION: "0.1.22"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bidi2pdf
 version: !ruby/object:Gem::Version
-  version: 0.1.20
+  version: 0.1.22
 platform: ruby
 authors:
 - Dieter S.
@@ -408,8 +408,10 @@ files:
 - docker/Dockerfile.chromedriver
 - docker/Dockerfile.slim
 - docker/chrome-driver/chrome.json
+- docker/chromedriver-watchdog.sh
 - docker/docker-compose.yml
 - docker/entrypoint.sh
+- docker/install-hyphen-data.sh
 - docker/nginx/default.conf
 - docker/nginx/htpasswd
 - exe/bidi2pdf