fix(render): isolate Chrome --user-data-dir per worker (fixes #54) (#65)

Both CDP backends launched Chrome with --remote-debugging-port but no
--user-data-dir. On a machine that already has Chrome open (normal on a
desktop), the new invocation forwards to the running instance on the default
profile instead of starting its own headless renderer: the CDP endpoint comes
up and trivial Runtime.evaluate works, but Page.navigate never commits and
Page.captureScreenshot hangs forever — every URL fails with done=0 after a
~180s timeout. This is the second of the two root causes in #54 (the first,
picking a non-page CDP target, was fixed in #56). It's masked on Linux/CI
because the bundled headless_shell launches fresh with no competing instance.

Give each worker an isolated, throwaway profile via tempfile.mkdtemp, pass it
as --user-data-dir, and remove it on teardown (including the connect-failure
path in the turbo backend). A unique profile per worker also prevents parallel
workers from colliding on one profile.

Also document cross-platform Chrome resolution in the README (headless_shell is
linux-x64 only; Windows/macOS use auto-detected system Chrome or CHROME_PATH).

Verified on Windows 11 with system Chrome 149: pixelshot https://example.com now
returns done=1 failed=0 with a valid tile (was a ~180s failure); temp profiles
are cleaned up; existing render/chrome tests pass.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: dex0shubham

README.md

@@ -230,6 +230,13 @@ pixelshot paper.pdf -o ./tiles --dpi 200
 pixelshot https://github.com/StarTrail-org/PixelRAG paper.pdf -o ./tiles
 ```
 
+> **Chrome on Windows/macOS** — the bundled turbo `headless_shell` auto-installs on
+> **linux-x64** only. Elsewhere, `pixelshot` uses your system Chrome/Chromium (or
+> Playwright's Chromium), auto-detected from the standard install locations. Point it at
+> a specific binary with `CHROME_PATH=/path/to/chrome` if it isn't found automatically.
+> Each render runs in an isolated, throwaway Chrome profile, so it works even while you
+> have Chrome open.
+
 ### Embed tools (standalone)
 
 Each stage runs independently, without the orchestrator:

render/src/pixelrag_render/backends/cdp.py

@@ -24,8 +24,10 @@
 import io
 import json
 import logging
+import shutil
 import signal
 import subprocess
+import tempfile
 import time
 import urllib.request
 from pathlib import Path
@@ -314,11 +316,21 @@ async def _worker(
     results: list,
 ):
     """Async worker: owns a Chrome process, pulls URLs from queue."""
+    # Isolated profile per worker. Without --user-data-dir, a launch on a machine that
+    # already has Chrome open forwards to the running instance (default profile) instead
+    # of starting this headless renderer — navigation/screenshot then hang forever. A
+    # unique dir also stops parallel workers from colliding on one profile. See issue #54.
+    user_data_dir = tempfile.mkdtemp(prefix=f"pixelshot_chrome_{port}_")
     proc = subprocess.Popen(
         # `--headless=new`: the bare `--headless` is deprecated and hangs on modern
         # Chrome (e.g. google-chrome 149); `=new` works on both stock Chrome and the
         # patched headless_shell.
-        [chrome_path, f"--remote-debugging-port={port}", "--headless=new"]
+        [
+            chrome_path,
+            f"--remote-debugging-port={port}",
+            "--headless=new",
+            f"--user-data-dir={user_data_dir}",
+        ]
         + BROWSER_ARGS
         + ["about:blank"],
         stdout=subprocess.DEVNULL,
@@ -388,6 +400,7 @@ async def _worker(
             proc.wait(timeout=5)
         except subprocess.TimeoutExpired:
             proc.kill()
+        shutil.rmtree(user_data_dir, ignore_errors=True)
 
 
 def _derive_stems(urls: list[str], stems: list[str] | None) -> list[str]:

render/src/pixelrag_render/backends/fast_cdp.py

@@ -25,9 +25,11 @@
 import json
 import logging
 import os
+import shutil
 import signal
 import struct
 import subprocess
+import tempfile
 import time
 import urllib.request
 from pathlib import Path
@@ -115,12 +117,22 @@ def _next_base_port() -> int:
 
 
 async def _launch_chrome(chrome_path: str, port: int) -> tuple:
-    """Launch a headless Chrome and return (websocket, proc)."""
+    """Launch a headless Chrome and return (websocket, proc, user_data_dir)."""
     import websockets
 
+    # Isolated profile per worker. Without --user-data-dir, a launch on a machine that
+    # already has Chrome open forwards to the running instance (default profile) instead
+    # of starting this headless renderer — navigation/screenshot then hang forever. A
+    # unique dir also stops parallel workers from colliding on one profile. See issue #54.
+    user_data_dir = tempfile.mkdtemp(prefix=f"pixelshot_chrome_{port}_")
     args = (
         # `--headless=new`: bare `--headless` is deprecated and hangs on modern Chrome.
-        [chrome_path, f"--remote-debugging-port={port}", "--headless=new"]
+        [
+            chrome_path,
+            f"--remote-debugging-port={port}",
+            "--headless=new",
+            f"--user-data-dir={user_data_dir}",
+        ]
         + CHROME_ARGS
         + ["about:blank"]
     )
@@ -142,19 +154,21 @@ async def _launch_chrome(chrome_path: str, port: int) -> tuple:
                 open_timeout=10,
                 max_size=50 * 1024 * 1024,
             )
-            return ws, proc
+            return ws, proc, user_data_dir
         except Exception:
             if attempt == 9:
                 proc.kill()
+                shutil.rmtree(user_data_dir, ignore_errors=True)
                 raise ConnectionError(f"Failed to connect to Chrome on port {port}")
 
 
 class _Conn:
     """Minimal CDP connection with a receive loop."""
 
-    def __init__(self, ws, proc):
+    def __init__(self, ws, proc, user_data_dir=None):
         self._ws = ws
         self._proc = proc
+        self._user_data_dir = user_data_dir
         self._msg_id = 0
         self._pending: dict[int, asyncio.Future] = {}
         self._event_listeners: dict[str, list] = {}
@@ -238,6 +252,8 @@ async def close(self):
             self._proc.wait(timeout=5)
         except subprocess.TimeoutExpired:
             self._proc.kill()
+        if self._user_data_dir:
+            shutil.rmtree(self._user_data_dir, ignore_errors=True)
 
 
 # ---------------------------------------------------------------------------
@@ -328,8 +344,8 @@ def _compressor_thread():
         base_port + n_workers - 1,
     )
     for i in range(n_workers):
-        ws, proc = await _launch_chrome(chrome_path, base_port + i)
-        conn = _Conn(ws, proc)
+        ws, proc, user_data_dir = await _launch_chrome(chrome_path, base_port + i)
+        conn = _Conn(ws, proc, user_data_dir)
         connections.append(conn)
 
     for i, conn in enumerate(connections):