重开仓库内容：改推五个技能（browser-harness / humanizer / humanizer-zh / product-planning / session-mechanism）

按授权清空原有内容后重新提交（原 oil-ui-pro 一并移出，可从历史恢复）。
browser-harness 剔除 .venv 等运行环境；根 .gitignore 补记 .venv/ 与 node_modules/。

browser-harness/src/browser_harness/__init__.py

@@ -0,0 +1,2 @@
+"""Browser Harness core package."""
+

browser-harness/src/browser_harness/_ipc.py

@@ -0,0 +1,201 @@
+"""Daemon IPC plumbing. AF_UNIX socket on POSIX, TCP loopback on Windows."""
+import asyncio, json, os, re, secrets, socket, subprocess, sys
+from pathlib import Path
+
+from . import paths
+
+IS_WINDOWS = sys.platform == "win32"
+# Two caller-supplied dirs:
+#   BH_RUNTIME_DIR — sock/port/pid. AF_UNIX sun_path is 104 bytes on macOS, so
+#       the runtime dir must be short. Caller is responsible for keeping it
+#       within budget. Falls back to BH_TMP_DIR (legacy single-dir callers),
+#       then to the browser-harness runtime dir.
+#   BH_TMP_DIR — screenshots, debug overlays, daemon log. No path-length
+#       sensitivity; caller can use a deep persistent path.
+# By default, a caller-supplied dir is treated as per-instance and files use
+# bare "bu" stems. Set BH_RUNTIME_DIR_SHARED=1 or BH_TMP_DIR_SHARED=1 when the
+# dir is shared by multiple BU_NAME values and the filename must carry the name.
+BH_TMP_DIR = os.environ.get("BH_TMP_DIR")
+BH_RUNTIME_DIR = os.environ.get("BH_RUNTIME_DIR") or BH_TMP_DIR
+BH_RUNTIME_DIR_SHARED = os.environ.get("BH_RUNTIME_DIR_SHARED") == "1"
+BH_TMP_DIR_SHARED = os.environ.get("BH_TMP_DIR_SHARED") == "1"
+_TMP = paths.tmp_dir()
+_RUNTIME = paths.ensure_private_dir(Path(BH_RUNTIME_DIR).expanduser().resolve()) if BH_RUNTIME_DIR else paths.runtime_dir()
+_TMP.mkdir(parents=True, exist_ok=True)
+_RUNTIME.mkdir(parents=True, exist_ok=True)
+_NAME_RE = re.compile(r"\A[A-Za-z0-9_-]{1,64}\Z")
+
+# Set by serve() on Windows. Daemon's handle() requires every request to carry
+# this token (TCP loopback has no chmod-equivalent so any local process could
+# otherwise issue CDP commands). Stays None on POSIX where AF_UNIX + chmod 600
+# is the boundary.
+_server_token = None
+
+
+def _check(name):  # path-traversal guard for BU_NAME
+    if not _NAME_RE.match(name or ""):
+        raise ValueError(f"invalid BU_NAME {name!r}: must match [A-Za-z0-9_-]{{1,64}}")
+    return name
+
+
+def _runtime_stem(name):  # "bu" when BH_RUNTIME_DIR isolates us, else "bu-<NAME>"
+    _check(name)
+    return "bu" if BH_RUNTIME_DIR and not BH_RUNTIME_DIR_SHARED else f"bu-{name}"
+
+
+def _tmp_stem(name):  # "bu" when BH_TMP_DIR isolates us, else "bu-<NAME>"
+    _check(name)
+    return "bu" if BH_TMP_DIR and not BH_TMP_DIR_SHARED else f"bu-{name}"
+
+
+def log_path(name):   return _TMP / f"{_tmp_stem(name)}.log"
+def pid_path(name):   return _RUNTIME / f"{_runtime_stem(name)}.pid"
+def port_path(name):  return _RUNTIME / f"{_runtime_stem(name)}.port"  # Windows-only: holds {"port","token"} JSON
+def _sock_path(name): return _RUNTIME / f"{_runtime_stem(name)}.sock"
+
+
+def _read_port_file(name):
+    """(port, token) from the Windows port file, or (None, None) on any failure."""
+    try:
+        d = json.loads(port_path(name).read_text(encoding="utf-8"))
+        return int(d["port"]), d["token"]
+    except (FileNotFoundError, ValueError, KeyError, TypeError, OSError):
+        return None, None
+
+
+def sock_addr(name):  # display-only, used in log lines
+    if not IS_WINDOWS: return str(_sock_path(name))
+    port, _ = _read_port_file(name)
+    return f"127.0.0.1:{port}" if port else f"tcp:{_runtime_stem(name)}"
+
+
+def spawn_kwargs():  # subprocess.Popen flags so the daemon detaches from this terminal
+    if IS_WINDOWS:
+        # CREATE_NO_WINDOW: no console window for the daemon. CREATE_NEW_PROCESS_GROUP:
+        # daemon doesn't receive Ctrl-C/Ctrl-Break sent to the parent terminal, so
+        # closing that terminal doesn't kill it. DETACHED_PROCESS is intentionally
+        # omitted: per Win32 docs it overrides CREATE_NO_WINDOW, causing Windows to
+        # allocate a fresh console for the (still console-subsystem) python.exe.
+        return {"creationflags": subprocess.CREATE_NEW_PROCESS_GROUP | subprocess.CREATE_NO_WINDOW}
+    return {"start_new_session": True}
+
+
+def connect(name, timeout=1.0):
+    """Blocking client. Returns (sock, token); token is None on POSIX, hex string on Windows.
+    Callers sending JSON requests MUST include the token as req["token"] on Windows."""
+    if not IS_WINDOWS:
+        # uv-Python on Windows lacks socket.AF_UNIX, so this branch must be gated.
+        s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        s.settimeout(timeout); s.connect(str(_sock_path(name))); return s, None
+    port, token = _read_port_file(name)
+    if port is None: raise FileNotFoundError(str(port_path(name)))
+    s = socket.create_connection(("127.0.0.1", port), timeout=timeout)
+    s.settimeout(timeout); return s, token
+
+
+def request(c, token, req):
+    """One-shot send + recv + parse on an open socket. Injects token on Windows.
+    Returns the parsed JSON response. Caller closes the socket."""
+    if token: req = {**req, "token": token}
+    c.sendall((json.dumps(req) + "\n").encode())
+    data = b""
+    while not data.endswith(b"\n"):
+        chunk = c.recv(1 << 16)
+        if not chunk: break
+        data += chunk
+    return json.loads(data or b"{}")
+
+
+def ping(name, timeout=1.0):
+    """True iff a live daemon answers our ping. Defends against stale .port files
+    + port reuse: a bare TCP connect can succeed against an unrelated process that
+    grabbed the port after our daemon crashed; only our daemon answers {"pong":true}."""
+    try:
+        c, token = connect(name, timeout=timeout)
+    except (FileNotFoundError, ConnectionRefusedError, TimeoutError, socket.timeout, OSError):
+        return False
+    try:
+        resp = request(c, token, {"meta": "ping"})
+        # request() returns parsed JSON, which may be any valid value (a list,
+        # scalar, etc. from a stale or hostile endpoint). Anything that isn't
+        # a {pong: true} dict counts as "not our daemon" — never .get() blindly.
+        return isinstance(resp, dict) and resp.get("pong") is True
+    except (OSError, ValueError, AttributeError):
+        return False
+    finally:
+        try: c.close()
+        except OSError: pass
+
+
+def identify(name, timeout=1.0):
+    """Return the live daemon's PID, or None if unreachable.
+
+    Used by restart_daemon() to signal a process whose identity has been
+    verified end-to-end (live IPC + self-reported PID), instead of trusting
+    a pid file whose number may have been reused by an unrelated process."""
+    try:
+        c, token = connect(name, timeout=timeout)
+    except (FileNotFoundError, ConnectionRefusedError, TimeoutError, socket.timeout, OSError):
+        return None
+    try:
+        resp = request(c, token, {"meta": "ping"})
+        # request() returns parsed JSON, which may be any valid value (a list,
+        # scalar, etc. from a stale or hostile endpoint). Anything that isn't
+        # a {pong: true} dict gets None — never .get() on a non-dict.
+        if not isinstance(resp, dict) or resp.get("pong") is not True:
+            return None
+        pid = resp.get("pid")
+        # `type(pid) is int` (not isinstance) intentionally rejects bool: in
+        # Python, isinstance(True, int) is True, so a hostile/buggy daemon
+        # could reply with {"pid": True} and we'd treat that as PID 1 (init).
+        # Also reject 0/negatives — os.kill(0, sig) signals every process in
+        # the calling process group, os.kill(-1, sig) signals every process
+        # the caller can. Upper bound is 2**31 because C pid_t is typically
+        # signed 32-bit and a value outside that range makes os.kill() raise
+        # OverflowError, which would propagate out of restart_daemon() before
+        # its cleanup. Linux pid_max is also bounded at 2**22 in practice.
+        return pid if type(pid) is int and 0 < pid < (1 << 31) else None
+    except (OSError, ValueError, AttributeError):
+        return None
+    finally:
+        try: c.close()
+        except OSError: pass
+
+
+async def serve(name, handler):
+    """Run the server until cancelled. handler(reader, writer) sees the same interface either way."""
+    global _server_token
+    if not IS_WINDOWS:
+        path = str(_sock_path(name))
+        if os.path.exists(path): os.unlink(path)
+        # umask 0o077 makes bind() create the socket as 0600 — no TOCTOU window before chmod.
+        old_umask = os.umask(0o077)
+        try: server = await asyncio.start_unix_server(handler, path=path)
+        finally: os.umask(old_umask)
+        _server_token = None
+        async with server: await asyncio.Event().wait()
+        return
+    server = await asyncio.start_server(handler, "127.0.0.1", 0)
+    port = server.sockets[0].getsockname()[1]
+    _server_token = secrets.token_hex(32)
+    pf = port_path(name)
+    # Atomic write so a concurrent reader never sees a half-written file.
+    tmp = pf.with_name(pf.name + ".tmp")
+    tmp.write_text(json.dumps({"port": port, "token": _server_token}), encoding="utf-8")
+    os.replace(tmp, pf)
+    try:
+        async with server: await asyncio.Event().wait()
+    finally:
+        try: pf.unlink()
+        except FileNotFoundError: pass
+
+
+def expected_token():
+    """The token the running daemon will accept, or None on POSIX."""
+    return _server_token
+
+
+def cleanup_endpoint(name):  # best-effort; silent if already gone
+    p = _sock_path(name) if not IS_WINDOWS else port_path(name)
+    try: p.unlink()
+    except FileNotFoundError: pass

browser-harness/src/browser_harness/auth.py

@@ -0,0 +1,543 @@
+"""Browser Use Cloud auth for browser-harness.
+
+The model-facing contract stays small: cloud browser startup either has a key
+or tells the agent to run `browser-harness auth login`. OAuth details live here.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from http.server import BaseHTTPRequestHandler, HTTPServer
+import argparse
+import base64
+import getpass
+import hashlib
+import json
+import os
+from pathlib import Path
+import secrets
+import stat
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import webbrowser
+
+from . import paths
+
+
+AUTH_BASE = "https://api.browser-use.com"
+# Browser Use currently exposes this registered CLI OAuth client. Keep an env
+# escape hatch so a dedicated browser-harness client can be used once issued.
+DEFAULT_CLIENT_ID = "browser-use-terminal"
+CALLBACK_PATH = "/browser-use-cloud/callback"
+AUTH_TIMEOUT_SECONDS = 600
+
+
+class CloudAuthRequired(RuntimeError):
+    def __init__(self):
+        super().__init__("cloud-auth-required: run `browser-harness auth login`")
+
+
+class AuthError(RuntimeError):
+    pass
+
+
+@dataclass
+class PendingCallback:
+    state: str
+    code: str | None = None
+    error: str | None = None
+    error_description: str | None = None
+    complete: bool = False
+
+
+@dataclass
+class BrowserAuthStart:
+    server: HTTPServer
+    callback: PendingCallback
+    redirect_uri: str
+    verifier: str
+    auth_url: str
+    expires_in: int | None
+    opened: bool = False
+
+
+@dataclass
+class DeviceAuthStart:
+    device_code: str
+    user_code: str
+    verification_uri: str
+    verification_uri_complete: str | None = None
+    expires_in: int | None = None
+    interval: int = 5
+    opened: bool = False
+
+    @property
+    def open_uri(self) -> str:
+        return self.verification_uri_complete or self.verification_uri
+
+
+@dataclass
+class AuthRecord:
+    api_key: str
+    api_key_id: str | None = None
+    project_id: str | None = None
+    expires_at: str | None = None
+    scopes: list[str] = field(default_factory=list)
+    source: str = "oauth"
+
+    @classmethod
+    def from_token_response(cls, data: dict, *, source: str = "oauth") -> "AuthRecord":
+        api_key = data.get("api_key")
+        if not api_key:
+            raise AuthError("auth token response did not include an api_key")
+        scopes = data.get("scopes") or []
+        if not isinstance(scopes, list):
+            scopes = []
+        return cls(
+            api_key=api_key,
+            api_key_id=data.get("api_key_id"),
+            project_id=data.get("project_id"),
+            expires_at=data.get("expires_at"),
+            scopes=[str(s) for s in scopes],
+            source=source,
+        )
+
+    def to_storage(self) -> dict:
+        return {
+            "api_key": self.api_key,
+            "api_key_id": self.api_key_id,
+            "project_id": self.project_id,
+            "expires_at": self.expires_at,
+            "scopes": self.scopes,
+            "source": self.source,
+        }
+
+
+def auth_base() -> str:
+    return (os.environ.get("BROWSER_USE_CLOUD_API_URL") or AUTH_BASE).rstrip("/")
+
+
+def client_id() -> str:
+    return os.environ.get("BROWSER_HARNESS_OAUTH_CLIENT_ID") or DEFAULT_CLIENT_ID
+
+
+def auth_path() -> Path:
+    override = os.environ.get("BH_AUTH_PATH")
+    if override:
+        return Path(override).expanduser()
+    return paths.config_dir() / "auth.json"
+
+
+def load_auth_file(path: Path | None = None) -> dict:
+    path = path or auth_path()
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return {}
+    except (json.JSONDecodeError, UnicodeDecodeError) as e:
+        raise AuthError(f"auth file is not valid JSON: {path}") from e
+
+
+def save_auth_record(record: AuthRecord, path: Path | None = None) -> None:
+    path = path or auth_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    _chmod_private(path.parent, directory=True)
+    existing = load_auth_file(path)
+    existing["browser_use"] = record.to_storage()
+    tmp = path.with_name(path.name + ".tmp")
+    _write_private_json(tmp, existing)
+    os.replace(tmp, path)
+    _chmod_private(path)
+
+
+def clear_auth(path: Path | None = None) -> bool:
+    path = path or auth_path()
+    data = load_auth_file(path)
+    existed = bool(data.get("browser_use"))
+    data.pop("browser_use", None)
+    if data:
+        tmp = path.with_name(path.name + ".tmp")
+        _write_private_json(tmp, data)
+        os.replace(tmp, path)
+        _chmod_private(path)
+    else:
+        try:
+            path.unlink()
+        except FileNotFoundError:
+            pass
+    return existed
+
+
+def stored_auth_record(path: Path | None = None) -> dict | None:
+    data = load_auth_file(path)
+    value = data.get("browser_use")
+    return value if isinstance(value, dict) else None
+
+
+def get_browser_use_api_key() -> str:
+    env_key = os.environ.get("BROWSER_USE_API_KEY")
+    if env_key:
+        return env_key
+    stored = stored_auth_record()
+    key = stored.get("api_key") if stored else None
+    if key:
+        return str(key)
+    raise CloudAuthRequired()
+
+
+def auth_status() -> dict:
+    if os.environ.get("BROWSER_USE_API_KEY"):
+        return {"status": "authenticated", "source": "env", "path": str(auth_path())}
+    stored = stored_auth_record()
+    if not stored or not stored.get("api_key"):
+        return {"status": "missing", "source": None, "path": str(auth_path())}
+    return {"status": "authenticated", "source": "stored", "path": str(auth_path())}
+
+
+def pkce_pair() -> tuple[str, str]:
+    verifier = secrets.token_urlsafe(48)
+    digest = hashlib.sha256(verifier.encode()).digest()
+    challenge = base64.urlsafe_b64encode(digest).decode().rstrip("=")
+    return verifier, challenge
+
+
+def start_browser_auth(*, open_url=True, timeout=AUTH_TIMEOUT_SECONDS) -> BrowserAuthStart:
+    verifier, challenge = pkce_pair()
+    state = secrets.token_urlsafe(32)
+    callback = PendingCallback(state=state)
+    server = _callback_server(callback)
+    host, port = server.server_address
+    redirect_uri = f"http://{host}:{port}{CALLBACK_PATH}"
+    req = {
+        "client_id": client_id(),
+        "response_type": "code",
+        "redirect_uri": redirect_uri,
+        "code_challenge": challenge,
+        "code_challenge_method": "S256",
+        "state": state,
+        "device_name": os.environ.get("BH_DEVICE_NAME") or "browser-harness",
+    }
+    try:
+        data = _post_json(f"{auth_base()}/cloud/cli-auth/browser", req)
+    except BaseException:
+        server.server_close()
+        raise
+    auth_url = data.get("authorization_uri") or data.get("auth_url")
+    if not auth_url:
+        server.server_close()
+        raise AuthError("auth start response did not include authorization_uri")
+    expires_in = _int_or_none(data.get("expires_in"))
+    opened = False
+    if open_url:
+        try:
+            opened = bool(webbrowser.open(auth_url))
+        except Exception:
+            opened = False
+    return BrowserAuthStart(
+        server=server,
+        callback=callback,
+        redirect_uri=redirect_uri,
+        verifier=verifier,
+        auth_url=auth_url,
+        expires_in=expires_in,
+        opened=opened,
+    )
+
+
+def complete_browser_auth(start: BrowserAuthStart, *, timeout=AUTH_TIMEOUT_SECONDS) -> AuthRecord:
+    deadline = time.time() + timeout
+    start.server.timeout = 0.5
+    try:
+        while not start.callback.complete and time.time() < deadline:
+            start.server.handle_request()
+    finally:
+        start.server.server_close()
+    if not start.callback.complete:
+        raise AuthError("timed out waiting for browser auth callback")
+    if start.callback.error:
+        detail = f": {start.callback.error_description}" if start.callback.error_description else ""
+        raise AuthError(f"auth failed: {start.callback.error}{detail}")
+    if not start.callback.code:
+        raise AuthError("auth callback did not include a code")
+    token = _exchange_authorization_code(start.callback.code, start.redirect_uri, start.verifier)
+    record = AuthRecord.from_token_response(token)
+    save_auth_record(record)
+    return record
+
+
+def browser_login(*, open_url=True, json_output=False, timeout=AUTH_TIMEOUT_SECONDS) -> AuthRecord:
+    start = start_browser_auth(open_url=open_url, timeout=timeout)
+    if json_output:
+        print(json.dumps({
+            "status": "needs_user_auth",
+            "auth_url": start.auth_url,
+            "callback": start.redirect_uri,
+            "expires_in": start.expires_in,
+            "opened": start.opened,
+        }), flush=True)
+    else:
+        print("Open this URL to sign in to Browser Use Cloud:")
+        print(start.auth_url, flush=True)
+        if start.opened:
+            print("Waiting for login to complete...", flush=True)
+        else:
+            print("Waiting for login to complete after you open the URL...", flush=True)
+    record = complete_browser_auth(start, timeout=timeout)
+    if json_output:
+        print(json.dumps(_stored_success_output()), flush=True)
+    else:
+        print("Browser Use Cloud auth stored.")
+    return record
+
+
+def start_device_auth(*, open_url=True) -> DeviceAuthStart:
+    data = _post_json(
+        f"{auth_base()}/cloud/cli-auth/device",
+        {"client_id": client_id(), "device_name": os.environ.get("BH_DEVICE_NAME") or "browser-harness"},
+    )
+    device_code = data.get("device_code")
+    user_code = data.get("user_code")
+    verification_uri = data.get("verification_uri") or data.get("verification_url")
+    if not device_code or not user_code or not verification_uri:
+        raise AuthError("device auth response missing device_code, user_code, or verification_uri")
+    opened = False
+    open_uri = data.get("verification_uri_complete") or verification_uri
+    if open_url:
+        try:
+            opened = bool(webbrowser.open(open_uri))
+        except Exception:
+            opened = False
+    return DeviceAuthStart(
+        device_code=device_code,
+        user_code=user_code,
+        verification_uri=verification_uri,
+        verification_uri_complete=data.get("verification_uri_complete"),
+        expires_in=_int_or_none(data.get("expires_in")),
+        interval=max(1, _int_or_none(data.get("interval")) or 5),
+        opened=opened,
+    )
+
+
+def complete_device_auth(start: DeviceAuthStart, *, timeout: int | None = None) -> AuthRecord:
+    deadline = time.time() + (timeout or start.expires_in or AUTH_TIMEOUT_SECONDS)
+    interval = start.interval
+    while time.time() < deadline:
+        try:
+            token = _post_json(f"{auth_base()}/cloud/cli-auth/token", {
+                "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+                "device_code": start.device_code,
+                "client_id": client_id(),
+            })
+            record = AuthRecord.from_token_response(token)
+            save_auth_record(record)
+            return record
+        except AuthError as e:
+            err = _auth_error_code(str(e))
+            if err == "authorization_pending":
+                time.sleep(interval)
+                continue
+            if err == "slow_down":
+                interval += 5
+                time.sleep(interval)
+                continue
+            raise
+    raise AuthError("timed out waiting for device auth")
+
+
+def device_login(*, open_url=True, json_output=False) -> AuthRecord:
+    start = start_device_auth(open_url=open_url)
+    if json_output:
+        print(json.dumps({
+            "status": "needs_user_auth",
+            "verification_uri": start.verification_uri,
+            "verification_uri_complete": start.verification_uri_complete,
+            "user_code": start.user_code,
+            "expires_in": start.expires_in,
+            "opened": start.opened,
+        }), flush=True)
+    else:
+        print("Open this URL to sign in to Browser Use Cloud:")
+        print(start.open_uri, flush=True)
+        print(f"Code: {start.user_code}", flush=True)
+        print("Waiting for login to complete...", flush=True)
+    record = complete_device_auth(start)
+    if json_output:
+        print(json.dumps(_stored_success_output()), flush=True)
+    else:
+        print("Browser Use Cloud auth stored.")
+    return record
+
+
+def api_key_stdin_login(*, json_output=False, input_stream=None) -> AuthRecord:
+    key = _read_manual_api_key(input_stream)
+    record = AuthRecord(api_key=key, source="manual")
+    save_auth_record(record)
+    if json_output:
+        print(json.dumps(_stored_success_output()), flush=True)
+    else:
+        print("Browser Use Cloud API key stored.")
+    return record
+
+
+def _exchange_authorization_code(code: str, redirect_uri: str, verifier: str) -> dict:
+    return _post_json(f"{auth_base()}/cloud/cli-auth/token", {
+        "grant_type": "authorization_code",
+        "code": code,
+        "redirect_uri": redirect_uri,
+        "code_verifier": verifier,
+        "client_id": client_id(),
+    })
+
+
+def _callback_server(callback: PendingCallback) -> HTTPServer:
+    class Handler(BaseHTTPRequestHandler):
+        def do_GET(self):  # noqa: N802 - stdlib handler API
+            parsed = urllib.parse.urlparse(self.path)
+            if parsed.path != CALLBACK_PATH:
+                self.send_error(404)
+                return
+            qs = urllib.parse.parse_qs(parsed.query)
+            state = _one(qs, "state")
+            if state != callback.state:
+                callback.error = "invalid_state"
+                callback.error_description = "OAuth callback state did not match"
+            else:
+                callback.code = _one(qs, "code")
+                callback.error = _one(qs, "error")
+                callback.error_description = _one(qs, "error_description")
+            callback.complete = True
+            body = b"<html><body><h1>Browser Use Cloud login complete</h1><p>You can close this tab.</p></body></html>"
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html; charset=utf-8")
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+
+        def log_message(self, fmt, *args):
+            return
+
+    return HTTPServer(("127.0.0.1", 0), Handler)
+
+
+def _post_json(url: str, payload: dict) -> dict:
+    req = urllib.request.Request(
+        url,
+        method="POST",
+        data=json.dumps(payload).encode(),
+        headers={"Content-Type": "application/json"},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=60) as resp:
+            return json.loads(resp.read() or b"{}")
+    except urllib.error.HTTPError as e:
+        body = e.read() or b""
+        try:
+            data = json.loads(body or b"{}")
+        except json.JSONDecodeError:
+            data = {}
+        err = data.get("error") or data.get("state") or f"http_{e.code}"
+        desc = data.get("error_description") or data.get("reason") or data.get("message")
+        detail = f": {desc}" if desc else ""
+        raise AuthError(f"{err}{detail}") from e
+    except urllib.error.URLError as e:
+        raise AuthError(f"network error: {e.reason}") from e
+
+
+def _read_manual_api_key(input_stream=None) -> str:
+    stream = input_stream or sys.stdin
+    if hasattr(stream, "isatty") and stream.isatty():
+        try:
+            key = getpass.getpass("Browser Use API key: ")
+        except EOFError as e:
+            raise AuthError("no API key provided") from e
+    else:
+        key = stream.read()
+    key = (key or "").strip()
+    if not key:
+        raise AuthError("no API key provided")
+    if len(key) < 20:
+        raise AuthError("API key looks too short")
+    return key
+
+
+def _write_private_json(path: Path, data: dict) -> None:
+    raw = (json.dumps(data, indent=2) + "\n").encode()
+    flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC
+    fd = os.open(path, flags, stat.S_IRUSR | stat.S_IWUSR)
+    try:
+        with os.fdopen(fd, "wb") as f:
+            f.write(raw)
+    except BaseException:
+        try:
+            os.close(fd)
+        except OSError:
+            pass
+        raise
+
+
+def _chmod_private(path: Path, *, directory=False) -> None:
+    mode = stat.S_IRWXU if directory else stat.S_IRUSR | stat.S_IWUSR
+    try:
+        os.chmod(path, mode)
+    except OSError:
+        pass
+
+
+def _one(qs: dict[str, list[str]], key: str) -> str | None:
+    values = qs.get(key)
+    return values[0] if values else None
+
+
+def _int_or_none(value) -> int | None:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _auth_error_code(message: str) -> str:
+    return message.split(":", 1)[0]
+
+
+def _stored_success_output() -> dict:
+    return {"status": "stored", "path": str(auth_path())}
+
+
+def run_auth_cli(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(prog="browser-harness auth")
+    sub = parser.add_subparsers(dest="command", required=True)
+    login = sub.add_parser("login")
+    login_mode = login.add_mutually_exclusive_group()
+    login_mode.add_argument("--device-code", action="store_true")
+    login_mode.add_argument("--api-key-stdin", action="store_true")
+    login.add_argument("--json", action="store_true")
+    login.add_argument("--no-open", action="store_true")
+    sub.add_parser("status")
+    sub.add_parser("logout")
+    args = parser.parse_args(argv)
+
+    try:
+        if args.command == "login":
+            if args.api_key_stdin:
+                api_key_stdin_login(json_output=args.json)
+            elif args.device_code:
+                device_login(open_url=not args.no_open, json_output=args.json)
+            else:
+                browser_login(open_url=not args.no_open, json_output=args.json)
+            return 0
+        if args.command == "status":
+            print(json.dumps(auth_status(), indent=2))
+            return 0
+        if args.command == "logout":
+            removed = clear_auth()
+            print(json.dumps({"status": "logged-out" if removed else "missing", "path": str(auth_path())}, indent=2))
+            return 0
+    except (AuthError, CloudAuthRequired) as e:
+        if getattr(args, "json", False):
+            print(json.dumps({"status": "error", "reason": str(e)}), file=sys.stderr)
+        else:
+            print(str(e), file=sys.stderr)
+        return 1
+    return 2

browser-harness/src/browser_harness/daemon.py

@@ -0,0 +1,643 @@
+"""CDP WS holder + IPC relay (Unix socket on POSIX, TCP loopback on Windows). One daemon per BU_NAME."""
+import asyncio, json, os, platform, socket, sys, time, urllib.error, urllib.request
+from urllib.parse import urlparse
+from collections import deque
+from pathlib import Path
+
+from . import _ipc as ipc
+from . import auth
+from . import paths
+from cdp_use.client import CDPClient
+
+
+def _load_env():
+    repo_root = Path(__file__).resolve().parents[2]
+    workspace = paths.workspace_dir()
+    for p in (repo_root / ".env", workspace / ".env"):
+        if not p.exists():
+            continue
+        _load_env_file(p)
+
+
+def _load_env_file(p):
+    for line in p.read_text(encoding="utf-8-sig", errors="replace").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        k, v = line.split("=", 1)
+        os.environ.setdefault(k.strip(), v.strip().strip('"').strip("'"))
+
+
+_load_env()
+
+NAME = os.environ.get("BU_NAME", "default")
+SOCK = ipc.sock_addr(NAME)
+LOG = str(ipc.log_path(NAME))
+PID = str(ipc.pid_path(NAME))
+BUF = 500
+_MAC_PROFILES = (
+    "Library/Application Support/Google/Chrome",
+    "Library/Application Support/Google/Chrome Canary",
+    "Library/Application Support/Comet",
+    "Library/Application Support/Arc/User Data",
+    "Library/Application Support/Dia/User Data",
+    "Library/Application Support/Microsoft Edge",
+    "Library/Application Support/Microsoft Edge Beta",
+    "Library/Application Support/Microsoft Edge Dev",
+    "Library/Application Support/Microsoft Edge Canary",
+    "Library/Application Support/BraveSoftware/Brave-Browser",
+)
+_LINUX_PROFILES = (
+    ".config/google-chrome",
+    ".config/chromium",
+    ".config/chromium-browser",
+    ".config/microsoft-edge",
+    ".config/microsoft-edge-beta",
+    ".config/microsoft-edge-dev",
+    ".var/app/org.chromium.Chromium/config/chromium",
+    ".var/app/com.google.Chrome/config/google-chrome",
+    ".var/app/com.brave.Browser/config/BraveSoftware/Brave-Browser",
+    ".var/app/com.microsoft.Edge/config/microsoft-edge",
+)
+_WINDOWS_PROFILES = (  # relative to %LOCALAPPDATA%; SxS = Canary channel
+    "Google/Chrome/User Data",
+    "Google/Chrome SxS/User Data",
+    "Google/Chrome Beta/User Data",
+    "Google/Chrome Dev/User Data",
+    "Chromium/User Data",
+    "Microsoft/Edge/User Data",
+    "Microsoft/Edge Beta/User Data",
+    "Microsoft/Edge Dev/User Data",
+    "Microsoft/Edge SxS/User Data",
+    "BraveSoftware/Brave-Browser/User Data",
+)
+
+
+def profile_dirs(system=None):
+    system = system or platform.system()
+    if system == "Windows":
+        local = Path(os.environ.get("LOCALAPPDATA") or Path.home() / "AppData/Local")
+        return [local / p for p in _WINDOWS_PROFILES]
+    if system == "Darwin":
+        return [Path.home() / p for p in _MAC_PROFILES]
+    return [Path.home() / p for p in _LINUX_PROFILES]
+
+
+PROFILES = profile_dirs()
+INTERNAL = ("chrome://", "chrome-untrusted://", "devtools://", "chrome-extension://", "about:")
+BU_API = "https://api.browser-use.com/api/v3"
+REMOTE_ID = os.environ.get("BU_BROWSER_ID")
+BROWSER_KIND = "cloud" if REMOTE_ID else ("cdp" if (os.environ.get("BU_CDP_WS") or os.environ.get("BU_CDP_URL")) else "local")
+# Chrome 144+ shows a per-connection popup. Keep popup open enough to click.
+LOCAL_HANDSHAKE_TIMEOUT = 45
+# How long get_ws_url() keeps waiting for DevToolsActivePort before giving up
+NO_TOGGLE_GRACE = 3
+TOGGLE_BOOT_GRACE = 12
+
+
+def _devtools_port_live(base):
+    """True when something is listening on the profile's DevToolsActivePort port.
+
+    A stale file left behind by a closed browser must not count as a running
+    instance — it would route recovery to "click Allow" on a popup that can't
+    exist."""
+    try:
+        port = int((base / "DevToolsActivePort").read_text(encoding="utf-8", errors="replace").splitlines()[0].strip())
+    except (OSError, ValueError, IndexError):
+        return False
+    try:
+        socket.create_connection(("127.0.0.1", port), timeout=0.5).close()
+        return True
+    except OSError:
+        return False
+
+
+def remote_debugging_user_enabled():
+    """chrome://inspect's "Allow remote debugging" toggle
+
+    True only when a toggle-on profile also has a live DevTools port.
+    False if a profile records it off, None when no profile records it."""
+    seen = None
+    for base in PROFILES:
+        try:
+            state = json.loads((base / "Local State").read_text(encoding="utf-8", errors="replace"))
+            enabled = ((state.get("devtools") or {}).get("remote_debugging") or {}).get("user-enabled")
+        except (OSError, ValueError, AttributeError):
+            continue
+        if enabled is True and _devtools_port_live(base):
+            return True
+        if enabled is False:
+            seen = False
+    return seen
+
+
+def remote_debugging_toggle_profiles():
+    """Profile dirs whose chrome://inspect toggle is recorded on in Local State"""
+    out = []
+    for base in PROFILES:
+        try:
+            state = json.loads((base / "Local State").read_text(encoding="utf-8", errors="replace"))
+            if ((state.get("devtools") or {}).get("remote_debugging") or {}).get("user-enabled") is True:
+                out.append(base)
+        except (OSError, ValueError, AttributeError):
+            continue
+    return out
+
+
+def browser_running_for_profile(base):
+    """True when a running browser instance holds this user-data-dir (POSIX)"""
+    try:
+        target = os.readlink(str(base / "SingletonLock"))
+    except OSError:
+        return False
+    try:
+        pid = int(target.rsplit("-", 1)[-1])
+    except ValueError:
+        return False
+    try:
+        os.kill(pid, 0)
+        return True
+    except ProcessLookupError:
+        return False
+    except OSError:
+        return True  # pid exists but belongs to another user
+
+
+def supported_browser_running():
+    """Is any browser whose profile we scan actually running?"""
+    if platform.system() == "Windows":
+        # Chromium on Windows uses a named mutex instead of SingletonLock —
+        import subprocess
+        try:
+            out = subprocess.check_output(["tasklist"], text=True, errors="replace", timeout=5).lower()
+        except Exception:
+            return True  # can't tell — assume running so recovery stays on the popup/toggle path
+        return any(n in out for n in ("chrome.exe", "msedge.exe", "chromium.exe", "brave.exe", "helium.exe"))
+    return any(browser_running_for_profile(base) for base in PROFILES)
+
+
+def log(msg):
+    open(LOG, "a", encoding="utf-8", errors="replace").write(f"{msg}\n")
+
+
+async def _silent(coro):
+    try:
+        await coro
+    except Exception:
+        pass
+
+
+def _ws_from_devtools_active_port(http_url: str) -> str | None:
+    """When /json/version returns 404 (Chrome 147+ default profile), match DevToolsActivePort by port."""
+    p = urlparse(http_url)
+    want_port = str(p.port) if p.port else ""
+    if not want_port:
+        return None
+    host = p.hostname or "127.0.0.1"
+    if ":" in host:  # urlparse strips IPv6 brackets; restore them for the ws:// URL
+        host = f"[{host}]"
+    for base in PROFILES:
+        try:
+            active = (base / "DevToolsActivePort").read_text(encoding="utf-8", errors="replace").splitlines()
+        except (FileNotFoundError, NotADirectoryError):
+            continue
+        port = active[0].strip() if active else ""
+        ws_path = active[1].strip() if len(active) > 1 else ""
+        if port == want_port and ws_path:
+            return f"ws://{host}:{port}{ws_path}"
+    return None
+
+
+def get_ws_url():
+    if url := os.environ.get("BU_CDP_WS"):
+        return url
+    if url := os.environ.get("BU_CDP_URL"):
+        # HTTP DevTools endpoint (e.g. http://127.0.0.1:9333) — resolve to ws via /json/version.
+        # Use this for a dedicated automation Chrome on a non-default profile, which avoids the
+        # M144 "Allow remote debugging" dialog and the M136 default-profile lockdown.
+        deadline = time.time() + 30
+        last_err = None
+        base_url = url.rstrip("/")
+        while time.time() < deadline:
+            try:
+                return json.loads(urllib.request.urlopen(f"{base_url}/json/version", timeout=5).read())["webSocketDebuggerUrl"]
+            except urllib.error.HTTPError as e:
+                last_err = e
+                if e.code == 403:
+                    raise RuntimeError("permission-blocked: Chrome is reachable, but the per-session Allow remote debugging popup has not been accepted")
+                if e.code == 404 and (ws := _ws_from_devtools_active_port(url)):
+                    return ws
+                time.sleep(1)
+            except Exception as e:
+                last_err = e
+                time.sleep(1)
+        hint = "is the dedicated automation Chrome running? Launch it with --remote-debugging-port=<port> --user-data-dir=<dedicated dir>"
+        if platform.system() == "Windows":
+            hint += "; on Windows also check that a firewall/antivirus isn't blocking localhost connections"
+        raise RuntimeError(f"BU_CDP_URL={url} unreachable after 30s: {last_err} -- {hint}")
+    deadline = time.time() + 30
+    next_liveness_check = 0.0
+    while time.time() < deadline:
+        for base in PROFILES:
+            try:
+                active = (base / "DevToolsActivePort").read_text(encoding="utf-8", errors="replace").splitlines()
+            except (FileNotFoundError, NotADirectoryError):
+                continue
+            port = active[0].strip() if active else ""
+            ws_path = active[1].strip() if len(active) > 1 else ""
+            if not port:
+                continue
+            # Resolve the live WS URL via /json/version instead of trusting the path stored
+            # alongside the port in DevToolsActivePort: if Chrome was previously launched
+            # with a different --user-data-dir on the same port, that file is left behind
+            # with a stale browser UUID and the WS upgrade returns 404.
+            try:
+                return json.loads(urllib.request.urlopen(f"http://127.0.0.1:{port}/json/version", timeout=1).read())["webSocketDebuggerUrl"]
+            except urllib.error.HTTPError as e:
+                if e.code == 403:
+                    raise RuntimeError("permission-blocked: Chrome is reachable, but the per-session Allow remote debugging popup has not been accepted")
+                # Chrome 147+ disables /json/* HTTP discovery on the default user-data-dir;
+                # the ws path Chrome wrote to DevToolsActivePort still works.
+                if e.code == 404 and ws_path:
+                    return f"ws://127.0.0.1:{port}{ws_path}"
+            except (OSError, KeyError, ValueError):
+                pass
+        # Closed browser leaves stale DevToolsActivePort files
+        now = time.time()
+        if now >= next_liveness_check:
+            if not supported_browser_running():
+                raise RuntimeError(
+                    "chrome-not-running: no supported Chromium-family browser is running -- start Chrome, then retry"
+                )
+            next_liveness_check = now + 2
+        # The browser is running but the port isn't up; waiting 30s
+        grace = TOGGLE_BOOT_GRACE if remote_debugging_toggle_profiles() else NO_TOGGLE_GRACE
+        if now > deadline - 30 + grace:
+            break
+        time.sleep(0.2)
+    for probe_port in (9222, 9223):
+        try:
+            with urllib.request.urlopen(f"http://127.0.0.1:{probe_port}/json/version", timeout=1) as r:
+                return json.loads(r.read())["webSocketDebuggerUrl"]
+        except urllib.error.HTTPError as e:
+            if e.code == 403:
+                raise RuntimeError("permission-blocked: Chrome is reachable, but the per-session Allow remote debugging popup has not been accepted")
+        except (OSError, KeyError, ValueError):
+            continue
+    if remote_debugging_user_enabled() is False:
+        raise RuntimeError('remote debugging is turned off for this browser instance — enable chrome://inspect/#remote-debugging (tick "Allow remote debugging for this browser instance")')
+    raise RuntimeError(f"DevToolsActivePort not found in {[str(p) for p in PROFILES]} — enable chrome://inspect/#remote-debugging, or set BU_CDP_WS for a remote browser")
+
+
+def stop_remote():
+    if not REMOTE_ID:
+        return
+    try:
+        key = auth.get_browser_use_api_key()
+        req = urllib.request.Request(
+            f"{BU_API}/browsers/{REMOTE_ID}",
+            data=json.dumps({"action": "stop"}).encode(),
+            method="PATCH",
+            headers={"X-Browser-Use-API-Key": key, "Content-Type": "application/json"},
+        )
+        urllib.request.urlopen(req, timeout=15).read()
+        log(f"stopped remote browser {REMOTE_ID}")
+    except Exception as e:
+        log(f"stop_remote failed ({REMOTE_ID}): {e}")
+
+
+def is_real_page(t):
+    return t["type"] == "page" and not t.get("url", "").startswith(INTERNAL)
+
+
+def is_reusable_blank_page(t):
+    """A plain about:blank tab that is safe to attach to and navigate"""
+    url = t.get("url", "")
+    return (
+        t["type"] == "page"
+        and (url == "about:blank" or url.startswith("about:blank#"))
+        and not t.get("title", "").startswith("Starting agent ")
+    )
+
+
+def is_inspect_tab(t):
+    """A chrome://inspect tab — normally the one the permission flow opened"""
+    return t["type"] == "page" and t.get("url", "").startswith("chrome://inspect")
+
+
+def harness_opened_inspect():
+    """True when admin's recovery flow opened a chrome://inspect tab that is
+    still awaiting cleanup (the marker survives until the next connect)."""
+    try:
+        return paths.inspect_marker().exists()
+    except OSError:
+        return False
+
+
+def is_reusable_new_tab_page(t):
+    """The browser's own New Tab Page, ex: from a fresh launch"""
+    return t["type"] == "page" and t.get("url", "").startswith(
+        ("chrome://newtab", "chrome://new-tab-page", "edge://newtab", "about:newtab")
+    )
+
+
+class _PatientCDPClient(CDPClient):
+    """CDPClient with the WS opening handshake stretched to LOCAL_HANDSHAKE_TIMEOUT."""
+
+    async def start(self):
+        import websockets
+        if self.ws is not None:
+            raise RuntimeError("Client is already started")
+        connect_kwargs = {"max_size": self.max_ws_frame_size, "open_timeout": LOCAL_HANDSHAKE_TIMEOUT}
+        if self.additional_headers:
+            connect_kwargs["additional_headers"] = self.additional_headers
+        self.ws = await websockets.connect(self.url, **connect_kwargs)
+        self._message_handler_task = asyncio.create_task(self._handle_messages())
+
+
+class Daemon:
+    def __init__(self):
+        self.cdp = None
+        self.session = None
+        self.target_id = None
+        self.events = deque(maxlen=BUF)
+        self.dialog = None
+        self.stop = None  # asyncio.Event, set inside start()
+
+    async def attach_first_page(self):
+        """Attach to a real page (or any page). Sets self.session. Returns attached target or None."""
+        targets = (await self.cdp.send_raw("Target.getTargets"))["targetInfos"]
+        pages = [t for t in targets if is_real_page(t)]
+        if not pages:
+            # Fresh browser (ex: BU cloud) starts w about:blank; reuse it
+            pages = [t for t in targets if is_reusable_blank_page(t)]
+        if not pages:
+            # Freshly launched browser (ex: harness relaunching closed Chrome)
+            # starts with just the New Tab Page. Reuse it — creating about:blank
+            pages = [t for t in targets if is_reusable_new_tab_page(t)]
+        take_over = None
+        if not pages and harness_opened_inspect():
+            # After perms granted, only tab is often chrome://inspect
+            # Attach to it instead of creating a new about:blank
+            inspect_tabs = [t for t in targets if is_inspect_tab(t)]
+            if inspect_tabs:
+                pages = [inspect_tabs[0]]
+                take_over = inspect_tabs[0]["targetId"]
+        if not pages:
+            # No usable pages - create one instead of attaching to omnibox popup.
+            tid = (await self.cdp.send_raw("Target.createTarget", {"url": "about:blank"}))["targetId"]
+            log(f"no real pages found, created about:blank ({tid})")
+            pages = [{"targetId": tid, "url": "about:blank", "type": "page"}]
+        self.session = (await self.cdp.send_raw(
+            "Target.attachToTarget", {"targetId": pages[0]["targetId"], "flatten": True}
+        ))["sessionId"]
+        self.target_id = pages[0]["targetId"]
+        log(f"attached {pages[0]['targetId']} ({pages[0].get('url','')[:80]}) session={self.session}")
+        if take_over:
+            try:
+                await self.cdp.send_raw("Page.navigate", {"url": "about:blank"}, session_id=self.session)
+                log(f"took over inspect tab {take_over} -> about:blank")
+            except Exception as e:
+                log(f"take over inspect tab {take_over}: {e}")
+        if BROWSER_KIND == "local":
+            await self._close_inspect_tabs(targets)
+        await self._enable_default_domains(self.session)
+        return pages[0]
+
+    async def _close_inspect_tabs(self, targets):
+        """Close chrome://inspect tabs left open by the permission recovery flow"""
+        if not harness_opened_inspect():
+            return
+        for t in targets:
+            if t["targetId"] != self.target_id and is_inspect_tab(t):
+                try:
+                    await self.cdp.send_raw("Target.closeTarget", {"targetId": t["targetId"]})
+                    log(f"closed leftover chrome://inspect tab {t['targetId']}")
+                except Exception as e:
+                    log(f"close inspect tab {t['targetId']}: {e}")
+        try:
+            paths.inspect_marker().unlink()
+        except OSError:
+            pass
+
+    async def _enable_default_domains(self, session_id):
+        """Enable Page/DOM/Runtime/Network on a CDP session.
+
+        Used by both initial attach and set_session (called after switch_tab/
+        new_tab). Without this, helpers that depend on Network.* events —
+        notably wait_for_network_idle() — silently stop receiving events
+        after a tab switch, because each fresh CDP session starts with all
+        domains disabled.
+
+        Runs the four enables in parallel via gather so the worst-case time is
+        bounded by a single CDP round trip rather than four sequential ones —
+        important on the set_session path, where the helper's IPC socket has
+        a 5s read timeout.
+        """
+        async def enable_one(d):
+            try:
+                await asyncio.wait_for(
+                    self.cdp.send_raw(f"{d}.enable", session_id=session_id),
+                    timeout=4,
+                )
+            except Exception as e:
+                log(f"enable {d} on {session_id}: {e}")
+        await asyncio.gather(*(enable_one(d) for d in ("Page", "DOM", "Runtime", "Network")))
+
+    async def start(self):
+        self.stop = asyncio.Event()
+        url = get_ws_url()
+        log(f"connecting to {url}")
+        self.cdp = _PatientCDPClient(url) if BROWSER_KIND == "local" else CDPClient(url)
+        if BROWSER_KIND == "local":
+            # Allow while this handshake is still parked on the popup
+            log("handshake-wait: if Chrome shows an 'Allow remote debugging?' popup, click Allow")
+        try:
+            await self.cdp.start()
+        except Exception as e:
+            if os.environ.get("BU_CDP_WS"):
+                raise RuntimeError(
+                    f"CDP WS handshake failed: {e} -- remote browser WebSocket connection failed. "
+                    "This can happen when network policy blocks the connection, the WS URL is wrong or expired, or the remote endpoint is down. "
+                    "If you use Browser Use cloud, verify auth and get a fresh URL via start_remote_daemon()."
+                )
+            if BROWSER_KIND == "local" and ("timed out" in str(e).lower() or "403" in str(e)) and remote_debugging_user_enabled():
+                raise RuntimeError(
+                    f"permission-blocked: Chrome's 'Allow remote debugging?' popup was not accepted within {LOCAL_HANDSHAKE_TIMEOUT}s"
+                    " -- wait for the user to click Allow, then retry"
+                )
+            raise RuntimeError(f"CDP WS handshake failed: {e} -- click Allow in Chrome if prompted, then retry")
+        await self.attach_first_page()
+        orig = self.cdp._event_registry.handle_event
+        mark_js = "if(!document.title.startsWith('\U0001F434'))document.title='\U0001F434 '+document.title"
+        async def tap(method, params, session_id=None):
+            self.events.append({"method": method, "params": params, "session_id": session_id})
+            if method == "Page.javascriptDialogOpening":
+                self.dialog = params
+            elif method == "Page.javascriptDialogClosed":
+                self.dialog = None
+            elif method in ("Page.loadEventFired", "Page.domContentEventFired"):
+                asyncio.create_task(_silent(asyncio.wait_for(self.cdp.send_raw("Runtime.evaluate", {"expression": mark_js}, session_id=self.session), timeout=2)))
+            return await orig(method, params, session_id)
+        self.cdp._event_registry.handle_event = tap
+
+    async def handle(self, req):
+        # Token guard for Windows TCP loopback: any local process can otherwise
+        # connect and issue CDP commands. expected_token() is None on POSIX so
+        # this check is a no-op there (AF_UNIX + chmod 600 is the boundary).
+        expected = ipc.expected_token()
+        if expected is not None and req.get("token") != expected:
+            return {"error": "unauthorized"}
+        meta = req.get("meta")
+        # Liveness probe — lets clients confirm the listener is actually this
+        # daemon and not an unrelated process that reused our port post-crash.
+        # `pid` lets restart_daemon() verify the live daemon's identity before
+        # signaling — protects against SIGTERM-by-stale-pid-file after PID reuse.
+        if meta == "ping":        return {"pong": True, "pid": os.getpid(), "browser_kind": BROWSER_KIND}
+        if meta == "drain_events":
+            out = list(self.events); self.events.clear()
+            return {"events": out}
+        if meta == "session":     return {"session_id": self.session}
+        if meta == "current_tab":
+            # Resolve the attached page's target info server-side. Helpers can't
+            # send Target.getTargetInfo themselves: daemon strips session_id for
+            # any Target.* method (browser-level call), and without a targetId
+            # Chrome silently returns the *browser* target.
+            if not self.target_id:
+                return {"error": "not_attached"}
+            try:
+                info = (await self.cdp.send_raw("Target.getTargetInfo", {"targetId": self.target_id}))["targetInfo"]
+            except Exception:
+                return {"error": "cdp_disconnected"}
+            return {"targetId": info.get("targetId"), "url": info.get("url", ""), "title": info.get("title", "")}
+        if meta == "connection_status":
+            if not self.target_id:
+                return {"error": "not_attached"}
+            try:
+                info = (await self.cdp.send_raw("Target.getTargetInfo", {"targetId": self.target_id}))["targetInfo"]
+            except Exception:
+                return {"error": "cdp_disconnected"}
+            page = None
+            if is_real_page(info):
+                page = {
+                    "targetId": info.get("targetId"),
+                    "title": info.get("title") or "(untitled)",
+                    "url": info.get("url") or "",
+                }
+            return {"target_id": self.target_id, "session_id": self.session, "page": page}
+        if meta == "set_session":
+            old_session = self.session
+            self.session = req.get("session_id")
+            self.target_id = req.get("target_id") or self.target_id
+            # Run the old-session Network.disable (defense in depth — keeps
+            # background-tab traffic out of the global event buffer; the
+            # consumer-side filter in wait_for_network_idle is the actual
+            # correctness gate) in parallel with the four enables on the new
+            # session. Different sessions, independent CDP requests. Keeps
+            # the synchronous reply under the helper's 5s IPC read timeout
+            # even on a remote daemon — sequentially these would have stacked
+            # to ~22s worst case.
+            tasks = []
+            if old_session and old_session != self.session:
+                async def disable_old():
+                    try:
+                        await asyncio.wait_for(
+                            self.cdp.send_raw("Network.disable", session_id=old_session),
+                            timeout=2,
+                        )
+                    except Exception: pass
+                tasks.append(disable_old())
+            tasks.append(self._enable_default_domains(self.session))
+            await asyncio.gather(*tasks)
+            # 🐴 tab-marker title prefix is purely cosmetic — fire-and-forget so
+            # it doesn't add to the synchronous IPC budget.
+            asyncio.create_task(_silent(asyncio.wait_for(
+                self.cdp.send_raw(
+                    "Runtime.evaluate",
+                    {"expression": "if(!document.title.startsWith('\U0001F434'))document.title='\U0001F434 '+document.title"},
+                    session_id=self.session,
+                ),
+                timeout=2,
+            )))
+            return {"session_id": self.session}
+        if meta == "pending_dialog": return {"dialog": self.dialog}
+        if meta == "shutdown":    self.stop.set(); return {"ok": True}
+
+        method = req["method"]
+        params = req.get("params") or {}
+        # Browser-level Target.* calls must not use a session (stale or otherwise).
+        # For everything else, explicit session in req wins; else default.
+        sid = None if method.startswith("Target.") else (req.get("session_id") or self.session)
+        try:
+            return {"result": await self.cdp.send_raw(method, params, session_id=sid)}
+        except Exception as e:
+            msg = str(e)
+            if "Session with given id not found" in msg and sid == self.session and sid:
+                log(f"stale session {sid}, re-attaching")
+                if await self.attach_first_page():
+                    return {"result": await self.cdp.send_raw(method, params, session_id=self.session)}
+            return {"error": msg}
+
+
+async def serve(d):
+    async def handler(reader, writer):
+        try:
+            line = await reader.readline()
+            if not line: return
+            resp = await d.handle(json.loads(line))
+            writer.write((json.dumps(resp, default=str) + "\n").encode())
+            await writer.drain()
+        except Exception as e:
+            log(f"conn: {e}")
+            try:
+                writer.write((json.dumps({"error": str(e)}) + "\n").encode())
+                await writer.drain()
+            except Exception:
+                pass
+        finally:
+            writer.close()
+
+    serve_task = asyncio.create_task(ipc.serve(NAME, handler))
+    stop_task = asyncio.create_task(d.stop.wait())
+    await asyncio.sleep(0.05)  # let serve() bind so sock_addr() resolves to the live endpoint
+    log(f"listening on {ipc.sock_addr(NAME)} (name={NAME}, remote={REMOTE_ID or 'local'})")
+    try:
+        await asyncio.wait({serve_task, stop_task}, return_when=asyncio.FIRST_COMPLETED)
+        if serve_task.done(): await serve_task  # surfaces a serve crash
+    finally:
+        for t in (serve_task, stop_task):
+            t.cancel()
+            try: await t
+            except (asyncio.CancelledError, Exception): pass
+        ipc.cleanup_endpoint(NAME)
+
+
+async def main():
+    d = Daemon()
+    await d.start()
+    await serve(d)
+
+
+def already_running():
+    # Ping handshake (not a bare connect) so a stale .port file + port reuse
+    # after a daemon crash doesn't make us mistake an unrelated listener for ours.
+    return ipc.ping(NAME, timeout=1.0)
+
+
+if __name__ == "__main__":
+    if already_running():
+        print(f"daemon already running on {SOCK}", file=sys.stderr)
+        sys.exit(0)
+    open(LOG, "w").close()
+    open(PID, "w").write(str(os.getpid()))
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        pass
+    except Exception as e:
+        log(f"fatal: {e}")
+        sys.exit(1)
+    finally:
+        stop_remote()
+        try: os.unlink(PID)
+        except FileNotFoundError: pass

browser-harness/src/browser_harness/helpers.py

@@ -0,0 +1,518 @@
+"""Browser control via CDP.
+
+Core helpers live here. Agent-editable helpers live in
+BH_AGENT_WORKSPACE/agent_helpers.py.
+"""
+import base64, importlib.util, json, math, os, sys, time, urllib.request
+from pathlib import Path
+from urllib.parse import urlparse
+
+from . import _ipc as ipc
+from . import paths
+
+
+CORE_DIR = Path(__file__).resolve().parent
+REPO_ROOT = CORE_DIR.parent.parent
+AGENT_WORKSPACE = paths.workspace_dir()
+
+
+def _load_env():
+    paths = [REPO_ROOT / ".env", AGENT_WORKSPACE / ".env"]
+    for p in paths:
+        if not p.exists():
+            continue
+        _load_env_file(p)
+
+
+def _load_env_file(p):
+    for line in p.read_text(encoding="utf-8-sig", errors="replace").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        k, v = line.split("=", 1)
+        os.environ.setdefault(k.strip(), v.strip().strip('"').strip("'"))
+
+
+_load_env()
+
+NAME = os.environ.get("BU_NAME", "default")
+SOCK = ipc.sock_addr(NAME)
+INTERNAL = ("chrome://", "chrome-untrusted://", "devtools://", "chrome-extension://", "about:")
+
+
+def _send(req):
+    c, token = ipc.connect(NAME, timeout=5.0)
+    try:
+        r = ipc.request(c, token, req)
+    finally:
+        c.close()
+    if "error" in r: raise RuntimeError(r["error"])
+    return r
+
+
+def cdp(method, session_id=None, **params):
+    """Raw CDP. cdp('Page.navigate', url='...'), cdp('DOM.getDocument', depth=-1)."""
+    return _send({"method": method, "params": params, "session_id": session_id}).get("result", {})
+
+
+def drain_events():  return _send({"meta": "drain_events"})["events"]
+
+
+def _js_snippet(expression, limit=160):
+    snippet = expression.strip().replace("\n", "\\n")
+    return snippet[:limit - 3] + "..." if len(snippet) > limit else snippet
+
+
+def _js_exception_description(result, details):
+    desc = result.get("description")
+    exc = details.get("exception") if details else None
+    if not desc and isinstance(exc, dict):
+        desc = exc.get("description")
+        if desc is None and "value" in exc:
+            desc = str(exc["value"])
+        if desc is None:
+            desc = exc.get("className")
+    if not desc and details:
+        desc = details.get("text")
+    return desc or "JavaScript evaluation failed"
+
+
+def _decode_unserializable_js_value(value):
+    if value == "NaN":
+        return math.nan
+    if value == "Infinity":
+        return math.inf
+    if value == "-Infinity":
+        return -math.inf
+    if value == "-0":
+        return -0.0
+    if value.endswith("n"):
+        return int(value[:-1])
+    return value
+
+
+def _runtime_value(response, expression):
+    result = response.get("result", {})
+    details = response.get("exceptionDetails")
+    if details or result.get("subtype") == "error":
+        desc = _js_exception_description(result, details)
+        if details:
+            line = details.get("lineNumber")
+            col = details.get("columnNumber")
+            loc = f" at line {line}, column {col}" if line is not None and col is not None else ""
+        else:
+            loc = ""
+        raise RuntimeError(f"JavaScript evaluation failed{loc}: {desc}; expression: {_js_snippet(expression)}")
+    if "value" in result:
+        return result["value"]
+    if "unserializableValue" in result:
+        return _decode_unserializable_js_value(result["unserializableValue"])
+    return None
+
+
+def _runtime_evaluate(expression, session_id=None, await_promise=False):
+    try:
+        r = cdp("Runtime.evaluate", session_id=session_id, expression=expression, returnByValue=True, awaitPromise=await_promise)
+    except TimeoutError as e:
+        raise RuntimeError(f"Runtime.evaluate timed out; expression: {_js_snippet(expression)}") from e
+    return _runtime_value(r, expression)
+
+
+def _wrap_js_function(expression):
+    return f"(function(){{{expression}}})()"
+
+
+def _is_illegal_return_error(exc):
+    return "Illegal return statement" in str(exc)
+
+
+# --- navigation / page ---
+def goto_url(url):
+    r = cdp("Page.navigate", url=url)
+    if os.environ.get("BH_DOMAIN_SKILLS") != "1":
+        return r
+    d = (AGENT_WORKSPACE / "domain-skills" / (urlparse(url).hostname or "").removeprefix("www.").split(".")[0])
+    return {**r, "domain_skills": sorted(p.name for p in d.rglob("*.md"))[:10]} if d.is_dir() else r
+
+def page_info():
+    """{url, title, w, h, sx, sy, pw, ph} — viewport + scroll + page size.
+
+    If a native dialog (alert/confirm/prompt/beforeunload) is open, returns
+    {dialog: {type, message, ...}} instead — the page's JS thread is frozen
+    until the dialog is handled (see interaction-skills/dialogs.md)."""
+    dialog = _send({"meta": "pending_dialog"}).get("dialog")
+    if dialog:
+        return {"dialog": dialog}
+    expression = "JSON.stringify({url:location.href,title:document.title,w:innerWidth,h:innerHeight,sx:scrollX,sy:scrollY,pw:document.documentElement.scrollWidth,ph:document.documentElement.scrollHeight})"
+    return json.loads(_runtime_evaluate(expression))
+
+# --- input ---
+_debug_click_counter = 0
+
+def click_at_xy(x, y, button="left", clicks=1):
+    if os.environ.get("BH_DEBUG_CLICKS"):
+        global _debug_click_counter
+        try:
+            from PIL import Image, ImageDraw
+            dpr = js("window.devicePixelRatio") or 1
+            path = capture_screenshot(str(ipc._TMP / f"debug_click_{_debug_click_counter}.png"))
+            img = Image.open(path)
+            draw = ImageDraw.Draw(img)
+            px, py = int(x * dpr), int(y * dpr)
+            r = int(15 * dpr)
+            draw.ellipse([px - r, py - r, px + r, py + r], outline="red", width=int(3 * dpr))
+            draw.line([px - r - int(5 * dpr), py, px + r + int(5 * dpr), py], fill="red", width=int(2 * dpr))
+            draw.line([px, py - r - int(5 * dpr), px, py + r + int(5 * dpr)], fill="red", width=int(2 * dpr))
+            img.save(path)
+            print(f"[debug_click] saved {path} (x={x}, y={y}, dpr={dpr})")
+        except Exception as e:
+            print(f"[debug_click] overlay failed: {e}")
+        _debug_click_counter += 1
+    cdp("Input.dispatchMouseEvent", type="mousePressed", x=x, y=y, button=button, clickCount=clicks)
+    cdp("Input.dispatchMouseEvent", type="mouseReleased", x=x, y=y, button=button, clickCount=clicks)
+
+def type_text(text):
+    cdp("Input.insertText", text=text)
+
+def fill_input(selector, text, clear_first=True, timeout=0.0):
+    """Fill a framework-managed input (React controlled, Vue v-model, Ember tracked).
+
+    type_text() uses Input.insertText which bypasses framework event listeners and leaves
+    submit buttons disabled. This helper focuses the element, clears it, types via real
+    key events, then fires synthetic input+change events so the framework sees the update.
+
+    Raises RuntimeError if the element is not found. Pass timeout>0 to wait for
+    late-rendered elements (e.g. after a route change) before typing.
+    """
+    if timeout > 0:
+        if not wait_for_element(selector, timeout=timeout):
+            raise RuntimeError(f"fill_input: element not found: {selector!r}")
+    focused = js(
+        f"(()=>{{const e=document.querySelector({json.dumps(selector)});"
+        f"if(!e)return false;e.focus();return true;}})()"
+    )
+    if not focused:
+        raise RuntimeError(f"fill_input: element not found: {selector!r}")
+    if clear_first:
+        # Dispatch select-all directly — NOT via press_key, which always emits a
+        # `char` event for single-char keys. With Ctrl/Cmd held, that `char`
+        # makes Chrome treat the input as a printable "a" instead of firing the
+        # select-all shortcut, leaving the field uncleared.
+        mods = 4 if sys.platform == "darwin" else 2  # Cmd on macOS, Ctrl elsewhere
+        select_all = {"key": "a", "code": "KeyA", "modifiers": mods,
+                      "windowsVirtualKeyCode": 65, "nativeVirtualKeyCode": 65}
+        cdp("Input.dispatchKeyEvent", type="rawKeyDown", **select_all)
+        cdp("Input.dispatchKeyEvent", type="keyUp", **select_all)
+        press_key("Backspace")
+    for ch in text:
+        press_key(ch)
+    js(
+        f"(()=>{{const e=document.querySelector({json.dumps(selector)});"
+        f"if(!e)return;"
+        f"e.dispatchEvent(new Event('input',{{bubbles:true}}));"
+        f"e.dispatchEvent(new Event('change',{{bubbles:true}}));}})();"
+    )
+
+_KEYS = {  # key → (windowsVirtualKeyCode, code, text)
+    "Enter": (13, "Enter", "\r"), "Tab": (9, "Tab", "\t"), "Backspace": (8, "Backspace", ""),
+    "Escape": (27, "Escape", ""), "Delete": (46, "Delete", ""), " ": (32, "Space", " "),
+    "ArrowLeft": (37, "ArrowLeft", ""), "ArrowUp": (38, "ArrowUp", ""),
+    "ArrowRight": (39, "ArrowRight", ""), "ArrowDown": (40, "ArrowDown", ""),
+    "Home": (36, "Home", ""), "End": (35, "End", ""),
+    "PageUp": (33, "PageUp", ""), "PageDown": (34, "PageDown", ""),
+}
+def press_key(key, modifiers=0):
+    """Modifiers bitfield: 1=Alt, 2=Ctrl, 4=Meta(Cmd), 8=Shift.
+    Special keys (Enter, Tab, Arrow*, Backspace, etc.) carry their virtual key codes
+    so listeners checking e.keyCode / e.key all fire."""
+    vk, code, text = _KEYS.get(key, (ord(key[0]) if len(key) == 1 else 0, key, key if len(key) == 1 else ""))
+    base = {"key": key, "code": code, "modifiers": modifiers, "windowsVirtualKeyCode": vk, "nativeVirtualKeyCode": vk}
+    shortcut_modifiers = modifiers & (1 | 2 | 4)  # Alt/Ctrl/Meta turn single keys into shortcuts.
+    printable_char = len(key) == 1 and bool(text) and not shortcut_modifiers
+    cdp("Input.dispatchKeyEvent", type="keyDown", **base, **({} if printable_char or not text else {"text": text}))
+    if printable_char:
+        cdp("Input.dispatchKeyEvent", type="char", text=text, **{k: v for k, v in base.items() if k != "text"})
+    cdp("Input.dispatchKeyEvent", type="keyUp", **base)
+
+def scroll(x, y, dy=-300, dx=0):
+    cdp("Input.dispatchMouseEvent", type="mouseWheel", x=x, y=y, deltaX=dx, deltaY=dy)
+
+
+# --- visual ---
+def capture_screenshot(path=None, full=False, max_dim=None):
+    """Save a PNG of the current viewport. Set max_dim=1800 on a 2× display to
+    keep the file under the 2000px-per-side limit some image-aware LLMs enforce."""
+    path = path or str(ipc._TMP / "shot.png")
+    r = cdp("Page.captureScreenshot", format="png", captureBeyondViewport=full)
+    open(path, "wb").write(base64.b64decode(r["data"]))
+    if max_dim:
+        from PIL import Image
+        img = Image.open(path)
+        if max(img.size) > max_dim:
+            img.thumbnail((max_dim, max_dim))
+            img.save(path)
+    return path
+
+
+# --- tabs ---
+def _is_agent_startup_placeholder(title, url):
+    url = str(url or "")
+    return str(title or "").startswith("Starting agent ") and (
+        url in ("", "about:blank") or url.startswith("about:blank#")
+    )
+
+
+def list_tabs(include_chrome=True):
+    out = []
+    for t in cdp("Target.getTargets")["targetInfos"]:
+        if t["type"] != "page": continue
+        url = t.get("url", "")
+        if _is_agent_startup_placeholder(t.get("title", ""), url): continue
+        if not include_chrome and url.startswith(INTERNAL): continue
+        out.append({
+            "targetId": t["targetId"],
+            "target_id": t["targetId"],
+            "title": t.get("title", ""),
+            "url": url,
+        })
+    return out
+
+def current_tab():
+    r = _send({"meta": "current_tab"})
+    return {
+        "targetId": r["targetId"],
+        "target_id": r["targetId"],
+        "url": r["url"],
+        "title": r["title"],
+    }
+
+def _mark_tab():
+    """Prepend horse emoji to tab title so the user can see which tab the agent controls."""
+    try: cdp("Runtime.evaluate", expression="if(!document.title.startsWith('\U0001F434'))document.title='\U0001F434 '+document.title")
+    except Exception: pass
+
+def switch_tab(target):
+    # Accept either a raw targetId string or the dict returned by current_tab() / list_tabs(),
+    # so `switch_tab(current_tab())` works without a manual ["targetId"] dance.
+    target_id = (target.get("targetId") or target.get("target_id")) if isinstance(target, dict) else target
+    # Unmark old tab. Horse emoji is a surrogate pair in JS UTF-16 strings (2 code units),
+    # plus the trailing space = 3 code units, so slice(3) cleanly removes the prefix.
+    try: cdp("Runtime.evaluate", expression="if(document.title.startsWith('\U0001F434 '))document.title=document.title.slice(3)")
+    except Exception: pass
+    cdp("Target.activateTarget", targetId=target_id)
+    sid = cdp("Target.attachToTarget", targetId=target_id, flatten=True)["sessionId"]
+    _send({"meta": "set_session", "session_id": sid, "target_id": target_id})
+    _mark_tab()
+    return sid
+
+def new_tab(url="about:blank"):
+    # Always create blank, then goto: passing url to createTarget races with
+    # attach, so the brief about:blank is "complete" by the time the caller
+    # polls and wait_for_load() returns before navigation actually starts.
+    if url != "about:blank":
+        try:
+            cur = current_tab()
+            cur_url = cur.get("url") or ""
+            # Reuse attached tab when it's blank
+            if (
+                cur_url in ("", "about:blank")
+                or cur_url.startswith("about:blank#")
+                or cur_url.startswith(("chrome://newtab", "chrome://new-tab-page", "edge://newtab", "about:newtab"))
+            ):
+                goto_url(url)
+                return cur.get("targetId") or cur.get("target_id")
+        except Exception:
+            pass
+    tid = cdp("Target.createTarget", url="about:blank")["targetId"]
+    switch_tab(tid)
+    if url != "about:blank":
+        goto_url(url)
+    return tid
+
+def close_tab(target=None):
+    """Close a tab. If `target` is omitted, closes the currently attached tab.
+    Accepts a raw targetId string or a dict from list_tabs()/current_tab()."""
+    target_id = (target.get("targetId") or target.get("target_id")) if isinstance(target, dict) else target
+    if target_id is None:
+        target_id = current_tab()["targetId"]
+    cdp("Target.closeTarget", targetId=target_id)
+
+
+def ensure_real_tab():
+    """Switch to a real user tab if current is chrome:// / internal / stale."""
+    tabs = list_tabs(include_chrome=False)
+    if not tabs:
+        return None
+    try:
+        cur = current_tab()
+        if cur["url"] and not cur["url"].startswith(INTERNAL):
+            return cur
+    except Exception:
+        pass
+    switch_tab(tabs[0]["targetId"])
+    return tabs[0]
+
+def iframe_target(url_substr):
+    """First iframe target whose URL contains `url_substr`. Use with js(..., target_id=...)."""
+    for t in cdp("Target.getTargets")["targetInfos"]:
+        if t["type"] == "iframe" and url_substr in t.get("url", ""):
+            return t["targetId"]
+    return None
+
+
+# --- utility ---
+def wait(seconds=1.0):
+    time.sleep(seconds)
+
+def wait_for_load(timeout=15.0):
+    """Poll document.readyState == 'complete' or timeout."""
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        if js("document.readyState") == "complete": return True
+        time.sleep(0.3)
+    return False
+
+def wait_for_element(selector, timeout=10.0, visible=False):
+    """Poll until querySelector(selector) exists in the DOM, or timeout.
+
+    wait_for_load() misses SPAs — the document is 'complete' before the framework renders.
+    Use this after actions that trigger async rendering (route changes, data fetches).
+    Set visible=True to also require the element to be non-hidden and in-layout.
+    Returns True if found, False on timeout.
+    """
+    if visible:
+        # checkVisibility walks the ancestor chain and respects display:none /
+        # visibility:hidden / opacity:0 on parents, which a getComputedStyle
+        # check on the element alone misses (it returns the descendant's own
+        # style, not the inherited "is this rendered" state). Falls back to
+        # the per-element CSS check on older Chrome that lacks checkVisibility.
+        check = (
+            f"(()=>{{const e=document.querySelector({json.dumps(selector)});"
+            f"if(!e)return false;"
+            f"if(typeof e.checkVisibility==='function')"
+            f"return e.checkVisibility({{checkOpacity:true,checkVisibilityCSS:true}});"
+            f"const s=getComputedStyle(e);"
+            f"return s.display!=='none'&&s.visibility!=='hidden'&&s.opacity!=='0'}})()"
+        )
+    else:
+        check = f"!!document.querySelector({json.dumps(selector)})"
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        if js(check): return True
+        time.sleep(0.3)
+    return False
+
+def wait_for_network_idle(timeout=10.0, idle_ms=500):
+    """Wait until all in-flight requests finish and no Network.* events arrive for idle_ms ms.
+
+    Useful after form submits, SPA route transitions, and any action that triggers
+    XHR/fetch without a visible DOM change. Builds on drain_events() — no daemon changes.
+    Returns True if idle window reached, False on timeout.
+
+    Events are filtered to the active session — a previously-attached background
+    tab (e.g. a polling/SSE page the agent switched away from) keeps emitting
+    Network events into the daemon's global event buffer; without this filter
+    they would poison the idle check on the current tab.
+    """
+    deadline = time.time() + timeout
+    last_activity = time.time()
+    inflight = set()
+    active_session = _send({"meta": "session"}).get("session_id")
+    while time.time() < deadline:
+        for e in drain_events():
+            if e.get("session_id") != active_session:
+                continue
+            method = e.get("method", "")
+            params = e.get("params", {})
+            if method == "Network.requestWillBeSent":
+                inflight.add(params.get("requestId"))
+                last_activity = time.time()
+            elif method in ("Network.loadingFinished", "Network.loadingFailed"):
+                inflight.discard(params.get("requestId"))
+                last_activity = time.time()
+            elif method.startswith("Network."):
+                last_activity = time.time()
+        if not inflight and (time.time() - last_activity) * 1000 >= idle_ms:
+            return True
+        time.sleep(0.1)
+    return False
+
+def js(expression, target_id=None):
+    """Run JS in the attached tab (default) or inside an iframe target (via iframe_target()).
+
+    Expressions are evaluated as-is first. If Chrome reports an illegal top-level
+    `return`, the snippet is retried inside a function wrapper, so both
+    `document.title` and `const x = 1; return x` work without mis-wrapping nested
+    functions that contain their own returns.
+    """
+    sid = cdp("Target.attachToTarget", targetId=target_id, flatten=True)["sessionId"] if target_id else None
+    try:
+        return _runtime_evaluate(expression, session_id=sid, await_promise=True)
+    except RuntimeError as e:
+        if _is_illegal_return_error(e):
+            return _runtime_evaluate(_wrap_js_function(expression), session_id=sid, await_promise=True)
+        raise
+
+
+_KC = {"Enter": 13, "Tab": 9, "Escape": 27, "Backspace": 8, " ": 32, "ArrowLeft": 37, "ArrowUp": 38, "ArrowRight": 39, "ArrowDown": 40}
+
+
+def dispatch_key(selector, key="Enter", event="keypress"):
+    """Dispatch a DOM KeyboardEvent on the matched element.
+
+    Use this when a site reacts to synthetic DOM key events on an element more reliably
+    than to raw CDP input events.
+    """
+    kc = _KC.get(key, ord(key) if len(key) == 1 else 0)
+    js(
+        f"(()=>{{const e=document.querySelector({json.dumps(selector)});if(e){{e.focus();e.dispatchEvent(new KeyboardEvent({json.dumps(event)},{{key:{json.dumps(key)},code:{json.dumps(key)},keyCode:{kc},which:{kc},bubbles:true}}));}}}})()"
+    )
+
+def upload_file(selector, path):
+    """Set files on a file input via CDP DOM.setFileInputFiles. `path` is an absolute filepath (use tempfile.mkstemp if needed)."""
+    doc = cdp("DOM.getDocument", depth=-1)
+    nid = cdp("DOM.querySelector", nodeId=doc["root"]["nodeId"], selector=selector)["nodeId"]
+    if not nid: raise RuntimeError(f"no element for {selector}")
+    cdp("DOM.setFileInputFiles", files=[path] if isinstance(path, str) else list(path), nodeId=nid)
+
+def http_get(url, headers=None, timeout=20.0):
+    """Pure HTTP — no browser. Use for static pages / APIs. Wrap in ThreadPoolExecutor for bulk.
+
+    When BROWSER_USE_API_KEY is set, routes through the fetch-use proxy (handles bot
+    detection, residential proxies, retries). Falls back to local urllib otherwise."""
+    if os.environ.get("BROWSER_USE_API_KEY"):
+        try:
+            from fetch_use import fetch_sync
+            return fetch_sync(url, headers=headers, timeout_ms=int(timeout * 1000)).text
+        except ImportError:
+            pass
+    import gzip
+    h = {"User-Agent": "Mozilla/5.0", "Accept-Encoding": "gzip"}
+    if headers: h.update(headers)
+    with urllib.request.urlopen(urllib.request.Request(url, headers=h), timeout=timeout) as r:
+        data = r.read()
+        if r.headers.get("Content-Encoding") == "gzip": data = gzip.decompress(data)
+        return data.decode()
+
+
+# Imported at the bottom so recorder's own `from . import helpers` sees a
+# fully-defined module. Exposes the recording helpers via `from .helpers import *`.
+from .recorder import start_recording, stop_recording, recording_dir
+
+
+def _load_agent_helpers():
+    p = AGENT_WORKSPACE / "agent_helpers.py"
+    if not p.exists():
+        return
+    spec = importlib.util.spec_from_file_location("browser_harness_agent_helpers", p)
+    if not spec or not spec.loader:
+        return
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    for name, value in vars(module).items():
+        if name.startswith("_"):
+            continue
+        globals()[name] = value
+
+
+_load_agent_helpers()

browser-harness/src/browser_harness/paths.py

@@ -0,0 +1,49 @@
+"""browser-harness filesystem layout."""
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+
+def home_dir() -> Path:
+    raw = os.environ.get("BH_HOME") or os.environ.get("BROWSER_HARNESS_HOME")
+    if raw:
+        return Path(raw).expanduser().resolve()
+    base = os.environ.get("XDG_CONFIG_HOME")
+    if base:
+        return (Path(base).expanduser() / "browser-harness").resolve()
+    return (Path.home() / ".config" / "browser-harness").resolve()
+
+
+def ensure_private_dir(path: Path) -> Path:
+    existed = path.exists()
+    path.mkdir(parents=True, exist_ok=True)
+    if not existed and sys.platform != "win32":
+        os.chmod(path, 0o700)
+    return path
+
+
+def config_dir() -> Path:
+    raw = os.environ.get("BH_CONFIG_DIR")
+    return ensure_private_dir(Path(raw).expanduser().resolve() if raw else home_dir())
+
+
+def inspect_marker() -> Path:
+    """Marker recording that the harness opened a chrome://inspect tab"""
+    return config_dir() / "inspect-opened"
+
+
+def runtime_dir() -> Path:
+    raw = os.environ.get("BH_RUNTIME_DIR")
+    return ensure_private_dir(Path(raw).expanduser().resolve() if raw else home_dir() / "runtime")
+
+
+def tmp_dir() -> Path:
+    raw = os.environ.get("BH_TMP_DIR")
+    return ensure_private_dir(Path(raw).expanduser().resolve() if raw else home_dir() / "tmp")
+
+
+def workspace_dir() -> Path:
+    raw = os.environ.get("BH_AGENT_WORKSPACE")
+    return ensure_private_dir(Path(raw).expanduser().resolve() if raw else home_dir() / "agent-workspace")

browser-harness/src/browser_harness/recorder.py

@@ -0,0 +1,324 @@
+"""Session recording: one screenshot + one trace line per action.
+
+A recording is just a folder:
+
+    <BH_AGENT_WORKSPACE>/recordings/<name>/
+      meta.json      # {name, title, started}
+      events.jsonl   # one JSON object per action: helper, coords/text,
+                     # url, viewport, focused-element box, frame filename
+      0001.jpg ...   # viewport screenshot after each action
+
+start_recording()/stop_recording() toggle it. A marker file carries the
+active state across CLI invocations (the daemon is untouched). run.py calls
+observe() after every traced helper; only helpers in ACTIONS produce a
+frame. Recording failures are swallowed — they must never break the run.
+
+Automatic recording is an opt-in preference stored under the browser-harness
+config directory. BH_RECORD=1/0 overrides it for one process. Explicit
+start_recording() always works unless BH_RECORD=0 is set.
+
+Turning a recording into a video is the make-video skill's job:
+interaction-skills/make-video.md.
+"""
+import base64, json, os, re, time
+from pathlib import Path
+
+from . import paths
+
+# Helpers that change what's on screen. Read-only helpers (js, page_info,
+# capture_screenshot, ...) don't get frames — they'd bloat recordings of
+# inspection-heavy sessions without adding visual beats.
+ACTIONS = {
+    "goto_url", "click_at_xy", "type_text", "fill_input", "press_key",
+    "scroll", "dispatch_key", "upload_file", "new_tab", "switch_tab",
+    "close_tab", "ensure_real_tab",
+    "wait", "wait_for_load", "wait_for_element", "wait_for_network_idle",
+}
+
+_TEXT_LIMIT = 500
+_SETTLE_SECONDS = 0.15  # let the page paint before the post-action frame
+
+# Credential-bearing query/fragment params (OAuth codes, tokens, session
+# state) are scrubbed from every URL written to events.jsonl — auth redirects
+# otherwise land real secrets in a folder people share.
+_URL_SECRETS = re.compile(
+    r"([?&#](?:code|access_token|id_token|refresh_token|token|assertion"
+    r"|client_secret|client_info|session_state|api_?key|sig|signature"
+    r"|auth|authorization|password|secret)=)[^&#]+",
+    re.IGNORECASE,
+)
+
+
+def _scrub_url(url):
+    return _URL_SECRETS.sub(r"\1REDACTED", str(url))
+
+# Page context per event. The focused-element box is what lets a video zoom
+# in on the input the agent is typing into; `input` flags password fields
+# so their text can be masked in the trace.
+_CTX_JS = (
+    "(()=>{const o={url:location.href,title:document.title,"
+    "w:innerWidth,h:innerHeight,sx:scrollX,sy:scrollY,dpr:devicePixelRatio};"
+    "const e=document.activeElement;"
+    "if(e&&e!==document.body&&e!==document.documentElement){"
+    "const r=e.getBoundingClientRect();"
+    "if(r.width||r.height)o.box={x:r.x,y:r.y,w:r.width,h:r.height};"
+    "o.input=String(e.type||e.tagName||'').toLowerCase();}"
+    "return o})()"
+)
+
+
+def _recordings_root():
+    return paths.workspace_dir() / "recordings"
+
+
+def _config_path():
+    return paths.config_dir() / "recording.json"
+
+
+def _load_config():
+    try:
+        data = json.loads(_config_path().read_text(encoding="utf-8"))
+        return data if isinstance(data, dict) else {}
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return {}
+
+
+def _env_override():
+    raw = os.environ.get("BH_RECORD")
+    if raw is None:
+        return None
+    return raw.strip().lower() not in ("0", "false", "no", "off")
+
+
+def _marker():
+    return _recordings_root() / f".active-{os.environ.get('BU_NAME', 'default')}"
+
+
+def start_recording(name=None, title=None):
+    """Record the session: one screenshot + trace line per action, until
+    stop_recording(). Survives across CLI invocations. Returns the recording
+    directory. `title` is used later as the video title.
+    See interaction-skills/make-video.md to turn the recording into a video."""
+    if _env_override() is False:
+        raise RuntimeError("recording disabled by BH_RECORD=0")
+    name = name or time.strftime("rec-%Y%m%d-%H%M%S")
+    d = _recordings_root() / name
+    d.mkdir(parents=True, exist_ok=True)
+    meta = {"name": name, "title": title, "started": round(time.time(), 3)}
+    (d / "meta.json").write_text(json.dumps(meta), encoding="utf-8")
+    _marker().write_text(str(d), encoding="utf-8")
+    _capture(d, "start_recording")
+    print(f"recording to {d}")
+    return str(d)
+
+
+def stop_recording():
+    """Stop the active recording. Returns its directory, or None if idle."""
+    d = recording_dir()
+    if d is None:
+        print("no active recording")
+        return None
+    _capture(Path(d), "stop_recording")
+    _marker().unlink(missing_ok=True)
+    frames = sum(1 for _ in Path(d).glob("*.jpg"))
+    print(f"recording saved: {d} ({frames} frames)")
+    return d
+
+
+def recording_dir():
+    """Directory of the active recording, or None."""
+    m = _marker()
+    if not m.exists():
+        return None
+    d = m.read_text(encoding="utf-8").strip()
+    return d if Path(d).is_dir() else None
+
+
+def recordings():
+    """Recording directories, newest first."""
+    root = _recordings_root()
+    if not root.exists():
+        return []
+
+    def modified(path):
+        evidence = path / "events.jsonl"
+        return evidence.stat().st_mtime if evidence.exists() else path.stat().st_mtime
+
+    found = [p for p in root.iterdir()
+             if p.is_dir() and ((p / "meta.json").exists() or (p / "events.jsonl").exists())]
+    return [str(p) for p in sorted(found, key=modified, reverse=True)]
+
+
+def latest_recording():
+    """Newest recording directory, or None."""
+    found = recordings()
+    return found[0] if found else None
+
+
+def auto_recording_setting():
+    """Return (enabled, source) for the automatic recording preference."""
+    override = _env_override()
+    if override is not None:
+        return override, "BH_RECORD"
+    config = _load_config()
+    if isinstance(config.get("enabled"), bool):
+        return config["enabled"], "config"
+    return False, "default"
+
+
+def _auto_enabled():
+    return auto_recording_setting()[0]
+
+
+def auto_recording_enabled():
+    """Whether automatic recording is enabled for this process."""
+    return _auto_enabled()
+
+
+def set_auto_recording(enabled):
+    """Persist the automatic recording preference. BH_RECORD still overrides it."""
+    path = _config_path()
+    tmp = path.with_name(path.name + ".tmp")
+    tmp.write_text(json.dumps({"enabled": bool(enabled)}) + "\n", encoding="utf-8")
+    if os.name != "nt":
+        os.chmod(tmp, 0o600)
+    os.replace(tmp, path)
+    if not enabled:
+        d = recording_dir()
+        if d is not None and _is_auto_recording(d):
+            _marker().unlink(missing_ok=True)
+
+
+def _is_auto_recording(d):
+    try:
+        return json.loads((Path(d) / "meta.json").read_text(encoding="utf-8")).get("auto") is True
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return False
+
+
+# Auto-recordings roll over after this idle gap — a pause since the last action
+# marks the end of one task and the start of the next, so a naive always-on
+# recording doesn't merge unrelated sessions or grow forever.
+def _auto_idle_gap():
+    try:
+        return float(os.environ.get("BH_RECORD_IDLE", "180"))
+    except ValueError:
+        return 180.0
+
+
+def _auto_start():
+    """Begin an auto-recording silently — no stdout (agents parse it)."""
+    stamp = time.strftime("session-%Y%m%d-%H%M%S")
+    name, n = stamp, 2
+    while (_recordings_root() / name).exists():  # avoid same-second collisions
+        name = f"{stamp}-{n}"; n += 1
+    d = _recordings_root() / name
+    d.mkdir(parents=True, exist_ok=True)
+    meta = {"name": name, "title": None, "started": round(time.time(), 3), "auto": True}
+    (d / "meta.json").write_text(json.dumps(meta), encoding="utf-8")
+    _marker().write_text(str(d), encoding="utf-8")
+    return d
+
+
+def _auto_is_stale(d):
+    """True if the active auto-recording has gone idle past the rollover gap."""
+    try:
+        if not _is_auto_recording(d):
+            return False  # explicit start_recording() never auto-rolls
+        frames = list(Path(d).glob("*.jpg"))
+        if not frames:
+            return False
+        newest = max(f.stat().st_mtime for f in frames)
+        return (time.time() - newest) > _auto_idle_gap()
+    except Exception:
+        return False
+
+
+def observe(name, args, kwargs, duration=None):
+    """Called by run.py after each traced helper succeeds. Never raises."""
+    if name not in ACTIONS:
+        return
+    try:
+        if _env_override() is False:
+            return
+        d = recording_dir()
+        if d is not None and _is_auto_recording(d) and not _auto_enabled():
+            _marker().unlink(missing_ok=True)
+            d = None
+        if d is not None and _auto_is_stale(d):
+            _marker().unlink(missing_ok=True)
+            d = None
+        if d is None:
+            if not _auto_enabled():
+                return
+            d = str(_auto_start())
+        time.sleep(_SETTLE_SECONDS)
+        _capture(Path(d), name, args, kwargs, duration)
+    except Exception:
+        pass
+
+
+def _capture(d, helper, args=(), kwargs=None, duration=None):
+    from . import helpers  # late: helpers imports recorder at its bottom
+
+    event = {"ts": round(time.time(), 3), "helper": helper}
+    if duration is not None:
+        event["duration"] = duration
+    try:
+        event.update(helpers.js(_CTX_JS) or {})
+    except Exception:
+        pass
+    event.update(_details(helper, args, kwargs or {}, event))
+    for k in ("url", "to"):
+        if k in event:
+            event[k] = _scrub_url(event[k])
+    try:
+        shot = helpers.cdp("Page.captureScreenshot", format="jpeg", quality=80)
+        number = sum(1 for _ in d.glob("*.jpg")) + 1
+        data = base64.b64decode(shot["data"])
+        while True:
+            frame = f"{number:04d}.jpg"
+            try:
+                with (d / frame).open("xb") as output:
+                    output.write(data)
+                break
+            except FileExistsError:
+                number += 1
+        event["frame"] = frame
+    except Exception:
+        pass
+    with (d / "events.jsonl").open("a", encoding="utf-8") as f:
+        f.write(json.dumps(event, ensure_ascii=False) + "\n")
+
+
+def _details(helper, args, kwargs, ctx):
+    def arg(i, name, default=None):
+        return args[i] if len(args) > i else kwargs.get(name, default)
+
+    d = {}
+    if helper == "click_at_xy":
+        d["x"], d["y"] = arg(0, "x"), arg(1, "y")
+    elif helper == "scroll":
+        d["x"], d["y"] = arg(0, "x"), arg(1, "y")
+        d["dy"], d["dx"] = arg(2, "dy", -300), arg(3, "dx", 0)
+    elif helper in ("goto_url", "new_tab"):
+        d["to"] = arg(0, "url")
+    elif helper == "type_text":
+        d["text"] = _mask(arg(0, "text", ""), ctx)
+    elif helper == "fill_input":
+        d["selector"] = arg(0, "selector")
+        d["text"] = _mask(arg(1, "text", ""), ctx)
+    elif helper == "press_key":
+        d["key"] = arg(0, "key")
+    elif helper == "dispatch_key":
+        d["selector"], d["key"] = arg(0, "selector"), arg(1, "key", "Enter")
+    elif helper == "wait_for_element":
+        d["selector"] = arg(0, "selector")
+    return {k: v for k, v in d.items() if v is not None}
+
+
+def _mask(text, ctx):
+    text = str(text)
+    if ctx.get("input") == "password":
+        return "•" * len(text)
+    return text[:_TEXT_LIMIT]

browser-harness/src/browser_harness/run.py

@@ -0,0 +1,391 @@
+import os, sys, time, urllib.request
+from io import StringIO
+
+# Windows default stdout/stderr encoding is cp1252
+# which can't encode the 🐴 marker helpers prepend to tab titles (or anything
+# else outside the locale charset). Force UTF-8 so `print(page_info())` and
+# tracebacks carrying page titles don't UnicodeEncodeError on Windows. #124(4).
+for _stream in (sys.stdout, sys.stderr):
+    if hasattr(_stream, "reconfigure"):
+        try: _stream.reconfigure(encoding="utf-8", errors="replace")
+        except Exception: pass
+
+from .admin import (
+    _version,
+    NAME,
+    daemon_alive,
+    daemon_browser_kind,
+    ensure_daemon,
+    list_cloud_profiles,
+    list_local_profiles,
+    print_update_banner,
+    restart_daemon,
+    run_doctor,
+    run_doctor_fix_snap,
+    run_update,
+    start_remote_daemon,
+    stop_remote_daemon,
+    sync_local_profile,
+)
+from . import auth, recorder, telemetry
+from .helpers import *
+
+HELP = """Browser Harness
+
+Read SKILL.md for the default workflow and examples.
+
+Typical usage:
+  browser-harness <<'PY'
+  ensure_real_tab()
+  print(page_info())
+  PY
+
+Helpers are pre-imported. The daemon auto-starts and connects to the running browser.
+
+Commands:
+  browser-harness --version        print the installed version
+  browser-harness --doctor         diagnose install, daemon, and browser state
+  browser-harness doctor           same as --doctor
+  browser-harness doctor --fix-snap   print how to fix Snap Chromium blocking CDP (Linux)
+  browser-harness auth login          sign in to Browser Use Cloud for cloud browsers
+  browser-harness auth login --device-code   sign in from SSH/headless environments
+  browser-harness auth status         show Browser Use Cloud auth state
+  browser-harness auth logout         remove stored Browser Use Cloud auth
+  browser-harness skill               print the browser-harness skill text
+  browser-harness recordings          show recording status and recent sessions
+  browser-harness recordings --latest   print the newest recording directory
+  browser-harness recordings enable   save browser actions locally by default
+  browser-harness recordings disable  stop saving browser actions by default
+  browser-harness video init <recording>      prepare a recording for editing
+  browser-harness video review <recording>    compile and review the video
+  browser-harness video export <recording> --reviewed   export a verified MP4
+  browser-harness telemetry status    show anonymous telemetry opt-out state
+  browser-harness --update [-y]    pull the latest version (agents: pass -y)
+  browser-harness --reload         stop the daemon so next call picks up code changes
+"""
+
+USAGE = """Usage:
+  browser-harness <<'PY'
+  print(page_info())
+  PY
+"""
+
+
+# Probe /json/version (not a bare TCP connect) so a non-Chrome process bound to
+# 9222/9223 doesn't masquerade as Chrome and skip the cloud bootstrap. Mirrors
+# daemon.py's fallback probe.
+def _local_chrome_listening():
+    for port in (9222, 9223):
+        try:
+            urllib.request.urlopen(f"http://127.0.0.1:{port}/json/version", timeout=0.3).close()
+            return True
+        except OSError: pass
+    return False
+
+
+# BU_CDP_URL / BU_CDP_WS are documented to override local Chrome discovery
+# (install.md:58-59), so they must also block cloud auto-bootstrap. Without this
+# guard, start_remote_daemon() in admin.py overwrites BU_CDP_WS in the daemon
+# env with a cloud WebSocket URL, silently replacing the user's explicit endpoint
+# *and* billing them for a cloud browser they never asked for.
+def _explicit_cdp_configured():
+    return bool(os.environ.get("BU_CDP_URL") or os.environ.get("BU_CDP_WS"))
+
+
+def _cloud_auth_configured():
+    try:
+        auth.get_browser_use_api_key()
+        return True
+    except (auth.CloudAuthRequired, auth.AuthError, OSError):
+        return False
+
+
+def _print_skill():
+    from importlib import resources
+    # SKILL.md is UTF-8 (contains emoji); locale-codec read crashes on gbk Windows
+    print(resources.files("browser_harness").joinpath("SKILL.md").read_text(encoding="utf-8"), end="")
+
+
+def _telemetry_command(args):
+    if not args:
+        return "script"
+    first = args[0]
+    if first in {"-h", "--help"}:
+        return "help"
+    if first == "--version":
+        return "version"
+    if first in {"--doctor", "doctor"}:
+        return "doctor"
+    if first == "--update":
+        return "update"
+    if first == "--reload":
+        return "reload"
+    if first == "--debug-clicks":
+        return "debug-clicks"
+    if first in {"auth", "skill", "recordings", "telemetry", "video"}:
+        return first
+    return "usage"
+
+
+def _exit_code(result) -> int:
+    if result is None:
+        return 0
+    if isinstance(result, int):
+        return result
+    return 1
+
+_MAX_TRACED_STEPS = 500
+_MAX_STEP_ARGS_LENGTH = 300
+_helper_trace = []
+_helper_call_count = 0
+
+
+def _step_args(args, kwargs):
+    parts = [repr(a) for a in args] + [f"{k}={v!r}" for k, v in kwargs.items()]
+    return ", ".join(parts)[:_MAX_STEP_ARGS_LENGTH]
+
+
+def _traced(name, fn):
+    import functools
+
+    @functools.wraps(fn)
+    def wrapper(*args, **kwargs):
+        global _helper_call_count
+        _helper_call_count += 1
+        entry = {"helper": name, "args": _step_args(args, kwargs)}
+        if len(_helper_trace) < _MAX_TRACED_STEPS:
+            _helper_trace.append(entry)
+        step_start = time.monotonic()
+        try:
+            result = fn(*args, **kwargs)
+        except BaseException as exc:
+            entry["duration_seconds"] = round(time.monotonic() - step_start, 3)
+            entry["error"] = str(exc)[:300]
+            raise
+        entry["duration_seconds"] = round(time.monotonic() - step_start, 3)
+        recorder.observe(name, args, kwargs, entry["duration_seconds"])
+        return result
+
+    wrapper.__bh_traced__ = True
+    return wrapper
+
+
+def _install_helper_trace():
+    from . import helpers
+
+    g = globals()
+    for name in dir(helpers):
+        if name.startswith("_"):
+            continue
+        fn = g.get(name)
+        if callable(fn) and not isinstance(fn, type) and not getattr(fn, "__bh_traced__", False):
+            g[name] = _traced(name, fn)
+
+
+_MAX_OUTPUT_LENGTH = 20_000
+
+
+class _StreamTail:
+    """Pass-through stream wrapper that remembers the tail and total length."""
+
+    def __init__(self, wrapped, limit=500):
+        self._wrapped = wrapped
+        self._limit = limit
+        self.tail = ""
+        self.length = 0
+
+    def write(self, text):
+        text = str(text)
+        self.length += len(text)
+        self.tail = (self.tail + text)[-self._limit :]
+        return self._wrapped.write(text)
+
+    def __getattr__(self, name):
+        return getattr(self._wrapped, name)
+
+
+def _read_task(args):
+    if args and args[0] == "--debug-clicks":
+        args = args[1:]
+    if args or sys.stdin.isatty():
+        return None
+    code = sys.stdin.read()
+    sys.stdin = StringIO(code)
+    return code
+
+
+def _traced_steps():
+    return _helper_trace or None
+
+
+def _telemetry_browser(task):
+    """'cloud' | 'cdp' | 'local', self-reported by the daemon the task ran on.
+    None when no browser was involved (non-script commands, daemon never up)."""
+    if not task or not telemetry.is_enabled():
+        return None
+    try:
+        return daemon_browser_kind()
+    except Exception:
+        return None
+
+
+def main():
+    global _helper_call_count
+    args = sys.argv[1:]
+    if args and args[0] == "telemetry":
+        sys.exit(telemetry.run_telemetry_cli(args[1:]))
+    _helper_trace.clear()
+    _helper_call_count = 0
+    start_time = time.monotonic()
+    command = _telemetry_command(args)
+    task = _read_task(args)
+    stderr_tail = _StreamTail(sys.stderr)
+    stdout_tail = _StreamTail(sys.stdout, limit=_MAX_OUTPUT_LENGTH)
+    sys.stderr = stderr_tail
+    sys.stdout = stdout_tail
+    try:
+        _run(args)
+    except SystemExit as exc:
+        code = _exit_code(exc.code)
+        telemetry.capture_cli_event(
+            action="error" if code else "completed",
+            command=command,
+            task=task,
+            browser=_telemetry_browser(task),
+            output=stdout_tail.tail or None,
+            output_length=stdout_tail.length or None,
+            steps=_traced_steps(),
+            step_count=_helper_call_count or None,
+            duration_seconds=time.monotonic() - start_time,
+            exit_code=code,
+            error_message=str(exc.code) if isinstance(exc.code, str) else (stderr_tail.tail.strip() or None) if code else None,
+        )
+        raise
+    except Exception as exc:
+        telemetry.capture_cli_event(
+            action="error",
+            command=command,
+            task=task,
+            browser=_telemetry_browser(task),
+            output=stdout_tail.tail or None,
+            output_length=stdout_tail.length or None,
+            steps=_traced_steps(),
+            step_count=_helper_call_count or None,
+            duration_seconds=time.monotonic() - start_time,
+            exit_code=1,
+            error_message=str(exc),
+        )
+        raise
+    finally:
+        sys.stderr = stderr_tail._wrapped
+        sys.stdout = stdout_tail._wrapped
+    telemetry.capture_cli_event(
+        action="completed",
+        command=command,
+        task=task,
+        browser=_telemetry_browser(task),
+        output=stdout_tail.tail or None,
+        output_length=stdout_tail.length or None,
+        steps=_traced_steps(),
+        step_count=_helper_call_count or None,
+        duration_seconds=time.monotonic() - start_time,
+        exit_code=0,
+    )
+
+
+def _run(args):
+    if args and args[0] in {"-h", "--help"}:
+        print(HELP)
+        return
+    if args and args[0] == "--version":
+        print(_version() or "unknown")
+        return
+    if args and args[0] == "--doctor":
+        sys.exit(run_doctor())
+    if args and args[0] == "doctor":
+        rest = args[1:]
+        if rest == ["--fix-snap"]:
+            sys.exit(run_doctor_fix_snap())
+        if rest:
+            print("usage: browser-harness doctor [--fix-snap]", file=sys.stderr)
+            sys.exit(2)
+        sys.exit(run_doctor())
+    if args and args[0] == "auth":
+        sys.exit(auth.run_auth_cli(args[1:]))
+    if args and args[0] == "skill":
+        if len(args) != 1:
+            print("usage: browser-harness skill", file=sys.stderr)
+            sys.exit(2)
+        _print_skill()
+        return
+    if args and args[0] == "recordings":
+        rest = args[1:]
+        if rest == ["--latest"]:
+            latest = recorder.latest_recording()
+            if latest is None:
+                print("no recordings found", file=sys.stderr)
+                sys.exit(1)
+            print(latest)
+            return
+        if rest in (["enable"], ["disable"]):
+            enabled = rest == ["enable"]
+            recorder.set_auto_recording(enabled)
+            print(f"auto-recording preference {'enabled' if enabled else 'disabled'}")
+            return
+        if rest:
+            print("usage: browser-harness recordings [--latest|enable|disable]", file=sys.stderr)
+            sys.exit(2)
+        enabled, source = recorder.auto_recording_setting()
+        print(f"auto-recording: {'on' if enabled else 'off'} ({source})")
+        active = recorder.recording_dir()
+        print(f"active: {active or 'none'}")
+        recent = recorder.recordings()
+        print(f"latest: {recent[0] if recent else 'none'}")
+        return
+    if args and args[0] == "video":
+        from . import video
+
+        sys.exit(video.run_cli(args[1:]))
+    if args and args[0] == "--update":
+        yes = any(a in {"-y", "--yes"} for a in args[1:])
+        sys.exit(run_update(yes=yes))
+    if args and args[0] == "--reload":
+        restart_daemon()
+        print("daemon stopped — will restart fresh on next call")
+        return
+    if args and args[0] == "--debug-clicks":
+        os.environ["BH_DEBUG_CLICKS"] = "1"
+        args = args[1:]
+    if not args and not sys.stdin.isatty():
+        code = sys.stdin.read()
+        if not code.strip():
+            sys.exit(USAGE)
+    else:
+        sys.exit(USAGE)
+    print_update_banner()
+    # Auto-bootstrap a cloud browser is opt-in via BU_AUTOSPAWN — BROWSER_USE_API_KEY alone
+    # is not enough, since the key is commonly set for unrelated reasons (profile sync,
+    # cloud API calls, parent agents managing their own session). An explicit BU_CDP_URL
+    # or BU_CDP_WS also blocks the spawn so we honour the precedence install.md promises.
+    cloud_admin = code.lstrip().startswith(("start_remote_daemon(", "stop_remote_daemon("))
+    if not cloud_admin:
+        if (
+            not daemon_alive()
+            and not _local_chrome_listening()
+            and not _explicit_cdp_configured()
+            and _cloud_auth_configured()
+            and os.environ.get("BU_AUTOSPAWN")
+        ):
+            start_remote_daemon(NAME)
+        try:
+            ensure_daemon()
+        except RuntimeError as e:
+            # Setup/permission errors are instructions for calling agent
+            print(f"browser-harness: {e}", file=sys.stderr)
+            sys.exit(1)
+    _install_helper_trace()
+    exec(code, globals())
+
+
+if __name__ == "__main__":
+    main()

browser-harness/src/browser_harness/telemetry.py

@@ -0,0 +1,308 @@
+"""Best-effort, opt-out telemetry for browser-harness."""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+import re
+import subprocess
+import sys
+import uuid
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+from urllib.parse import urlparse
+
+from . import paths
+
+POSTHOG_KEY = "phc_rCPCLPtaXB3EuBdiH7JLKtU2Wj5iPnuwdsbw58CnjYXc"
+POSTHOG_HOST = "https://eu.i.posthog.com"
+DISABLE_ENVS = ("BH_TELEMETRY", "BROWSER_HARNESS_TELEMETRY", "ANONYMIZED_TELEMETRY")
+MAX_TASK_LENGTH = 20_000
+FORBIDDEN_KEYS = (
+    "api_key",
+    "content",
+    "cookie",
+    "email",
+    "href",
+    "key",
+    "message",
+    "password",
+    "path",
+    "prompt",
+    "query",
+    "secret",
+    "selector",
+    "text",
+    "title",
+    "token",
+    "url",
+    "uri",
+)
+
+
+def _config_dir() -> Path:
+    return paths.config_dir()
+
+
+def _config_path() -> Path:
+    return _config_dir() / "telemetry.json"
+
+
+def _load_config() -> dict:
+    try:
+        return json.loads(_config_path().read_text(encoding="utf-8"))
+    except (FileNotFoundError, OSError, ValueError):
+        return {}
+
+
+def _save_config(data: dict) -> None:
+    path = _config_path()
+    try:
+        parent_existed = path.parent.exists()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        if not parent_existed and platform.system() != "Windows":
+            os.chmod(path.parent, 0o700)
+        path.write_text(json.dumps(data, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+        if platform.system() != "Windows":
+            os.chmod(path, 0o600)
+    except OSError:
+        pass
+
+
+def _version() -> str:
+    try:
+        return version("browser-harness")
+    except PackageNotFoundError:
+        return ""
+    except Exception:
+        return ""
+
+
+def _env_disabled() -> bool:
+    return any((os.environ.get(name) or "").lower() in {"0", "false", "no", "off"} for name in DISABLE_ENVS)
+
+
+def _valid_install_id(raw) -> bool:
+    return isinstance(raw, str) and re.fullmatch(r"[0-9a-f-]{32,36}", raw) is not None
+
+
+def _install_id(config: dict | None = None, *, create: bool = True) -> str | None:
+    config = config if config is not None else _load_config()
+    raw = config.get("install_id")
+    if _valid_install_id(raw):
+        return raw
+    if not create:
+        return None
+    install_id = str(uuid.uuid4())
+    _save_config({**config, "install_id": install_id})
+    return install_id
+
+
+def is_enabled() -> bool:
+    if _env_disabled():
+        return False
+    return not bool(_load_config().get("disabled"))
+
+
+def status() -> dict:
+    config = _load_config()
+    env_disabled = _env_disabled()
+    enabled = not env_disabled and not bool(config.get("disabled"))
+    return {
+        "enabled": enabled,
+        "disabled_by_env": env_disabled,
+        "disabled_by_config": bool(config.get("disabled")),
+        "install_id": _install_id(config, create=enabled),
+        "config_path": str(_config_path()),
+    }
+
+
+def set_enabled(enabled: bool) -> dict:
+    config = _load_config()
+    config["disabled"] = not enabled
+    _save_config(config)
+    return status()
+
+
+def _safe_properties(properties: dict | None) -> dict:
+    out = {}
+    for key, value in (properties or {}).items():
+        safe_key = re.sub(r"[^A-Za-z0-9_$.-]+", "_", str(key))[:80]
+        lowered = safe_key.lower()
+        if not safe_key or any(word in lowered for word in FORBIDDEN_KEYS):
+            continue
+        if isinstance(value, bool) or value is None:
+            out[safe_key] = value
+        elif isinstance(value, int | float):
+            out[safe_key] = value
+        else:
+            safe_value = str(value)
+            if "://" in safe_value:
+                safe_value = "[redacted]"
+            out[safe_key] = safe_value[:120]
+    return out
+
+
+# Env markers each coding agent injects into subprocesses
+_AGENT_ENV_MARKERS: tuple[tuple[str, str], ...] = (
+    ("AGENT=amp", "amp"),
+    ("CLAUDECODE", "claude-code"),
+    ("CODEX_SANDBOX", "codex"),
+    ("CODEX_THREAD_ID", "codex"),
+    ("GEMINI_CLI", "gemini-cli"),
+    ("COPILOT_CLI", "copilot-cli"),
+    ("COPILOT_AGENT_SESSION_ID", "copilot-cli"),
+    ("OPENCLAW_CLI", "openclaw"),
+    ("HERMES_SESSION_ID", "hermes"),
+    ("CURSOR_AGENT", "cursor"),
+    ("CURSOR_TRACE_ID", "cursor"),
+    ("OPENCODE", "opencode"),
+)
+
+
+def _detect_agent_client() -> str | None:
+    for marker, client in _AGENT_ENV_MARKERS:
+        name, _, required = marker.partition("=")
+        value = os.environ.get(name)
+        if value and (not required or value == required):
+            return client
+    return None
+
+
+_DETACHED_SENDER_SOURCE = """
+import json, sys, urllib.request
+try:
+    job = json.load(sys.stdin)
+    request = urllib.request.Request(
+        job['url'],
+        method='POST',
+        data=json.dumps(job['payload']).encode('utf-8'),
+        headers={'Content-Type': 'application/json', 'User-Agent': 'browser-harness'},
+    )
+    urllib.request.urlopen(request, timeout=job['timeout']).close()
+except Exception:
+    pass
+"""
+
+
+def _send_detached(payload: dict) -> None:
+    """Hand the event to a detached helper process so the CLI never blocks."""
+    host = os.environ.get("BH_POSTHOG_HOST", POSTHOG_HOST).rstrip("/")
+    job = {
+        "url": f"{host}/i/v0/e/",
+        "timeout": float(os.environ.get("BH_TELEMETRY_TIMEOUT", "5")),
+        "payload": payload,
+    }
+    process = subprocess.Popen(
+        [sys.executable, "-c", _DETACHED_SENDER_SOURCE],
+        stdin=subprocess.PIPE,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        start_new_session=True,
+    )
+    assert process.stdin is not None
+    process.stdin.write(json.dumps(job).encode("utf-8"))
+    process.stdin.close()
+
+
+def _base_properties() -> dict:
+    return {
+        "browser_harness_version": _version() or "unknown",
+        "python_version": platform.python_version(),
+        "os": platform.system() or "unknown",
+        "machine": platform.machine() or "unknown",
+    }
+
+
+def _cdp_hostname() -> str | None:
+    value = os.environ.get("BU_CDP_WS") or os.environ.get("BU_CDP_URL")
+    if not value:
+        return None
+    try:
+        return urlparse(value if "://" in value else f"//{value}").hostname
+    except ValueError:
+        return None
+
+
+def capture(event: str, properties: dict | None = None) -> None:
+    if not is_enabled():
+        return
+    try:
+        payload = {
+            "api_key": POSTHOG_KEY,
+            "distinct_id": _install_id(),
+            "event": event,
+            "properties": {
+                **_base_properties(),
+                "$process_person_profile": False,
+                **_safe_properties(properties),
+            },
+        }
+        _send_detached(payload)
+    except Exception:
+        return
+
+
+def capture_cli_event(
+    *,
+    action: str,
+    command: str,
+    task: str | None = None,
+    browser: str | None = None,
+    output: str | None = None,
+    output_length: int | None = None,
+    steps: list | None = None,
+    step_count: int | None = None,
+    duration_seconds: float | None = None,
+    exit_code: int | None = None,
+    error_message: str | None = None,
+) -> None:
+    if not is_enabled():
+        return
+    try:
+        payload = {
+            "api_key": POSTHOG_KEY,
+            "distinct_id": _install_id(),
+            "event": "cli_event",
+            "properties": {
+                **_base_properties(),
+                "$process_person_profile": True,
+                "action": action,
+                "command": command,
+                # 'cloud' | 'cdp' | 'local'
+                "browser": browser,
+                "cdp_url": _cdp_hostname(),
+                "client": os.environ.get("BH_CLIENT") or None,
+                "client_version": os.environ.get("BH_CLIENT_VERSION") or None,
+                "agent_client": _detect_agent_client(),
+                "model": os.environ.get("BROWSER_USE_AGENT_MODEL") or None,
+                "model_provider": os.environ.get("BROWSER_USE_MODEL_PROVIDER") or None,
+                "task": task[:MAX_TASK_LENGTH] if task is not None else None,
+                "task_length": len(task) if task is not None else None,
+                "output": output,
+                "output_length": output_length,
+                "steps": steps,
+                "step_count": step_count,
+                "duration_seconds": duration_seconds,
+                "exit_code": exit_code,
+                "error_message": error_message,
+            },
+        }
+        _send_detached(payload)
+    except Exception:
+        return
+
+
+def run_telemetry_cli(argv: list[str]) -> int:
+    if not argv or argv == ["status"]:
+        print(json.dumps(status(), indent=2))
+        return 0
+    if argv == ["disable"]:
+        print(json.dumps(set_enabled(False), indent=2))
+        return 0
+    if argv == ["enable"]:
+        print(json.dumps(set_enabled(True), indent=2))
+        return 0
+    print("usage: browser-harness telemetry [status|enable|disable]")
+    return 2

browser-harness/src/browser_harness/video-template.html

@@ -0,0 +1,970 @@
+<!DOCTYPE html>
+<!-- browser-harness video template: renders a recording as a structured,
+     privacy-safe explanatory video — chapter plan, semantic routes, readable
+     narration, cursor-led camera, immediate click results, explanation/outcome
+     cards — and exports webm via MediaRecorder. Everything is a pure function
+     of the playhead: seek(t) is exact. See make-video.md for the workflow. -->
+<html>
+<head>
+<meta charset="utf-8">
+<title>browser-harness video</title>
+<style>
+  html, body { margin: 0; height: 100%; background: #0b0e14; overflow: hidden; }
+  #stage { display: block; width: 100vw; height: 100vh; object-fit: contain; }
+  #hud { position: fixed; left: 12px; bottom: 10px; color: #9aa; font: 12px/1.4 ui-monospace, monospace;
+         background: rgba(0,0,0,.55); padding: 6px 10px; border-radius: 8px; user-select: none; }
+</style>
+</head>
+<body>
+<canvas id="stage" width="1920" height="1080"></canvas>
+<div id="hud"></div>
+<script src="composition.js"></script>
+<script>
+"use strict";
+/* composition.js is compiler-owned. Author edit-brief.json; do not hand-edit
+   renderer fields or copy this template as an alternative workflow. */
+const C = window.COMPOSITION;
+const VW = () => C.viewport?.w || 1392, VH = () => C.viewport?.h || 1170;
+
+// ------------------------------ tuning ------------------------------
+const W = 1920, H = 1080;
+const PAD = 108;                   // generous breathing room around the window
+const FRAME_STYLE = C.frameStyle || "native";
+const TABSTRIP = FRAME_STYLE === "browser" ? 36 : 32;
+const TOOLBAR = FRAME_STYLE === "browser" ? 44 : 0;
+const CHROME = FRAME_STYLE === "raw" ? 0 : TABSTRIP + TOOLBAR;
+const MOTION = C.motion || {};
+const PACING = C.pacing || {};
+const REDUCED_MOTION = matchMedia("(prefers-reduced-motion: reduce)").matches;
+const PUNCH_S = REDUCED_MOTION ? 0 : (MOTION.zoomDuration ?? 0.46);
+const DRIFT_MAX = REDUCED_MOTION ? 0 : (MOTION.panDuration ?? 0.58);
+const CUR_S = REDUCED_MOTION ? 0 : (MOTION.cursorDuration ?? 0.52);
+const AUTO_ZOOM = MOTION.autoZoom ?? 1.7;
+const WIDE_SCALE = MOTION.wideScale ?? 0.8;
+const CLICK_SAFE = {
+  left: 140, right: 140, top: 150, bottom: 190,
+  ...(MOTION.clickSafeInset || {}),
+};
+const REACTION_LAG = REDUCED_MOTION ? 0 : (MOTION.reactionLag ?? 0.025);
+const REACTION_FADE = REDUCED_MOTION ? 0.001 : (MOTION.reactionFade ?? 0.04);
+const RADIUS = 12;
+const RAIL = H - 142;              // readable narration above the action/time rail
+const STAGE = 0.94;                // camera output inset — backdrop margin at any zoom
+const ACCENT = "#6ee7ff";
+const MONO = "ui-monospace, 'SF Mono', Menlo, monospace";
+const SANS = "system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif";
+const SERIF = "'Tiempos Headline', 'Tiempos Text', 'Iowan Old Style', Georgia, serif";
+
+const easeOutCubic = t => 1 - Math.pow(1 - t, 3);
+const easeOutQuart = t => 1 - Math.pow(1 - t, 4);
+const easeOutQuint = t => 1 - Math.pow(1 - t, 5);
+const easeInOut = t => t < .5 ? 4*t*t*t : 1 - Math.pow(-2*t + 2, 3) / 2;
+const clamp = (v, a, b) => Math.min(b, Math.max(a, v));
+const lerp = (a, b, t) => a + (b - a) * t;
+
+// ------------------------------ timeline ------------------------------
+function cardText(b) {
+  const details = b.kind === "intro" ? (C.plan || [])
+    : b.kind === "explanation" ? (b.points || []).flatMap(p => [p.label, p.text])
+    : b.kind === "outcome" ? (b.outcomes || [])
+    : [];
+  return [b.title, b.sub, ...details].filter(Boolean).join(" ");
+}
+const wordCount = text => text ? String(text).trim().split(/\s+/).length : 0;
+const cardReadSeconds = b => 0.4 + wordCount(cardText(b)) * 60 / (C.readingWpm || 380);
+const cardBaseSeconds = b => b.kind === "intro" || b.kind === "outcome" ? 4.5
+  : b.kind === "explanation" ? 4 : 3.5;
+const cardTargetSeconds = b => Math.max(cardBaseSeconds(b), cardReadSeconds(b));
+function defaultDur(b) {
+  const text = b.card ? cardText(b) : (b.narration || b.caption);
+  const words = text ? text.trim().split(/\s+/).length : 0;
+  let base = b.card ? 3.5 : 0.7;
+  if (b.kind === "intro" || b.kind === "outcome") base = 4.5;
+  if (b.kind === "explanation") base = 4;
+  if (b.click) base = 1.15;
+  if (b.after) base = Math.max(base, 1.4);   // let the consequence land
+  if (b.type) base = Math.max(base, 0.6 + b.type.text.length * 0.035);
+  if (b.card) return cardTargetSeconds(b);
+  const captionBase = PACING.captionBaseSeconds ?? 0.35;
+  const secondsPerWord = PACING.captionSecondsPerWord ?? 0.2;
+  return Math.max(base, words ? captionBase + secondsPerWord * words : base);
+}
+const beats = C.beats;
+beats.forEach(b => { if (b.dur == null) b.dur = defaultDur(b); });
+const starts = []; let T = 0;
+for (const b of beats) { starts.push(T); T += b.dur; }
+const DURATION = T;
+const beatAt = t => { let i = beats.length - 1; while (i > 0 && t < starts[i]) i--; return i; };
+const firstWindowBeat = beats.findIndex(b => !b.card);
+
+beats.forEach(b => {
+  if (b.label === undefined) {
+    if (b.click && b.cursor) b.label = `click(${Math.round(b.cursor.x)}, ${Math.round(b.cursor.y)})`;
+    else if (b.type) b.label = `type("${b.type.text}")`;
+  }
+});
+const stepOf = []; let stepCount = 0;
+beats.forEach((b, i) => { if (b.label) stepCount++; stepOf[i] = stepCount; });
+
+// ------------------------------ preflight ------------------------------
+const usedFrames = [...new Set(beats.flatMap(b => [b.frame, b.after]).filter(Boolean))];
+const reviewedFrames = new Set(C.privacy?.reviewedFrames || []);
+const preflightErrors = [];
+const preflightWarnings = [];
+const unsafeRoute = /@|[?#]|:\/\/|onmicrosoft|(?:tenant|user|object)[_-]?id|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+const opaqueHex = /^#[0-9a-f]{6}$/i;
+if (C.schemaVersion !== 1)
+  preflightErrors.push("composition must use schema version 1");
+if (C.frameStyle !== "native" || C.readingWpm !== 380)
+  preflightErrors.push("composition changed generated typography or frame style");
+if (!Number.isFinite(C.durationBudget) || DURATION > C.durationBudget + 0.001)
+  preflightErrors.push(
+    `video is ${DURATION.toFixed(1)}s; shorten it to the ${Number(C.durationBudget).toFixed(1)}s budget`,
+  );
+if (!Array.isArray(C.plan) || C.plan.length < 2 || C.plan.length > 5)
+  preflightErrors.push("plan must contain 2–5 steps");
+if (!beats[0]?.card || beats[0]?.kind !== "intro" || beats[0]?.dur < 4)
+  preflightErrors.push("first beat must be an intro card lasting at least 4 seconds");
+if (!beats.at(-1)?.card || beats.at(-1)?.kind !== "outcome" || !beats.at(-1)?.outcomes?.length)
+  preflightErrors.push("last beat must be an outcome card with achieved outcomes");
+for (const frame of usedFrames)
+  if (!reviewedFrames.has(frame)) preflightErrors.push(`privacy review missing: ${frame}`);
+for (const [i, b] of beats.entries()) {
+  if (b.card && b.dur + 0.001 < cardTargetSeconds(b))
+    preflightErrors.push(`beat ${i + 1} card is shorter than its structured scan target`);
+  if (b.kind === "explanation") {
+    const labels = (b.points || []).map(point => String(point.label || "").toLowerCase());
+    if (labels.join("|") !== "observed|mistake|correction")
+      preflightErrors.push(`beat ${i + 1} explanation must be Observed, Mistake, Correction`);
+  }
+}
+if (FRAME_STYLE === "browser" && C.authenticity?.allowSyntheticChrome !== true)
+  preflightErrors.push("synthetic browser chrome requires authenticity.allowSyntheticChrome=true");
+for (const frame of usedFrames) {
+  for (const [i, rect] of (C.redact?.[frame] || []).entries()) {
+    const mask = C.privacy?.mask || {};
+    const fill = rect.fill ?? mask.fill ?? "#f2f4f7";
+    const stroke = rect.stroke ?? mask.stroke ?? "#e2e7ec";
+    if (!opaqueHex.test(fill))
+      preflightErrors.push(`${frame} mask ${i + 1} fill must be opaque six-digit hex`);
+    if (stroke && !opaqueHex.test(stroke))
+      preflightErrors.push(`${frame} mask ${i + 1} stroke must be opaque six-digit hex`);
+  }
+}
+for (let i = 0; i < beats.length; i++) {
+  const b = beats[i];
+  const text = b.narration || b.caption;
+  const wc = text ? String(text).trim().split(/\s+/).length : 0;
+  if (wc > 7) preflightErrors.push(`beat ${i + 1} narration exceeds 7 words`);
+  if (!b.card && (!Number.isInteger(b.chapter) || b.chapter < 0 || b.chapter >= (C.plan || []).length))
+    preflightErrors.push(`beat ${i + 1} has no valid chapter`);
+  if (!b.card && !b.route) preflightErrors.push(`beat ${i + 1} has no semantic route`);
+  if (b.url) preflightErrors.push(`beat ${i + 1} uses a raw url; use route`);
+  if (unsafeRoute.test(String(b.route || "")) || unsafeRoute.test(String(b.afterRoute || "")))
+    preflightErrors.push(`beat ${i + 1} route contains sensitive/raw URL material`);
+}
+window.videoPreflight = () => ({
+  errors: [...preflightErrors], warnings: [...preflightWarnings], frames: [...usedFrames],
+});
+
+// ------------------------------ assets ------------------------------
+const images = new Map();
+let ready = false;
+const srcs = new Set();
+beats.forEach(b => { if (b.frame) srcs.add(b.frame); if (b.after) srcs.add(b.after); });
+Promise.all([...srcs].map(src => new Promise(res => {
+  const im = new Image();
+  im.onload = () => { images.set(src, im); res(); };
+  im.onerror = () => res();
+  im.src = src;
+}))).then(() => { ready = true; draw(); });
+window.videoReady = () => ready;
+
+// browser-use logo as Path2D (1000×1000 viewBox), injected at build time.
+const LOGO_D = "M585.941 27.9374C672.468 -1.01696 755.454 -8.30297 825.373 10.0229L826.395 10.2948L827 10.4392L827.641 10.6284C847.195 15.931 865.182 23.1177 881.555 32.0311L882.227 32.3732L882.764 32.6944C906.114 45.592 926.136 62.0317 942.682 81.5504L943.373 82.306L944.245 83.4133C946.291 85.8804 948.277 88.3966 950.214 90.9591L950.305 91.0486L950.355 91.109L950.764 91.6906C955.445 97.9479 959.8 104.485 963.827 111.286L964.182 111.755H964.105C965.309 113.795 966.482 115.86 967.623 117.947L967.736 118.16C967.754 118.194 967.773 118.228 967.791 118.261L968.136 118.852C968.418 119.369 968.673 119.888 968.95 120.408L969.173 120.816C970.409 123.152 971.6 125.517 972.764 127.909L973.191 128.769L973.268 128.959C974.382 131.276 975.459 133.619 976.5 135.988L976.668 136.32L976.841 136.761C979.995 143.992 982.832 151.46 985.345 159.154C985.564 159.824 985.782 160.496 985.995 161.169L986.032 161.204L986.064 161.32L986.186 161.773C988.514 169.161 990.55 176.753 992.291 184.537L992.386 184.823L992.404 184.879L993.014 187.773L993.091 188.222C993.645 190.862 994.164 193.524 994.65 196.208L994.745 196.627H994.841V197.246C996.318 205.56 997.473 214.078 998.3 222.786L998.309 222.849C999.132 231.502 999.627 240.388 999.8 249.407L999.818 249.586L999.823 249.643L999.864 250.083L999.823 250.618C999.882 254.587 999.886 258.592 999.823 262.628V263.4L999.818 263.827C999.645 272.954 999.132 282.249 998.314 291.701V291.914C997.127 305.459 995.259 319.327 992.723 333.483L992.414 335.331L992 337.438C986.227 368.283 977.241 400.477 964.936 433.68L964.459 435.07L964.132 436.006L963.7 435.256C963.627 435.192 963.577 435.106 963.555 435.011L954.727 419.751L945.673 404.357L936.286 389.309L936.041 388.924L926.414 374.112L926.35 374.017L916.232 358.915L910.195 350.317L905.823 343.979L905.691 343.8L894.95 329.184L888.609 320.729L883.923 314.384L883.809 314.228L883.841 314.052C883.841 314.047 883.841 314.057 883.841 314.052L885.195 306.069V305.778L886.255 298.195L887.091 291.914L887.168 291.374L887.209 291.159L887.314 290.632L888.064 283.111L888.518 275.73L888.968 268.646L889.118 261.552L889.123 261.489V261.107L889.273 254.779L889.132 250.083L889.123 249.675V248.142L888.818 241.65L888.4 236.643L888.364 236.23V235.466L887.764 229.309L887.014 223.577L886.109 217.852L885.327 213.031L885.205 212.282L884.609 210.191L883.995 206.979L882.795 202.035L882.777 201.975L881.536 197.835H881.423V197.452L881.418 197.382V197.148L879.932 192.541L878.423 188.011L877.227 185.173L876.768 183.805L874.968 179.752L873.186 175.897L873.159 175.839L873.118 175.758L871.205 172.075L869.25 168.471L867.15 165.018L864.891 161.703L862.636 158.547L857.964 152.519L852.845 147.102L849.091 143.651L845.195 140.201L840.977 136.887L837.068 134.192L836.623 133.883L833.164 131.651L831.954 130.872L829.104 129.372L826.977 128.159L821.718 125.455L816.164 123.053L810.286 120.792L805.627 119.44L803.977 118.838L797.332 117.026L790.409 115.371L783.032 113.866L782.509 113.783L775.341 112.659L767.2 111.754L758.623 111.151L749.75 110.851H740.432L730.868 110.999L720.918 111.754L716.018 112.187L710.65 112.662L700.255 113.865L689.391 115.524L678.373 117.639L667.059 120.052L667.009 120.063L655.518 122.749L655.441 122.768L643.673 125.936L631.759 129.402L631.318 129.543L619.541 133.325L607.309 137.705L597.955 141.325L595.055 142.429L594.786 142.533L582.264 147.66L569.604 153.085L556.75 158.983L544.077 165.244L543.936 165.318L543.841 165.368L530.95 171.955L517.964 178.904L504.982 186.149L492.005 193.843L482.95 199.428L478.864 201.849L475.436 204.039L465.891 210.146L463.341 211.946L453.068 218.742L452.82 218.917L444.462 224.784L440.077 227.805L427.248 237.012L415.051 246.158L414.57 246.52L408.533 251.197L401.89 256.332L392.468 263.977L391.527 264.74L391.477 264.782L389.356 266.449L376.99 276.851L364.764 287.567L352.744 298.537L352.687 298.59L340.755 309.613L329.135 321.082L328.985 321.229L317.509 332.708L306.345 344.471L300.758 350.514L295.279 356.287L295.168 356.406L284.456 368.622L273.9 380.837L273.781 381.016L263.471 393.383L261.663 395.642L253.357 405.912L249.588 410.884L244.251 417.862L243.698 418.588L234.189 431.261L224.982 444.093L216.073 456.928L207.474 469.9L199.456 482.436L199.17 482.881L199.092 483.008L191.359 495.798L191.321 495.862L186.791 503.563L183.619 508.851L183.59 508.901L178.039 519.106L176.381 521.814L176.255 522.059L169.739 534.649L169.705 534.713L169.653 534.763L169.559 534.858L163.1 547.771L162.045 550.038L157.062 560.602L151.356 573.364L148.156 580.829L145.894 586.104L141.097 598.544L141.069 598.621L136.413 610.934L136.414 611.152L136.415 611.611H136.28L132.157 623.388L131.256 626.387L128.387 635.455L126.729 641.33L124.915 647.382L122.804 655.519L121.9 658.991L119.614 668.845L119.485 669.404L119.182 670.613L116.92 681.772L114.96 692.771L114.95 692.849L113.452 703.489L113.425 703.73L112.697 710.423L112.254 713.817L112.245 713.885L111.497 723.917L111.495 723.962L111.497 724.417L110.889 733.808L110.887 735.289L110.889 736.798V737.252L110.737 743.304L110.889 749.624V752.355L111.Line truncated
+const LOGO = LOGO_D.startsWith("M") ? new Path2D(LOGO_D) : null;
+function drawLogo(x, y, size, color, alpha = 1) {
+  if (!LOGO) return;
+  ctx.save();
+  ctx.globalAlpha = alpha; ctx.fillStyle = color;
+  ctx.translate(x, y); ctx.scale(size / 1000, size / 1000);
+  ctx.fill(LOGO);
+  ctx.restore();
+}
+
+// ------------------------------ layout ------------------------------
+function frameRect() {
+  const availW = W - PAD * 2, availH = H - PAD * 2;
+  const s = Math.min(availW / VW(), (availH - CHROME) / VH());
+  const w = VW() * s, h = VH() * s + CHROME;
+  return { x: (W - w) / 2, y: (H - h) / 2 - 14, w, h, s };  // lifted: bottom rail breathes
+}
+const FR = frameRect();
+const pageX = x => FR.x + x * FR.s;
+const pageY = y => FR.y + CHROME + y * FR.s;
+
+// ------------------------------ cursor ------------------------------
+const curTargets = [];
+{
+  let last = C.cursorStart || { x: VW() * 0.55, y: VH() * 0.25 };
+  for (const b of beats) {
+    if (b.cursor) last = b.cursor;
+    else if (b.type) last = { x: b.type.box.x + b.type.box.w * 0.3, y: b.type.box.y + b.type.box.h / 2 };
+    curTargets.push(last);
+  }
+}
+const cursorActive = i => !!(beats[i].cursor || beats[i].click || beats[i].type);
+const glideDelay = i => REDUCED_MOTION ? 0 : (beats[i].cursorDelay ?? 0.06);
+const glideDuration = i => Math.min(CUR_S, beats[i].dur * 0.42);
+const clickTime = i => glideDelay(i) + glideDuration(i) + (REDUCED_MOTION ? 0 : 0.035);
+function cursorMotion(i, lt) {
+  const cur = curTargets[i];
+  if (i <= 0) return { ...cur, arrive: 0 };
+  const prev = curTargets[i - 1];
+  const glide = glideDuration(i);
+  const k = glide ? easeOutQuint(clamp((lt - glideDelay(i)) / glide, 0, 1)) : 1;
+  return {
+    x: lerp(prev.x, cur.x, k),
+    y: lerp(prev.y, cur.y, k),
+    arrive: glideDelay(i) + glide,
+  };
+}
+function cursor(t) {
+  const i = beatAt(t);
+  const lt = t - starts[i];
+  const motion = cursorMotion(i, lt);
+  // fade out on idle beats, fade in when working again
+  let alpha;
+  if (cursorActive(i)) alpha = (i > 0 && !cursorActive(i - 1)) ? easeOutCubic(clamp(lt / 0.25, 0, 1)) : 1;
+  else alpha = (i > 0 && cursorActive(i - 1)) ? 1 - easeInOut(clamp(lt / 0.35, 0, 1)) : 0;
+  return { ...motion, alpha };
+}
+
+// ------------------------------ camera ------------------------------
+const WIDE = { s: WIDE_SCALE, x: W / 2, y: H / 2, mode: "wide" };
+function framedTarget(point, scale, mode = "fixed") {
+  let px = pageX(point.x), py = pageY(point.y);
+  const vw2 = W / (2 * scale), vh2 = H / (2 * scale);
+  px = clamp(px, FR.x + Math.min(vw2, FR.w / 2), FR.x + FR.w - Math.min(vw2, FR.w / 2));
+  py = clamp(py, FR.y + Math.min(vh2, FR.h / 2), FR.y + FR.h - Math.min(vh2, FR.h / 2));
+  if (py - vh2 - FR.y < CHROME + 190 * FR.s) py = FR.y + Math.min(vh2, FR.h / 2);
+  if (px - vw2 - FR.x < 56 * FR.s) px = FR.x + Math.min(vw2, FR.w / 2);
+  return { s: scale, x: px, y: py, mode };
+}
+
+function projectedPoint(point, cam) {
+  return {
+    x: W / 2 + STAGE * ((cam.shake || 0) + cam.s * (pageX(point.x) - cam.x)),
+    y: H / 2 + STAGE * cam.s * (pageY(point.y) - cam.y),
+  };
+}
+function clickPointIsSafe(point, cam) {
+  const p = projectedPoint(point, cam);
+  return p.x >= CLICK_SAFE.left && p.x <= W - CLICK_SAFE.right &&
+    p.y >= CLICK_SAFE.top && p.y <= H - CLICK_SAFE.bottom;
+}
+function nudgePointIntoSafeArea(cam, point) {
+  const p = projectedPoint(point, cam);
+  const safeX = clamp(p.x, CLICK_SAFE.left, W - CLICK_SAFE.right);
+  const safeY = clamp(p.y, CLICK_SAFE.top, H - CLICK_SAFE.bottom);
+  return {
+    ...cam,
+    x: cam.x + (p.x - safeX) / (STAGE * cam.s),
+    y: cam.y + (p.y - safeY) / (STAGE * cam.s),
+  };
+}
+function clickSafeTarget(focus, point, scale, mode = "fixed") {
+  const requested = framedTarget(focus, scale, mode);
+  if (clickPointIsSafe(point, requested)) return requested;
+
+  // Edge actions should pull back before they push the click under captions,
+  // telemetry, or the video edge. Keep the largest zoom that remains safe.
+  let low = Math.min(scale, WIDE_SCALE), high = scale;
+  let best = framedTarget(focus, low, mode);
+  if (!clickPointIsSafe(point, best)) return nudgePointIntoSafeArea(best, point);
+  for (let n = 0; n < 14; n++) {
+    const mid = (low + high) / 2;
+    const candidate = framedTarget(focus, mid, mode);
+    if (clickPointIsSafe(point, candidate)) { best = candidate; low = mid; }
+    else high = mid;
+  }
+  return best;
+}
+
+const camTargets = [];
+for (let i = 0; i < beats.length; i++) {
+  const b = beats[i];
+  if (b.card || b.wide) { camTargets.push(WIDE); continue; }
+  if (b.zoom) {
+    const scale = b.zoom.scale || AUTO_ZOOM;
+    camTargets.push(b.click && b.cursor
+      ? clickSafeTarget(b.zoom, b.cursor, scale)
+      : framedTarget(b.zoom, scale));
+    continue;
+  }
+  if (MOTION.autoFollow !== false && cursorActive(i) && !b.noFollow) {
+    const scale = b.followScale || AUTO_ZOOM;
+    camTargets.push(b.click
+      ? clickSafeTarget(curTargets[i], curTargets[i], scale, "follow")
+      : framedTarget(curTargets[i], scale, "follow"));
+    continue;
+  }
+  if (i === 0 || beats[i - 1].card) camTargets.push(WIDE);
+  else camTargets.push({ ...camTargets[i - 1], mode: "fixed" });
+}
+
+function camera(t) {
+  const i = beatAt(t), b = beats[i], lt = t - starts[i];
+  const final = camTargets[i];
+  const desired = final.mode === "follow"
+    ? (b.click
+      ? clickSafeTarget(cursorMotion(i, lt), cursorMotion(i, lt), final.s, "follow")
+      : framedTarget(cursorMotion(i, lt), final.s, "follow"))
+    : final;
+  let cam;
+  if (i === 0 || b.card || b.cameraCut) cam = { ...desired };
+  else {
+    const prev = beats[i - 1].card ? WIDE : camTargets[i - 1];
+    const zooming = Math.abs(prev.s - desired.s) > 0.01;
+    const dur = zooming ? PUNCH_S : Math.min(DRIFT_MAX, b.dur * 0.65);
+    const k = dur ? easeOutQuint(clamp(lt / dur, 0, 1)) : 1;
+    cam = {
+      s: lerp(prev.s, desired.s, k),
+      x: lerp(prev.x, desired.x, k),
+      y: lerp(prev.y, desired.y, k),
+    };
+  }
+  if (b.errorMotion && !REDUCED_MOTION) {
+    const damp = 1 - clamp(lt / 0.42, 0, 1);
+    cam.shake = Math.sin(lt * 42) * 5 * damp;
+  } else cam.shake = 0;
+  return cam;
+}
+
+const clickVisibility = beats.flatMap((b, i) => {
+  if (!b.click || !b.cursor) return [];
+  const t = starts[i] + Math.min(clickTime(i), Math.max(0, b.dur - 0.001));
+  const cam = camera(t);
+  const point = projectedPoint(b.cursor, cam);
+  const visible = clickPointIsSafe(b.cursor, cam);
+  if (!visible) preflightErrors.push(`beat ${i + 1} click falls outside the safe viewport`);
+  const resultTime = b.after
+    ? starts[i] + Math.min(clickTime(i) + REACTION_LAG + REACTION_FADE, b.dur)
+    : t;
+  return [{
+    beat: i + 1, label: b.label, time: t, resultTime,
+    x: point.x, y: point.y, scale: cam.s, visible,
+  }];
+});
+window.clickVisibility = () => clickVisibility.map(item => ({ ...item }));
+
+// ------------------------------ drawing ------------------------------
+const canvas = document.getElementById("stage");
+const ctx = canvas.getContext("2d");
+
+const BG = Array.isArray(C.bg) ? C.bg : [C.bg || "#F0EEE6"];
+const LIGHT_BG = (() => {   // perceived luminance of the backdrop
+  const c = h => parseInt(h, 16);
+  const lum = s => { const h = s.replace("#", "");
+    return 0.299 * c(h.slice(0, 2)) + 0.587 * c(h.slice(2, 4)) + 0.114 * c(h.slice(4, 6)); };
+  return BG.reduce((a, s) => a + lum(s), 0) / BG.length > 128;
+})();
+const INK = LIGHT_BG ? "#1f1e1b" : "#ffffff";          // text/logo on the backdrop
+function drawBackdrop() {
+  if (BG.length < 2) { ctx.fillStyle = BG[0]; ctx.fillRect(0, 0, W, H); return; }
+  const g = ctx.createLinearGradient(0, 0, W, H);
+  g.addColorStop(0, BG[0]); g.addColorStop(1, BG[1]);
+  ctx.fillStyle = g; ctx.fillRect(0, 0, W, H);
+}
+
+function roundRect(x, y, w, h, r) {
+  ctx.beginPath();
+  ctx.moveTo(x + r, y);
+  ctx.arcTo(x + w, y, x + w, y + h, r);
+  ctx.arcTo(x + w, y + h, x, y + h, r);
+  ctx.arcTo(x, y + h, x, y, r);
+  ctx.arcTo(x, y, x + w, y, r);
+  ctx.closePath();
+}
+
+// --- realistic Chrome window (macOS, light theme) ---
+function afterIsVisible(i, lt) {
+  const b = beats[i];
+  if (!b.after) return false;
+  const at = b.click ? clickTime(i) + REACTION_LAG : Math.min(0.22, b.dur * 0.22);
+  return lt >= at + REACTION_FADE;
+}
+function drawChromeWindow(i, lt) {
+  ctx.save();
+  ctx.shadowColor = LIGHT_BG ? "rgba(40,35,25,0.3)" : "rgba(0,0,0,0.6)";
+  ctx.shadowBlur = LIGHT_BG ? 54 : 70; ctx.shadowOffsetY = LIGHT_BG ? 18 : 28;
+  roundRect(FR.x, FR.y, FR.w, FR.h, RADIUS);
+  ctx.fillStyle = FRAME_STYLE === "browser" ? "#DEE1E6" : "#EAECF0"; ctx.fill();
+  ctx.restore();
+
+  if (FRAME_STYLE === "raw") return;
+
+  const tcy = FR.y + TABSTRIP / 2;
+  [["#FF5F57"], ["#FEBC2E"], ["#28C840"]].forEach(([c], k) => {
+    ctx.beginPath(); ctx.arc(FR.x + 22 + k * 20, tcy, 6, 0, 7); ctx.fillStyle = c; ctx.fill();
+  });
+
+  // Native framing keeps the recording honest: no reconstructed tab title or
+  // fake URL masquerading as captured browser evidence.
+  if (FRAME_STYLE !== "browser") return;
+
+  const tabX = FR.x + 84, tabW = Math.min(240, FR.w * 0.3), tabH = TABSTRIP - 8;
+  ctx.beginPath();
+  ctx.moveTo(tabX - 8, FR.y + TABSTRIP);
+  ctx.quadraticCurveTo(tabX, FR.y + TABSTRIP, tabX, FR.y + TABSTRIP - 8);
+  ctx.lineTo(tabX, FR.y + 12);
+  ctx.quadraticCurveTo(tabX, FR.y + 4, tabX + 8, FR.y + 4);
+  ctx.lineTo(tabX + tabW - 8, FR.y + 4);
+  ctx.quadraticCurveTo(tabX + tabW, FR.y + 4, tabX + tabW, FR.y + 12);
+  ctx.lineTo(tabX + tabW, FR.y + TABSTRIP - 8);
+  ctx.quadraticCurveTo(tabX + tabW, FR.y + TABSTRIP, tabX + tabW + 8, FR.y + TABSTRIP);
+  ctx.closePath();
+  ctx.fillStyle = "#fff"; ctx.fill();
+
+  const after = afterIsVisible(i, lt);
+  const route = (after && beats[i].afterRoute) || sticky(i, "route") || sticky(i, "url") || "Browser";
+  const tab = (after && beats[i].afterTab) || sticky(i, "tab") || route.split("/").pop().trim() || "Browser";
+  ctx.beginPath(); ctx.arc(tabX + 18, FR.y + 4 + tabH / 2, 6.5, 0, 7);
+  ctx.fillStyle = "#F19E38"; ctx.fill();
+  ctx.fillStyle = "#3C4043"; ctx.font = `500 13px ${SANS}`;
+  ctx.textAlign = "left"; ctx.textBaseline = "middle";
+  ctx.fillText(fitText(tab, tabW - 64), tabX + 32, FR.y + 5 + tabH / 2);
+  ctx.fillStyle = "#5F6368"; ctx.font = `400 14px ${SANS}`;
+  ctx.fillText("×", tabX + tabW - 20, FR.y + 5 + tabH / 2);
+  ctx.font = `400 18px ${SANS}`;
+  ctx.fillText("+", tabX + tabW + 18, FR.y + 5 + tabH / 2);
+
+  ctx.fillStyle = "#fff";
+  ctx.fillRect(FR.x, FR.y + TABSTRIP, FR.w, TOOLBAR);
+  const ty = FR.y + TABSTRIP + TOOLBAR / 2;
+  arrow(FR.x + 26, ty, -1, "#5F6368");
+  arrow(FR.x + 58, ty, 1, "#C0C3C7");
+  reloadIcon(FR.x + 90, ty);
+
+  const ox = FR.x + 116, ow = FR.w - 116 - 118, oh = 30;
+  roundRect(ox, ty - oh / 2, ow, oh, oh / 2);
+  ctx.fillStyle = "#F1F3F4"; ctx.fill();
+  lockIcon(ox + 18, ty);
+  ctx.fillStyle = "#202124"; ctx.font = `400 14.5px ${SANS}`;
+  ctx.textAlign = "left"; ctx.textBaseline = "middle";
+  ctx.fillText(fitText(route, ow - 70), ox + 34, ty + 1);
+  starIcon(ox + ow - 20, ty);
+
+  ctx.beginPath(); ctx.arc(FR.x + FR.w - 62, ty, 12, 0, 7);
+  ctx.fillStyle = "#7C4DFF"; ctx.fill();
+  ctx.fillStyle = "#fff"; ctx.font = `600 12px ${SANS}`; ctx.textAlign = "center";
+  ctx.fillText("G", FR.x + FR.w - 62, ty + 1);
+  ctx.fillStyle = "#5F6368";
+  for (let k = -1; k <= 1; k++) { ctx.beginPath(); ctx.arc(FR.x + FR.w - 28, ty + k * 5, 1.8, 0, 7); ctx.fill(); }
+}
+
+function arrow(x, y, dir, color) {
+  ctx.strokeStyle = color; ctx.lineWidth = 1.8; ctx.lineCap = "round";
+  ctx.beginPath();
+  ctx.moveTo(x + 6 * dir, y - 5); ctx.lineTo(x - 3 * dir, y); ctx.lineTo(x + 6 * dir, y + 5);
+  ctx.moveTo(x - 3 * dir, y); ctx.lineTo(x + 8 * dir, y);
+  ctx.stroke();
+}
+function reloadIcon(x, y) {
+  ctx.strokeStyle = "#5F6368"; ctx.lineWidth = 1.8;
+  ctx.beginPath(); ctx.arc(x, y, 7, -0.4, 5.0); ctx.stroke();
+  ctx.beginPath(); ctx.moveTo(x + 7, y - 5); ctx.lineTo(x + 7, y - 1); ctx.lineTo(x + 3, y - 2);
+  ctx.fillStyle = "#5F6368"; ctx.fill();
+}
+function lockIcon(x, y) {
+  ctx.strokeStyle = "#5F6368"; ctx.lineWidth = 1.6;
+  ctx.beginPath(); ctx.arc(x, y - 3, 3.5, Math.PI, 0); ctx.stroke();
+  ctx.fillStyle = "#5F6368";
+  roundRect(x - 5.5, y - 3, 11, 8, 2); ctx.fill();
+}
+function starIcon(x, y) {
+  ctx.strokeStyle = "#9AA0A6"; ctx.lineWidth = 1.4;
+  ctx.beginPath();
+  for (let k = 0; k < 10; k++) {
+    const r = k % 2 ? 3.2 : 7, a = -Math.PI / 2 + k * Math.PI / 5;
+    ctx[k ? "lineTo" : "moveTo"](x + r * Math.cos(a), y + r * Math.sin(a));
+  }
+  ctx.closePath(); ctx.stroke();
+}
+function fitText(s, maxW) {
+  if (ctx.measureText(s).width <= maxW) return s;
+  while (s.length > 1 && ctx.measureText(s + "…").width > maxW) s = s.slice(0, -1);
+  return s + "…";
+}
+function sticky(i, key) {
+  for (let k = i; k >= 0; k--)
+    if (Object.prototype.hasOwnProperty.call(beats[k], key) && beats[k][key] != null && beats[k][key] !== "")
+      return beats[k][key];
+  return null;
+}
+
+// Frame shown at the END of beat i (its consequence, if any)
+const finalFrame = i => beats[i].after || beats[i].frame;
+function fadeDur(i) {
+  const b = beats[i];
+  return b.fade != null ? b.fade : 0;   // hard cut unless explicitly asked
+}
+
+function drawContent(t, i, lt) {
+  ctx.save();
+  roundRect(FR.x, FR.y + CHROME, FR.w, FR.h - CHROME, 2);
+  ctx.clip();
+  const b = beats[i];
+  // entry transition from the previous beat's final frame
+  const prevSrc = i > 0 && !beats[i - 1].card ? finalFrame(i - 1) : null;
+  const fd = fadeDur(i);
+  let base = images.get(b.frame);
+  const shown = [];
+  if (prevSrc && fd > 0 && lt < fd && prevSrc !== b.frame) {
+    drawPage(images.get(prevSrc));
+    shown.push(prevSrc);
+    ctx.globalAlpha = clamp(lt / fd, 0, 1);
+  }
+  if (base) { drawPage(base); shown.push(b.frame); }
+  ctx.globalAlpha = 1;
+  // in-beat consequence: swap to `after` once the click lands
+  if (b.after) {
+    const at = b.click ? clickTime(i) + REACTION_LAG : Math.min(0.22, b.dur * 0.22);
+    const k = clamp((lt - at) / REACTION_FADE, 0, 1);
+    if (k > 0) {
+      const im = images.get(b.after);
+      ctx.globalAlpha = k; drawPage(im); ctx.globalAlpha = 1;
+      if (im) { if (k >= 1) shown.length = 0; shown.push(b.after); }
+    }
+  }
+  if (C.redact)
+    for (const src of shown)
+      for (const r of C.redact[src] || []) drawRedact(r);
+  if (b.type) drawTyping(b, lt);
+  ctx.restore();
+}
+function drawPage(im) { if (im) ctx.drawImage(im, FR.x, FR.y + CHROME, FR.w, VH() * FR.s); }
+
+// Opaque masks may match their surrounding surface, but never use alpha: unlike
+// blur or pixelation, secrets cannot be reconstructed from them.
+function drawRedact(r) {
+  const pad = r.pad ?? C.privacy?.pad ?? 8;
+  const mask = C.privacy?.mask || {};
+  const x = pageX(r.x - pad), y = pageY(r.y - pad);
+  const w = (r.w + pad * 2) * FR.s, h = (r.h + pad * 2) * FR.s;
+  if (w < 2 || h < 2) return;
+  const fill = r.fill ?? mask.fill ?? "#f2f4f7";
+  const stroke = r.stroke ?? mask.stroke ?? "#e2e7ec";
+  const radius = Math.min(r.radius ?? mask.radius ?? 7, w / FR.s / 2, h / FR.s / 2) * FR.s;
+  ctx.save();
+  ctx.globalAlpha = 1;
+  roundRect(x, y, w, h, radius);
+  ctx.fillStyle = fill; ctx.fill();
+  if (stroke) {
+    ctx.strokeStyle = stroke;
+    ctx.lineWidth = Math.max(1, FR.s);
+    ctx.stroke();
+  }
+  ctx.restore();
+}
+
+function drawTyping(b, lt) {
+  const { box, text } = b.type;
+  const visibleText = b.type.redact ? "••••••" : text;
+  const i = beats.indexOf(b);
+  const mag = camTargets[i].s < 1.25 ? 1.7 : 1;   // synthetic pill: enlarge when wide
+  let x = pageX(box.x), y = pageY(box.y), w = box.w * FR.s * mag, h = box.h * FR.s * mag;
+  x -= (mag - 1) * box.w * FR.s * 0.15; y -= (mag - 1) * box.h * FR.s * 0.5;
+  const t0 = 0.35, t1 = Math.max(t0 + 0.25, b.dur - 0.3);
+  const chars = Math.round(clamp((lt - t0) / (t1 - t0), 0, 1) * visibleText.length);
+  ctx.save();
+  roundRect(x, y, w, h, Math.min(8, h / 3));
+  ctx.fillStyle = "rgba(255,255,255,0.98)"; ctx.fill();
+  ctx.strokeStyle = ACCENT; ctx.lineWidth = 1.6; ctx.stroke();
+  ctx.fillStyle = "#111"; ctx.textAlign = "left"; ctx.textBaseline = "middle";
+  ctx.font = `500 ${Math.max(13, h * 0.46)}px ${SANS}`;
+  const shown = visibleText.slice(0, chars);
+  ctx.fillText(shown, x + h * 0.32, y + h / 2 + 1);
+  if (lt >= t0 && (lt % 0.9) < 0.5) {
+    const tw = ctx.measureText(shown).width;
+    ctx.fillStyle = "#333";
+    ctx.fillRect(x + h * 0.32 + tw + 2, y + h * 0.22, 1.6, h * 0.56);
+  }
+  ctx.restore();
+}
+
+function drawCursor(t, i, lt, cam) {
+  const b = beats[i];
+  if (b.card || b.hideCursor) return;
+  const c = cursor(t);
+  if (c.alpha <= 0.01) return;
+  const x = pageX(c.x), y = pageY(c.y);
+  const clickAt = clickTime(i);
+  const pressed = b.click && lt >= clickAt && lt < clickAt + 0.18;
+  const inv = 1 / Math.max(0.01, cam.s * STAGE);
+  const cursorPx = cam.s < 1 ? 52 : 38;
+  ctx.save();
+  ctx.globalAlpha = c.alpha;
+
+  if (b.click && lt >= clickAt) {
+    const rt = clamp((lt - clickAt) / 0.5, 0, 1);
+    ctx.strokeStyle = `rgba(110,231,255,${0.5 * (1 - rt)})`; ctx.lineWidth = inv;
+    ctx.beginPath();
+    ctx.moveTo(x - 34 * inv, y); ctx.lineTo(x - 12 * inv, y); ctx.moveTo(x + 12 * inv, y); ctx.lineTo(x + 34 * inv, y);
+    ctx.moveTo(x, y - 34 * inv); ctx.lineTo(x, y - 12 * inv); ctx.moveTo(x, y + 12 * inv); ctx.lineTo(x, y + 34 * inv);
+    ctx.stroke();
+    ctx.beginPath(); ctx.arc(x, y, (7 + easeOutCubic(rt) * 34) * inv, 0, 7);
+    ctx.strokeStyle = `rgba(255,255,255,${0.8 * (1 - rt)})`;
+    ctx.lineWidth = (3 * (1 - rt) + 1) * inv; ctx.stroke();
+  }
+  const k = (cursorPx / 18.1) * inv * (pressed ? 0.85 : 1);
+  ctx.translate(x, y); ctx.scale(k, k);
+  ctx.shadowColor = "rgba(0,0,0,0.45)"; ctx.shadowBlur = 5; ctx.shadowOffsetY = 2;
+  ctx.beginPath();
+  ctx.moveTo(0, 0); ctx.lineTo(0, 16.5); ctx.lineTo(3.9, 12.8); ctx.lineTo(6.3, 18.1);
+  ctx.lineTo(9.3, 16.8); ctx.lineTo(6.9, 11.6); ctx.lineTo(12.2, 11.4); ctx.closePath();
+  ctx.fillStyle = "#fff"; ctx.fill();
+  ctx.shadowColor = "transparent";
+  ctx.strokeStyle = "#111"; ctx.lineWidth = 1.1; ctx.stroke();
+  ctx.restore();
+}
+
+// --- telemetry (screen space) ---
+function chip(x, y, parts, align = "left", error = false) {
+  // parts: [[text, color], ...] rendered in one pill
+  // One palette: ink on paper (light bg) / paper on ink (dark bg). `parts`
+  // entries are [text, muted?] — no accent colors.
+  ctx.font = `600 21px ${MONO}`;
+  const texts = parts.map(p => p[0]);
+  const logoPad = parts.logo ? 30 : 0;
+  const w = texts.reduce((a, s) => a + ctx.measureText(s).width, 0) + 30 + (parts.length - 1) * 12 + logoPad;
+  const bx = align === "right" ? x - w : x;
+  roundRect(bx, y, w, 48, 24);
+  if (error) {
+    ctx.fillStyle = "rgba(160,40,40,0.95)"; ctx.fill();
+  } else if (LIGHT_BG) {
+    ctx.fillStyle = "rgba(255,253,247,0.9)"; ctx.fill();
+    ctx.strokeStyle = "rgba(31,30,27,0.22)"; ctx.lineWidth = 1; ctx.stroke();
+  } else {
+    ctx.fillStyle = "rgba(9,12,20,0.72)"; ctx.fill();
+    ctx.strokeStyle = "rgba(255,255,255,0.13)"; ctx.lineWidth = 1; ctx.stroke();
+  }
+  const ink = error ? "#fff" : (LIGHT_BG ? "#1f1e1b" : "#f4f2ec");
+  ctx.textAlign = "left"; ctx.textBaseline = "middle";
+  let cx = bx + 15;
+  if (parts.logo) { drawLogo(cx - 2, y + 14, 20, ink, 0.9); cx += logoPad; }
+  for (const [text, muted] of parts) {
+    ctx.globalAlpha = muted ? 0.52 : 1;
+    ctx.fillStyle = ink;
+    ctx.fillText(text, cx, y + 25);
+    ctx.globalAlpha = 1;
+    cx += ctx.measureText(text).width + 12;
+  }
+}
+function drawPlan(i) {
+  const chapter = sticky(i, "chapter") ?? 0;
+  const detour = !!beats[i].detour;
+  const gap = 10, h = 58, maxW = 420;
+  ctx.font = `600 19px ${SANS}`;
+  const widths = C.plan.map((step, n) => Math.min(maxW, Math.max(240, ctx.measureText(`${n + 1}. ${step}`).width + 62)));
+  const total = widths.reduce((sum, width) => sum + width, 0) + gap * (widths.length - 1);
+  let x = (W - total) / 2;
+  for (let n = 0; n < C.plan.length; n++) {
+    const active = n === chapter;
+    roundRect(x, 26, widths[n], h, 18);
+    ctx.fillStyle = active ? "rgba(10,12,18,0.93)" : "rgba(10,12,18,0.58)"; ctx.fill();
+    ctx.strokeStyle = active ? "rgba(110,231,255,0.7)" : "rgba(255,255,255,0.12)";
+    ctx.lineWidth = active ? 2 : 1; ctx.stroke();
+    ctx.fillStyle = active ? "#fff" : "rgba(255,255,255,0.68)";
+    ctx.textAlign = "left"; ctx.textBaseline = "middle";
+    ctx.fillText(`${n + 1}. ${C.plan[n]}`, x + 24, 56);
+    x += widths[n] + gap;
+  }
+  if (detour) {
+    ctx.font = `700 15px ${MONO}`;
+    const label = "DETOUR";
+    const w = ctx.measureText(label).width + 30;
+    roundRect(W / 2 - w / 2, 92, w, 32, 16);
+    ctx.fillStyle = "rgba(128,63,22,0.94)"; ctx.fill();
+    ctx.fillStyle = "#fff"; ctx.textAlign = "center";
+    ctx.fillText(label, W / 2, 108);
+  }
+}
+function drawTelemetry(t, i, lt) {
+  const b = beats[i];
+  if (b.card) return;
+  drawPlan(i);
+  const cy = H - 74;
+  if (b.label || b.error) {
+    const parts = [];
+    if (b.label) {
+      parts.push([`${String(stepOf[i]).padStart(2, "0")}/${String(stepCount).padStart(2, "0")}`, true]);
+      parts.push([b.label, false]);
+    }
+    if (b.error) parts.push(["⚠ ERROR", false]);
+    chip(28, cy, parts, "left", b.error);
+  }
+  const bt = sticky(i, "t");
+  if (bt != null) {
+    let next = null;
+    for (let k = i + 1; k < beats.length; k++) if (beats[k].t != null) { next = beats[k].t; break; }
+    const cur = beats[i].t != null ? beats[i].t : bt;
+    const shown = next != null ? lerp(cur, next, clamp(lt / b.dur, 0, 1)) : cur;
+    const m = Math.floor(shown / 60), s = Math.floor(shown % 60);
+    const parts = [[`${m}:${String(s).padStart(2, "0")}`, false]];
+    parts.logo = true;
+    chip(W - 28, cy, parts, "right");
+  }
+  ctx.save();
+  const px0 = 28, pw = W - 56, py = H - 12;
+  ctx.fillStyle = LIGHT_BG ? "rgba(31,30,27,0.12)" : "rgba(255,255,255,0.1)";
+  ctx.fillRect(px0, py, pw, 2);
+  ctx.fillStyle = LIGHT_BG ? "rgba(31,30,27,0.5)" : "rgba(255,255,255,0.55)";
+  ctx.fillRect(px0, py, pw * (t / DURATION), 2);
+  ctx.restore();
+}
+
+function narrationState(i) {
+  for (let k = i; k >= 0; k--) {
+    if (beats[k].card) return null;
+    if (Object.prototype.hasOwnProperty.call(beats[k], "narration")) {
+      if (!beats[k].narration) return null;
+      return {
+        text: String(beats[k].narration),
+        index: k,
+        error: beats[k].narrationError ?? beats[k].error ?? false,
+      };
+    }
+  }
+  return null;
+}
+
+function captionState(i) {
+  const b = beats[i];
+  if (b.card) return null;
+  if (b.caption) return { text: b.caption, index: i, error: !!b.error };
+  return narrationState(i);
+}
+
+function drawCaptionPill(state, alpha, rise = 0) {
+  if (!state || alpha <= 0) return;
+  ctx.save();
+  ctx.globalAlpha = alpha;
+  let fs = 56;
+  ctx.font = `600 ${fs}px ${SANS}`;
+  while (ctx.measureText(state.text).width > W * 0.64 && fs > 44) {
+    fs -= 2; ctx.font = `600 ${fs}px ${SANS}`;
+  }
+  ctx.textAlign = "center"; ctx.textBaseline = "middle";
+  const ph = fs * 1.9;
+  const y = RAIL + rise;
+  const w = ctx.measureText(state.text).width;
+  ctx.save();
+  ctx.shadowColor = "rgba(0,0,0,0.4)"; ctx.shadowBlur = 24; ctx.shadowOffsetY = 6;
+  roundRect(W / 2 - w / 2 - 26, y - ph / 2, w + 52, ph, ph / 2);
+  ctx.fillStyle = state.error ? "rgba(52,10,14,0.9)" : "rgba(10,12,18,0.82)"; ctx.fill();
+  ctx.restore();
+  ctx.strokeStyle = state.error ? "rgba(255,90,90,0.55)" : "rgba(255,255,255,0.14)"; ctx.lineWidth = 1;
+  roundRect(W / 2 - w / 2 - 26, y - ph / 2, w + 52, ph, ph / 2); ctx.stroke();
+  ctx.fillStyle = state.error ? "#ffd7d7" : "#fff";
+  ctx.fillText(state.text, W / 2, y + 1);
+  ctx.restore();
+}
+
+function drawCaption(t, i) {
+  const state = captionState(i);
+  if (!state) return;
+  const elapsed = t - starts[state.index];
+  const k = REDUCED_MOTION ? 1 : easeOutQuart(clamp((elapsed - 0.04) / 0.22, 0, 1));
+  if (state.index === i && i > 0 && k < 1) {
+    const previous = captionState(i - 1);
+    if (previous && previous.text !== state.text)
+      drawCaptionPill(previous, 1 - k, -8 * k);
+  }
+  drawCaptionPill(state, k, 12 * (1 - k));
+}
+
+function drawCard(i, lt) {
+  const b = beats[i];
+  const last = i === beats.length - 1;
+  const aIn = easeOutCubic(clamp(lt / 0.35, 0, 1));
+  const aOut = last ? 1 : 1 - easeInOut(clamp((lt - (b.dur - 0.3)) / 0.3, 0, 1));
+  const a = Math.min(aIn, aOut);
+  ctx.save();
+  ctx.globalAlpha = a;
+  // Center each card's complete visual stack, not just its title. The intro is
+  // shorter than explanation/outcome cards, so it needs the larger offset.
+  const centerShift = b.kind === "intro" ? 154
+    : b.kind === "explanation" ? 106
+    : b.kind === "outcome" ? 116
+    : 0;
+  const rise = centerShift + (1 - aIn) * 16;
+  drawLogo(W / 2 - 40, 130 + rise, 80, INK, 1);
+  ctx.fillStyle = INK; ctx.textAlign = "center"; ctx.textBaseline = "middle";
+  let titleSize = 72;
+  ctx.font = `600 ${titleSize}px ${SANS}`;
+  while (ctx.measureText(b.title || "").width > W * 0.8 && titleSize > 52) {
+    titleSize -= 2; ctx.font = `600 ${titleSize}px ${SANS}`;
+  }
+  ctx.fillText(b.title || "", W / 2, 300 + rise);
+  if (b.sub) {
+    ctx.font = `500 25px ${MONO}`;
+    ctx.globalAlpha = a * 0.6; ctx.fillStyle = INK;
+    ctx.fillText(b.sub, W / 2, 386 + rise);
+    ctx.globalAlpha = a;
+  }
+  if (b.kind === "intro" && C.plan) {
+    const gap = 18, w = 430, h = 118;
+    const total = C.plan.length * w + (C.plan.length - 1) * gap;
+    let x = (W - total) / 2;
+    for (let n = 0; n < C.plan.length; n++) {
+      roundRect(x, 525 + rise, w, h, 20);
+      ctx.fillStyle = LIGHT_BG ? "rgba(255,255,255,0.62)" : "rgba(255,255,255,0.08)"; ctx.fill();
+      ctx.strokeStyle = LIGHT_BG ? "rgba(31,30,27,0.18)" : "rgba(255,255,255,0.14)"; ctx.stroke();
+      ctx.font = `700 20px ${MONO}`; ctx.textAlign = "left"; ctx.fillStyle = INK;
+      ctx.fillText(String(n + 1).padStart(2, "0"), x + 28, 559 + rise);
+      ctx.font = `600 26px ${SANS}`; ctx.fillText(C.plan[n], x + 28, 607 + rise);
+      x += w + gap;
+    }
+  }
+  if (b.kind === "explanation" && b.points) {
+    const firstReveal = 1.1;
+    const finalHold = 3.0;
+    const revealSpan = Math.max(0, b.dur - firstReveal - finalHold);
+    const revealGap = b.points.length > 1 ? revealSpan / (b.points.length - 1) : 0;
+    const current = Math.min(
+      b.points.length - 1,
+      Math.max(-1, Math.floor((lt - firstReveal) / Math.max(0.001, revealGap))),
+    );
+    let y = 505 + rise;
+    for (let n = 0; n < b.points.length; n++) {
+      const point = b.points[n];
+      const revealAt = firstReveal + n * revealGap;
+      const k = lt < revealAt ? 0 : REDUCED_MOTION ? 1 : easeOutQuart(clamp((lt - revealAt) / 0.28, 0, 1));
+      if (k <= 0) { y += 106; continue; }
+      const active = n === current;
+      const rowAlpha = active ? 1 : 0.56;
+      const slide = REDUCED_MOTION ? 0 : 14 * (1 - k);
+      ctx.textAlign = "left";
+      ctx.font = `700 18px ${MONO}`; ctx.globalAlpha = a * k * rowAlpha; ctx.fillStyle = INK;
+      const label = `${String(n + 1).padStart(2, "0")}  ${String(point.label || "").toUpperCase()}`;
+      ctx.fillText(label, 360 + slide, y);
+      ctx.font = `${active ? 650 : 560} 31px ${SANS}`;
+      ctx.fillText(point.text || "", 590 + slide, y);
+      y += 106;
+    }
+    ctx.globalAlpha = a;
+  }
+  if (b.kind === "outcome" && b.outcomes) {
+    let y = 515 + rise;
+    for (const outcome of b.outcomes) {
+      ctx.beginPath(); ctx.arc(520, y, 18, 0, 7); ctx.fillStyle = "#157f63"; ctx.fill();
+      ctx.fillStyle = "#fff"; ctx.font = `700 19px ${SANS}`; ctx.textAlign = "center"; ctx.fillText("✓", 520, y + 1);
+      ctx.textAlign = "left"; ctx.fillStyle = INK; ctx.font = `600 32px ${SANS}`;
+      ctx.fillText(outcome, 570, y);
+      y += 92;
+    }
+  }
+  ctx.restore();
+}
+
+function draw() {
+  if (!ready) return;
+  const t = clamp(playhead, 0, DURATION - 0.001);
+  const i = beatAt(t), lt = t - starts[i];
+  drawBackdrop();
+  if (beats[i].card) { drawCard(i, lt); drawHud(t, i); return; }
+  const cam = camera(t);
+  ctx.save();
+  // Stage inset: the camera's output maps to a slightly smaller rect so a
+  // margin of backdrop stays visible on every side at ANY zoom (Screen Studio
+  // keeps this breathing room; full-bleed content reads as a raw screencap).
+  ctx.translate(W / 2, H / 2); ctx.scale(STAGE, STAGE); ctx.translate(-W / 2, -H / 2);
+  ctx.translate(W / 2 + (cam.shake || 0), H / 2); ctx.scale(cam.s, cam.s); ctx.translate(-cam.x, -cam.y);
+  // Screen-Studio window entrance after a card
+  if (i === firstWindowBeat) {
+    const k = easeOutCubic(clamp(lt / 0.45, 0, 1));
+    const ws = 0.94 + 0.06 * k;
+    ctx.translate(W / 2, H / 2); ctx.scale(ws, ws); ctx.translate(-W / 2, -H / 2);
+    ctx.globalAlpha = 0.25 + 0.75 * k;
+  }
+  drawChromeWindow(i, lt);
+  drawContent(t, i, lt);
+  drawCursor(t, i, lt, cam);
+  ctx.restore();
+  ctx.globalAlpha = 1;
+  if (beats[i].errorMotion) {
+    const a = 0.12 * easeOutCubic(clamp(lt / 0.3, 0, 1));
+    const g = ctx.createRadialGradient(W/2, H/2, H * 0.42, W/2, H/2, H * 0.85);
+    g.addColorStop(0, "rgba(255,60,60,0)"); g.addColorStop(1, `rgba(255,50,50,${a})`);
+    ctx.fillStyle = g; ctx.fillRect(0, 0, W, H);
+  }
+  drawTelemetry(t, i, lt);
+  drawCaption(t, i, lt);
+  drawHud(t, i);
+}
+function drawHud(t, i) {
+  hud.textContent = `${t.toFixed(2)}s / ${DURATION.toFixed(2)}s  beat ${i + 1}/${beats.length}` +
+    (recorder ? "  ● EXPORTING" : playing ? "  ▶" : "  ⏸");
+}
+
+// ------------------------------ playback ------------------------------
+const hud = document.getElementById("hud");
+let playhead = 0, playing = false, rafT0 = 0, recorder = null;
+
+function tick(ts) {
+  if (playing) {
+    playhead = (ts - rafT0) / 1000;
+    if (playhead >= DURATION) {
+      playhead = DURATION; playing = false;
+      if (recorder) recorder.stop();
+    }
+  }
+  draw();
+  requestAnimationFrame(tick);
+}
+requestAnimationFrame(tick);
+
+window.seek = t => { playing = false; playhead = clamp(t, 0, DURATION); draw(); };
+window.play = (from = playhead >= DURATION ? 0 : playhead) => {
+  playhead = from; rafT0 = performance.now() - from * 1000; playing = true;
+};
+window.pause = () => { playing = false; };
+window.duration = () => DURATION;
+
+// Realtime export: plays once from 0 while MediaRecorder captures the canvas.
+// Keep this tab focused — rAF throttles in background tabs and stalls capture.
+window.exportVideo = (filename = "video.webm") => new Promise((resolve, reject) => {
+  if (preflightErrors.length) {
+    const message = `Export blocked: ${preflightErrors.join("; ")}`;
+    window.__exportError = message;
+    reject(new Error(message));
+    return;
+  }
+  const stream = canvas.captureStream(60);
+  const mime = ["video/webm;codecs=vp9", "video/webm;codecs=vp8", "video/webm"]
+    .find(m => MediaRecorder.isTypeSupported(m));
+  recorder = new MediaRecorder(stream, { mimeType: mime, videoBitsPerSecond: 14_000_000 });
+  const chunks = [];
+  recorder.ondataavailable = e => e.data.size && chunks.push(e.data);
+  recorder.onstop = () => {
+    recorder = null;
+    const blob = new Blob(chunks, { type: "video/webm" });
+    const a = document.createElement("a");
+    a.href = URL.createObjectURL(blob); a.download = filename; a.click();
+    window.__exported = filename;
+    resolve(filename);
+  };
+  recorder.start();
+  window.play(0);
+});
+
+document.addEventListener("keydown", e => {
+  if (e.key === " ") { e.preventDefault(); playing ? pause() : play(); }
+  if (e.key === "ArrowRight") seek(playhead + (e.shiftKey ? 1 : 0.1));
+  if (e.key === "ArrowLeft") seek(playhead - (e.shiftKey ? 1 : 0.1));
+  if (e.key === "e") exportVideo();
+});
+</script>
+</body>
+</html>

browser-harness/src/browser_harness/video.py

@@ -0,0 +1,749 @@
+#!/usr/bin/env python3
+"""Initialize, compile, review, and export browser-harness recordings."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import math
+import re
+import shutil
+from pathlib import Path
+from typing import Any
+
+TEMPLATE = Path(__file__).with_name("video-template.html")
+SOURCE_MANIFEST = "video-source.json"
+COMPOSITION_PREFIX = "window.COMPOSITION ="
+SENSITIVE = re.compile(
+    r"@|onmicrosoft\.com|(?:tenant|user|object)[_-]?id|"
+    r"\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b",
+    re.IGNORECASE,
+)
+ROUTE_UNSAFE = re.compile(
+    r"@|[?#]|://|onmicrosoft|(?:tenant|user|object)[_-]?id|"
+    r"\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b",
+    re.IGNORECASE,
+)
+OPAQUE_HEX = re.compile(r"^#[0-9a-f]{6}$", re.IGNORECASE)
+HOUSE_STYLE = {
+    "version": 1,
+    "frameStyle": "native",
+    "readingWpm": 380,
+    "background": ["#efece4", "#dce7e7"],
+    "cursorStart": {"x": 700, "y": 280},
+    "pacing": {
+        "captionBaseSeconds": 0.35,
+        "captionSecondsPerWord": 0.2,
+        "rawToCardHoldSeconds": 0.55,
+        "baseDurationBudget": 22,
+        "extraActionSeconds": 1.25,
+        "extraExplanationSeconds": 3,
+        "maximumDurationBudget": 32,
+    },
+    "motion": {
+        "autoFollow": True,
+        "autoZoom": 1.7,
+        "cursorDuration": 0.48,
+        "zoomDuration": 0.42,
+        "panDuration": 0.55,
+        "wideScale": 0.78,
+        "reactionLag": 0.025,
+        "reactionFade": 0.04,
+    },
+    "privacy": {"pad": 10, "mask": {"fill": "#ffffff", "stroke": False, "radius": 0}},
+}
+ACTION_KEYS = {
+    "event",
+    "frameEvent",
+    "afterEvent",
+    "chapter",
+    "route",
+    "afterRoute",
+    "narration",
+    "label",
+    "detour",
+    "error",
+    "context",
+    "showTyping",
+}
+BRIEF_KEYS = {
+    "task",
+    "summary",
+    "plan",
+    "actions",
+    "explanations",
+    "outcomeTitle",
+    "outcomeSummary",
+    "outcomes",
+    "privacy",
+}
+PRIVACY_KEYS = {"reviewedFrames", "redact"}
+EXPLANATION_KEYS = {
+    "afterAction",
+    "title",
+    "summary",
+    "observed",
+    "mistake",
+    "correction",
+}
+TYPE_HELPERS = {"type_text", "fill", "fill_input"}
+CLICK_HELPERS = {"click_at_xy"}
+REDACTION_KEYS = {"x", "y", "w", "h", "fill", "stroke", "radius", "pad"}
+VIEWPORT_TOLERANCE = 2
+
+
+class BriefError(ValueError):
+    """An edit brief violates the deliberately small authoring contract."""
+
+
+def load_json(path: Path) -> dict[str, Any]:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise BriefError(f"cannot read {path}: {exc}") from exc
+    if not isinstance(value, dict):
+        raise BriefError(f"{path} must contain a JSON object")
+    return value
+
+
+def file_hash(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def load_composition(path: Path) -> dict[str, Any]:
+    try:
+        text = path.read_text(encoding="utf-8").strip()
+    except OSError as exc:
+        raise BriefError(f"cannot read {path}: {exc}") from exc
+    if not text.startswith(COMPOSITION_PREFIX) or not text.endswith(";"):
+        raise BriefError(f"{path} is not a generated composition")
+    try:
+        value = json.loads(text[len(COMPOSITION_PREFIX) : -1].strip())
+    except json.JSONDecodeError as exc:
+        raise BriefError(f"cannot read {path}: {exc}") from exc
+    if not isinstance(value, dict):
+        raise BriefError(f"{path} must set a JSON object")
+    return value
+
+
+def used_frames(composition: dict[str, Any]) -> list[str]:
+    frames: list[str] = []
+    for beat in composition.get("beats") or []:
+        for key in ("frame", "after"):
+            frame = beat.get(key)
+            if frame and frame not in frames:
+                frames.append(str(frame))
+    return frames
+
+
+def source_files(recording: Path) -> list[Path]:
+    required = [recording / name for name in ("events.jsonl", "meta.json", "recording-summary.json")]
+    frames = sorted(path for path in recording.glob("*.jpg") if path.stem.isdigit())
+    return [path for path in required if path.is_file()] + frames
+
+
+def write_source_manifest(recording: Path) -> dict[str, Any]:
+    meta_path = recording / "meta.json"
+    meta = load_json(meta_path) if meta_path.is_file() else {}
+    files = source_files(recording)
+    manifest = {
+        "recording": recording.name,
+        "started": meta.get("started"),
+        "explicit": meta_path.is_file() and meta.get("auto") is not True,
+        "files": {path.name: file_hash(path) for path in files},
+    }
+    (recording / SOURCE_MANIFEST).write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
+    return manifest
+
+
+def verify_source_manifest(recording: Path) -> dict[str, Any]:
+    manifest = load_json(recording / SOURCE_MANIFEST)
+    if manifest.get("recording") != recording.name:
+        raise BriefError("recording directory does not match video-source.json")
+    expected = manifest.get("files")
+    if not isinstance(expected, dict):
+        raise BriefError("video-source.json has no source hashes")
+    paths = source_files(recording)
+    if {path.name for path in paths} != set(expected):
+        raise BriefError("recording source files changed after initialization")
+    for path in paths:
+        if expected.get(path.name) != file_hash(path):
+            raise BriefError(f"recording source changed after initialization: {path.name}")
+    return manifest
+
+
+def reject_unknown(value: dict[str, Any], allowed: set[str], where: str) -> None:
+    unknown = sorted(set(value) - allowed)
+    if unknown:
+        raise BriefError(f"{where} has unsupported field(s): {', '.join(unknown)}")
+
+
+def require_text(value: Any, where: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise BriefError(f"{where} must be non-empty text")
+    return value.strip()
+
+
+def require_text_list(value: Any, where: str, low: int, high: int) -> list[str]:
+    if not isinstance(value, list) or not low <= len(value) <= high:
+        raise BriefError(f"{where} must contain {low}–{high} items")
+    return [require_text(item, f"{where}[{index}]") for index, item in enumerate(value)]
+
+
+def words(value: Any) -> int:
+    return len(re.findall(r"\S+", str(value or "")))
+
+
+def card_duration(
+    title: str,
+    summary: str | None,
+    details: list[str],
+    kind: str,
+    reading_wpm: float,
+) -> float:
+    text = " ".join(part for part in (title, summary, *details) if part)
+    base = 4.5 if kind in {"intro", "outcome"} else 4.0
+    return round(max(base, 0.4 + words(text) * 60 / reading_wpm), 3)
+
+
+def validate_narration(value: Any, where: str) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise BriefError(f"{where} must be text")
+    if words(value) > 7:
+        raise BriefError(f"{where} exceeds seven words")
+    return value.strip()
+
+
+def optional_text(value: Any, where: str) -> str | None:
+    if value is None:
+        return None
+    return require_text(value, where)
+
+
+def event_at(events: list[dict[str, Any]], number: Any, where: str) -> dict[str, Any]:
+    if not isinstance(number, int) or isinstance(number, bool):
+        raise BriefError(f"{where} must be a one-based integer")
+    if number < 1 or number > len(events):
+        raise BriefError(f"{where} is outside recording-summary.json")
+    event = events[number - 1]
+    if not event.get("frame"):
+        raise BriefError(f"{where} has no captured frame")
+    return event
+
+
+def event_target(event: dict[str, Any]) -> dict[str, float] | None:
+    cursor = event.get("cursor")
+    if isinstance(cursor, dict) and cursor.get("x") is not None and cursor.get("y") is not None:
+        return {"x": float(cursor["x"]), "y": float(cursor["y"])}
+    box = event.get("box")
+    if isinstance(box, dict) and all(box.get(key) is not None for key in ("x", "y", "w", "h")):
+        return {
+            "x": float(box["x"]) + float(box["w"]) * 0.3,
+            "y": float(box["y"]) + float(box["h"]) / 2,
+        }
+    return None
+
+
+def require_matching_viewport(event: dict[str, Any], viewport: dict[str, Any], where: str) -> None:
+    candidate = event.get("viewport") or {}
+    try:
+        dw = abs(float(candidate["w"]) - float(viewport["w"]))
+        dh = abs(float(candidate["h"]) - float(viewport["h"]))
+    except (KeyError, TypeError, ValueError):
+        raise BriefError(f"{where} has no valid viewport") from None
+    if dw > VIEWPORT_TOLERANCE or dh > VIEWPORT_TOLERANCE:
+        raise BriefError(f"{where} uses a different viewport; split or normalize the recording first")
+
+
+def default_action_duration(beat: dict[str, Any], pacing: dict[str, Any]) -> float:
+    base = 0.7
+    if beat.get("click"):
+        base = 1.15
+    if beat.get("after"):
+        base = max(base, 1.4)
+    typing = beat.get("type")
+    if typing:
+        base = max(base, 0.6 + len(str(typing.get("text") or "")) * 0.035)
+    narration = beat.get("narration")
+    if narration:
+        base = max(
+            base,
+            float(pacing["captionBaseSeconds"])
+            + float(pacing["captionSecondsPerWord"]) * words(narration),
+        )
+    return round(base, 3)
+
+
+def duration_budget(
+    action_count: int,
+    explanation_count: int,
+    raw_to_card_count: int,
+    pacing: dict[str, Any],
+) -> float:
+    budget = float(pacing["baseDurationBudget"])
+    budget += max(0, action_count - 5) * float(pacing["extraActionSeconds"])
+    budget += max(0, explanation_count - 1) * float(
+        pacing["extraExplanationSeconds"]
+    )
+    budget += raw_to_card_count * float(pacing["rawToCardHoldSeconds"])
+    return round(min(budget, float(pacing["maximumDurationBudget"])), 3)
+
+
+def add_raw_to_card_holds(beats: list[dict[str, Any]], pacing: dict[str, Any]) -> int:
+    hold = float(pacing["rawToCardHoldSeconds"])
+    count = 0
+    for beat, next_beat in zip(beats, beats[1:]):
+        if beat.get("card") or not next_beat.get("card"):
+            continue
+        beat["endStateHold"] = hold
+        beat["dur"] = round(float(beat["dur"]) + hold, 3)
+        count += 1
+    return count
+
+
+def validate_narration_cadence(beats: list[dict[str, Any]]) -> None:
+    """Keep narration semantic and sticky instead of mirroring every frame."""
+
+    segments: list[list[dict[str, Any]]] = []
+    current: list[dict[str, Any]] = []
+    for beat in beats:
+        if beat.get("card"):
+            if current:
+                segments.append(current)
+                current = []
+        else:
+            current.append(beat)
+    if current:
+        segments.append(current)
+
+    for segment in segments:
+        cues = [beat for beat in segment if beat.get("narration")]
+        if len(segment) >= 3 and len(cues) > math.ceil(len(segment) / 2):
+            raise BriefError(
+                "narration is sticky: set it only when the thought changes, then "
+                "omit it while 2–3 screenshots advance underneath"
+            )
+        consecutive = 0
+        for beat in segment:
+            consecutive = consecutive + 1 if beat.get("narration") else 0
+            if consecutive >= 3:
+                raise BriefError(
+                    "three consecutive actions change narration; omit narration on "
+                    "intervening actions so text and screenshots use different pacing"
+                )
+
+
+def compile_action(
+    action: dict[str, Any],
+    index: int,
+    events: list[dict[str, Any]],
+    plan: list[str],
+    first_ts: float,
+    previous_target: dict[str, float] | None,
+    viewport: dict[str, float],
+    pacing: dict[str, Any],
+    revealed_text: dict[int, str],
+) -> tuple[dict[str, Any], dict[str, float] | None]:
+    if not isinstance(action, dict):
+        raise BriefError(f"actions[{index}] must be an object")
+    reject_unknown(action, ACTION_KEYS, f"actions[{index}]")
+    if "showTyping" in action and not isinstance(action["showTyping"], bool):
+        raise BriefError(f"actions[{index}].showTyping must be true or false")
+    event = event_at(events, action.get("event"), f"actions[{index}].event")
+    require_matching_viewport(event, viewport, f"actions[{index}].event")
+    frame_event = event
+    if action.get("frameEvent") is not None:
+        frame_event = event_at(
+            events, action["frameEvent"], f"actions[{index}].frameEvent"
+        )
+        require_matching_viewport(frame_event, viewport, f"actions[{index}].frameEvent")
+    chapter = action.get("chapter")
+    if not isinstance(chapter, int) or isinstance(chapter, bool) or not 0 <= chapter < len(plan):
+        raise BriefError(f"actions[{index}].chapter must index plan")
+    route = require_text(action.get("route"), f"actions[{index}].route")
+    if ROUTE_UNSAFE.search(route):
+        raise BriefError(f"actions[{index}].route must be semantic, not a raw URL or identity")
+
+    beat: dict[str, Any] = {
+        "frame": frame_event["frame"],
+        "route": route,
+        "chapter": chapter,
+    }
+    after_number = action.get("afterEvent")
+    if after_number is not None:
+        after = event_at(events, after_number, f"actions[{index}].afterEvent")
+        require_matching_viewport(after, viewport, f"actions[{index}].afterEvent")
+        beat["after"] = after["frame"]
+        after_route = action.get("afterRoute")
+        if after_route is not None:
+            after_route = require_text(after_route, f"actions[{index}].afterRoute")
+            if ROUTE_UNSAFE.search(after_route):
+                raise BriefError(f"actions[{index}].afterRoute must be semantic")
+            beat["afterRoute"] = after_route
+
+    narration = validate_narration(action.get("narration"), f"actions[{index}].narration")
+    if narration is not None:
+        beat["narration"] = narration
+    if action.get("label") is not None:
+        beat["label"] = require_text(action["label"], f"actions[{index}].label")
+    if action.get("detour") is True:
+        beat["detour"] = True
+    if action.get("error") is True:
+        beat["error"] = True
+
+    helper = str(event.get("helper") or "")
+    cursor = event.get("cursor")
+    if helper in CLICK_HELPERS:
+        if not isinstance(cursor, dict) or cursor.get("x") is None or cursor.get("y") is None:
+            raise BriefError(f"actions[{index}] identifies a click without captured coordinates")
+        beat["cursor"] = {"x": cursor["x"], "y": cursor["y"]}
+        beat["click"] = True
+    elif helper in TYPE_HELPERS:
+        box = event.get("box")
+        if not isinstance(box, dict) or not all(box.get(key) is not None for key in ("x", "y", "w", "h")):
+            raise BriefError(f"actions[{index}] identifies typing without a captured box")
+        show_typing = action.get("showTyping") is True
+        if show_typing and event.get("password"):
+            raise BriefError(f"actions[{index}].showTyping cannot reveal a password field")
+        source_line = event.get("sourceLine")
+        if show_typing and source_line not in revealed_text:
+            raise BriefError(f"actions[{index}].showTyping requires the original typed event")
+        beat["type"] = {
+            "box": {key: box[key] for key in ("x", "y", "w", "h")},
+            "text": revealed_text[source_line] if show_typing else "••••••",
+            **({} if show_typing else {"redact": True}),
+        }
+    elif action.get("showTyping") is not None:
+        raise BriefError(f"actions[{index}].showTyping requires a typing event")
+
+    target = event_target(event)
+    if action.get("context") is True and not (beat.get("click") or beat.get("type")):
+        beat["wide"] = True
+    elif target and previous_target:
+        distance = math.hypot(target["x"] - previous_target["x"], target["y"] - previous_target["y"])
+        diagonal = math.hypot(float(viewport["w"]), float(viewport["h"]))
+        if distance > diagonal * 0.58:
+            beat["cameraCut"] = True
+
+    ts = event.get("ts")
+    if isinstance(ts, (int, float)):
+        beat["t"] = round(max(0.0, float(ts) - first_ts), 3)
+    beat["dur"] = default_action_duration(beat, pacing)
+    return beat, target or previous_target
+
+
+def validate_privacy(reviewed: list[str], redact: dict[str, Any], composition: dict[str, Any]) -> None:
+    frames = used_frames(composition)
+    for frame in (*frames, *reviewed, *redact):
+        if Path(frame).name != frame or not frame.lower().endswith(".jpg"):
+            raise BriefError(f"invalid frame name: {frame}")
+    if len(reviewed) != len(set(reviewed)):
+        raise BriefError("privacy.reviewedFrames contains duplicates")
+    missing = [frame for frame in frames if frame not in reviewed]
+    if missing:
+        raise BriefError("privacy review missing: " + ", ".join(missing))
+    unknown = sorted(set(redact) - set(frames))
+    if unknown:
+        raise BriefError("privacy.redact lists unused frames: " + ", ".join(unknown))
+    for frame, rectangles in redact.items():
+        if not isinstance(rectangles, list):
+            raise BriefError(f"privacy.redact.{frame} must be a list")
+        for index, rectangle in enumerate(rectangles):
+            where = f"privacy.redact.{frame}[{index}]"
+            if not isinstance(rectangle, dict):
+                raise BriefError(f"{where} must be an object")
+            reject_unknown(rectangle, REDACTION_KEYS, where)
+            for key in ("x", "y", "w", "h"):
+                value = rectangle.get(key)
+                if not isinstance(value, (int, float)) or isinstance(value, bool) or not math.isfinite(value):
+                    raise BriefError(f"{where}.{key} must be a finite number")
+            if rectangle["w"] <= 0 or rectangle["h"] <= 0:
+                raise BriefError(f"{where} must have positive width and height")
+            for key in ("fill", "stroke"):
+                value = rectangle.get(key)
+                if value is not None and value is not False and (
+                    not isinstance(value, str) or not OPAQUE_HEX.fullmatch(value)
+                ):
+                    raise BriefError(f"{where}.{key} must be false or opaque six-digit hex")
+
+
+def compile_brief(summary: dict[str, Any], brief: dict[str, Any], style: dict[str, Any], revealed_text: dict[int, str] | None = None) -> dict[str, Any]:
+    reject_unknown(brief, BRIEF_KEYS, "edit brief")
+    task = require_text(brief.get("task"), "task")
+    summary_text = optional_text(brief.get("summary"), "summary")
+    plan = require_text_list(brief.get("plan"), "plan", 2, 5)
+    outcomes = require_text_list(brief.get("outcomes"), "outcomes", 1, 5)
+    actions = brief.get("actions")
+    if not isinstance(actions, list) or not actions:
+        raise BriefError("actions must contain at least one action")
+    events = summary.get("events")
+    if not isinstance(events, list) or not events:
+        raise BriefError("recording-summary.json has no events")
+    first_action = actions[0]
+    if not isinstance(first_action, dict):
+        raise BriefError("actions[0] must be an object")
+    viewport_event = event_at(
+        events,
+        first_action.get("frameEvent", first_action.get("event")),
+        "actions[0].frameEvent" if "frameEvent" in first_action else "actions[0].event",
+    )
+    if not (viewport_event.get("viewport") or {}).get("w") or not (viewport_event.get("viewport") or {}).get("h"):
+        raise BriefError("recording-summary.json has no viewport")
+    viewport = viewport_event["viewport"]
+    first_ts = next(
+        (float(event["ts"]) for event in events if isinstance(event.get("ts"), (int, float))),
+        0.0,
+    )
+
+    privacy = brief.get("privacy")
+    if not isinstance(privacy, dict):
+        raise BriefError("privacy must be an object")
+    reject_unknown(privacy, PRIVACY_KEYS, "privacy")
+    reviewed = privacy.get("reviewedFrames")
+    if not isinstance(reviewed, list) or not all(isinstance(frame, str) for frame in reviewed):
+        raise BriefError("privacy.reviewedFrames must be a list of frame names")
+    redact = privacy.get("redact") or {}
+    if not isinstance(redact, dict):
+        raise BriefError("privacy.redact must be an object")
+
+    explanations = brief.get("explanations") or []
+    if not isinstance(explanations, list):
+        raise BriefError("explanations must be a list")
+    pacing = style["pacing"]
+    reading_wpm = float(style["readingWpm"])
+    explanation_by_action: dict[int, list[dict[str, Any]]] = {}
+    revealed_text = revealed_text or {}
+    for index, explanation in enumerate(explanations):
+        if not isinstance(explanation, dict):
+            raise BriefError(f"explanations[{index}] must be an object")
+        reject_unknown(explanation, EXPLANATION_KEYS, f"explanations[{index}]")
+        after_action = explanation.get("afterAction")
+        if not isinstance(after_action, int) or isinstance(after_action, bool) or not 1 <= after_action <= len(actions):
+            raise BriefError(f"explanations[{index}].afterAction must index actions")
+        title = require_text(explanation.get("title"), f"explanations[{index}].title")
+        sub = optional_text(explanation.get("summary"), f"explanations[{index}].summary")
+        points = [
+            {"label": "Observed", "text": require_text(explanation.get("observed"), f"explanations[{index}].observed")},
+            {"label": "Mistake", "text": require_text(explanation.get("mistake"), f"explanations[{index}].mistake")},
+            {"label": "Correction", "text": require_text(explanation.get("correction"), f"explanations[{index}].correction")},
+        ]
+        card = {
+            "card": True,
+            "kind": "explanation",
+            "title": title,
+            **({"sub": sub} if sub is not None else {}),
+            "points": points,
+            "dur": card_duration(
+                title,
+                sub,
+                [part for point in points for part in (point["label"], point["text"])],
+                "explanation",
+                reading_wpm,
+            ),
+        }
+        explanation_by_action.setdefault(after_action, []).append(card)
+
+    intro = {
+        "card": True,
+        "kind": "intro",
+        "title": task,
+        **({"sub": summary_text} if summary_text is not None else {}),
+        "dur": card_duration(task, summary_text, plan, "intro", reading_wpm),
+    }
+    beats: list[dict[str, Any]] = [intro]
+    previous_target = None
+    for index, action in enumerate(actions):
+        beat, previous_target = compile_action(
+            action, index, events, plan, first_ts, previous_target, viewport, pacing, revealed_text
+        )
+        beats.append(beat)
+        beats.extend(explanation_by_action.get(index + 1, []))
+
+    outcome_title = require_text(brief.get("outcomeTitle") or "Task complete", "outcomeTitle")
+    outcome_summary = optional_text(brief.get("outcomeSummary"), "outcomeSummary")
+    beats.append(
+        {
+            "card": True,
+            "kind": "outcome",
+            "title": outcome_title,
+            **({"sub": outcome_summary} if outcome_summary is not None else {}),
+            "outcomes": outcomes,
+            "dur": card_duration(
+                outcome_title, outcome_summary, outcomes, "outcome", reading_wpm
+            ),
+        }
+    )
+
+    validate_narration_cadence(beats)
+    raw_to_card_count = add_raw_to_card_holds(beats, pacing)
+    budget = duration_budget(
+        len(actions), len(explanations), raw_to_card_count, pacing
+    )
+    duration = round(sum(float(beat["dur"]) for beat in beats), 3)
+    if duration > budget + 0.001:
+        raise BriefError(
+            f"compiled video is {duration:.1f}s; house-style budget is "
+            f"{budget:.1f}s. Shorten card copy, remove redundant actions, or set "
+            "narration only when the thought changes; viewers can pause for detail"
+        )
+
+    house_privacy = style["privacy"]
+    composition = {
+        "schemaVersion": style["version"],
+        "viewport": {"w": viewport["w"], "h": viewport["h"]},
+        "cursorStart": style["cursorStart"],
+        "frameStyle": style["frameStyle"],
+        "readingWpm": style["readingWpm"],
+        "pacing": pacing,
+        "durationBudget": budget,
+        "bg": style["background"],
+        "plan": plan,
+        "motion": style["motion"],
+        "privacy": {
+            "reviewedFrames": reviewed,
+            "pad": house_privacy["pad"],
+            "mask": house_privacy["mask"],
+        },
+        "redact": redact,
+        "beats": beats,
+    }
+    validate_privacy(reviewed, redact, composition)
+    return composition
+
+
+def write_composition(path: Path, composition: dict[str, Any]) -> None:
+    body = json.dumps(composition, indent=2, ensure_ascii=False)
+    path.write_text(f"window.COMPOSITION = {body};\n", encoding="utf-8")
+
+
+def load_revealed_text(events_path: Path) -> dict[int, str]:
+    revealed: dict[int, str] = {}
+    try:
+        lines = events_path.read_text(encoding="utf-8").splitlines()
+    except OSError as exc:
+        raise BriefError(f"cannot read {events_path}: {exc}") from exc
+    for source_line, line in enumerate(lines, 1):
+        if not line.strip():
+            continue
+        try:
+            event = json.loads(line)
+        except json.JSONDecodeError as exc:
+            raise BriefError(f"cannot read {events_path}: {exc}") from exc
+        if event.get("helper") in TYPE_HELPERS and event.get("input") != "password":
+            text = event.get("text")
+            if text is not None:
+                revealed[source_line] = str(text)
+    return revealed
+
+
+def safe_text(event: dict[str, Any]) -> str | None:
+    value = event.get("text")
+    if value is None:
+        return None
+    if event.get("helper") in TYPE_HELPERS:
+        return "<typed text hidden>"
+    value = str(value)
+    if event.get("input") == "password" or SENSITIVE.search(value):
+        return "<sensitive>"
+    return value[:120]
+
+
+def safe_label(value: object) -> str | None:
+    if value is None:
+        return None
+    value = str(value)
+    return "<sensitive>" if SENSITIVE.search(value) else value[:120]
+
+
+def init_recording(recording: Path, require_explicit: bool = False) -> int:
+    events_path = recording / "events.jsonl"
+    if not events_path.is_file():
+        raise BriefError(f"missing {events_path}")
+    meta_path = recording / "meta.json"
+    meta = load_json(meta_path) if meta_path.is_file() else {}
+    if require_explicit and (not meta_path.is_file() or meta.get("auto") is True):
+        raise BriefError("not an explicit recording; use the exact path returned by start_recording()")
+
+    shutil.copy2(TEMPLATE, recording / "video.html")
+    events = []
+    for source_line, line in enumerate(events_path.read_text(encoding="utf-8").splitlines(), 1):
+        if not line.strip():
+            continue
+        try:
+            raw = json.loads(line)
+        except json.JSONDecodeError as exc:
+            raise BriefError(f"cannot read {events_path}: {exc}") from exc
+        if not raw.get("frame"):
+            continue
+        events.append(
+            {
+                "frame": raw["frame"],
+                "sourceLine": source_line,
+                "helper": raw.get("helper"),
+                "ts": raw.get("ts"),
+                "route": "Browser",
+                "tab": safe_label(raw.get("title")),
+                "viewport": {"w": raw.get("w"), "h": raw.get("h")},
+                "cursor": (
+                    {"x": raw.get("x"), "y": raw.get("y")}
+                    if raw.get("x") is not None and raw.get("y") is not None
+                    else None
+                ),
+                "box": raw.get("box"),
+                "text": safe_text(raw),
+                "textLength": len(str(raw.get("text") or "")),
+                "password": raw.get("input") == "password",
+            }
+        )
+
+    summary = {
+        "recording": recording.name,
+        "title": safe_label(meta.get("title")),
+        "eventCount": len(events),
+        "events": events,
+    }
+    output = recording / "recording-summary.json"
+    output.write_text(json.dumps(summary, indent=2) + "\n", encoding="utf-8")
+    write_source_manifest(recording)
+    print(f"summary: {output}")
+    print(f"next: write {recording / 'edit-brief.json'}, then run browser-harness video review")
+    return 0
+
+
+def run_cli(args: list[str]) -> int:
+    parser = argparse.ArgumentParser(prog="browser-harness video")
+    sub = parser.add_subparsers(dest="command", required=True)
+    init = sub.add_parser("init", help="prepare a recording for editing")
+    init.add_argument("recording", type=Path)
+    init.add_argument("--require-explicit", action="store_true")
+    review = sub.add_parser("review", help="compile and generate a review sheet")
+    review.add_argument("recording", type=Path)
+    export = sub.add_parser("export", help="export a reviewed MP4")
+    export.add_argument("recording", type=Path)
+    export.add_argument("--output", default="video.mp4")
+    export.add_argument("--reviewed", action="store_true")
+    parsed = parser.parse_args(args)
+    recording = parsed.recording.expanduser().resolve()
+    try:
+        if parsed.command == "init":
+            return init_recording(recording, parsed.require_explicit)
+        from . import video_render
+
+        if parsed.command == "review":
+            return video_render.review(recording)
+        return video_render.export(recording, parsed.output, parsed.reviewed)
+    except (OSError, ValueError, RuntimeError) as exc:
+        parser.error(str(exc))
+
+
+def main() -> int:
+    import sys
+
+    return run_cli(sys.argv[1:])
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

browser-harness/src/browser_harness/video_render.py

@@ -0,0 +1,523 @@
+#!/usr/bin/env python3
+"""Prepare compact renderer review sheets, then export and verify an MP4."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import math
+import os
+import shutil
+import subprocess
+import sys
+import threading
+import time
+from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+
+from PIL import Image, ImageDraw, ImageFont, ImageOps
+
+from . import video
+
+
+TEMPLATE = Path(__file__).with_name("video-template.html")
+MARKER = "__BH_VIDEO_RESULT__="
+REVIEW_ARTIFACTS = {
+    "composition.js",
+    "recording-summary.json",
+    "edit-brief.json",
+    video.SOURCE_MANIFEST,
+    "video.html",
+}
+OBSOLETE_REVIEW_FILES = {
+    "privacy-contact-sheet.jpg",
+    "renderer-normal-contact-sheet.jpg",
+    "renderer-reduced-contact-sheet.jpg",
+    "renderer-click-contact-sheet.jpg",
+    "video-audit.json",
+}
+
+
+def load_composition(recording: Path) -> dict:
+    return video.load_composition(recording / "composition.js")
+
+
+def compile_recording(recording: Path, write: bool) -> dict:
+    video.verify_source_manifest(recording)
+    summary = video.load_json(recording / "recording-summary.json")
+    brief = video.load_json(recording / "edit-brief.json")
+    composition = video.compile_brief(
+        summary, brief, video.HOUSE_STYLE, video.load_revealed_text(recording / "events.jsonl")
+    )
+    if write:
+        video.write_composition(recording / "composition.js", composition)
+    return composition
+
+
+def review_samples(comp: dict) -> list[dict]:
+    """One stable state per beat, plus every explanation reveal."""
+    samples = []
+    start = 0.0
+    for index, beat in enumerate(comp.get("beats") or [], 1):
+        duration = float(beat.get("dur") or 0)
+        if beat.get("kind") == "explanation" and beat.get("points"):
+            points = beat["points"]
+            first, final_hold = 1.1, 3.0
+            span = max(0.0, duration - first - final_hold)
+            gap = span / max(1, len(points) - 1)
+            for point_index, point in enumerate(points, 1):
+                local = min(max(0.05, duration - 0.05), first + (point_index - 1) * gap + 0.2)
+                samples.append({
+                    "time": round(start + local, 3),
+                    "label": f"beat {index} · {point.get('label') or point_index}",
+                })
+        else:
+            local = min(max(0.05, duration - 0.05), 1.0 if beat.get("card") else max(0.12, min(0.5, duration / 2)))
+            samples.append({"time": round(start + local, 3), "label": f"beat {index}"})
+        start += duration
+    return samples
+
+
+class _QuietHandler(SimpleHTTPRequestHandler):
+    def log_message(self, _format, *_args):
+        pass
+
+
+@contextlib.contextmanager
+def serve(recording: Path):
+    handler = lambda *args, **kwargs: _QuietHandler(  # noqa: E731
+        *args, directory=str(recording), **kwargs
+    )
+    server = ThreadingHTTPServer(("127.0.0.1", 0), handler)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    try:
+        yield f"http://127.0.0.1:{server.server_port}/video.html"
+    finally:
+        server.shutdown()
+        server.server_close()
+        thread.join(timeout=2)
+
+
+def _harness_command() -> list[str]:
+    return [sys.executable, "-m", "browser_harness.run"]
+
+
+def run_harness(code: str, timeout: float = 60) -> dict:
+    env = {**os.environ, "BH_RECORD": "0"}
+    proc = subprocess.run(
+        _harness_command(),
+        input=code,
+        text=True,
+        capture_output=True,
+        env=env,
+        timeout=timeout,
+        check=False,
+    )
+    if proc.returncode:
+        detail = (proc.stderr or proc.stdout).strip()
+        raise RuntimeError(f"browser review failed: {detail}")
+    for line in reversed(proc.stdout.splitlines()):
+        if line.startswith(MARKER):
+            return json.loads(line[len(MARKER):])
+    raise RuntimeError(f"browser review returned no result: {proc.stdout[-1000:]}")
+
+
+def _review_browser(recording: Path, url: str, samples: list[dict]) -> dict:
+    review_dir = recording / ".renderer-review"
+    payload = {
+        "url": url,
+        "samples": samples,
+        "reviewDir": str(review_dir),
+        "marker": MARKER,
+    }
+    code = f"""
+import json, os, time
+cfg = json.loads({json.dumps(json.dumps(payload))})
+os.makedirs(cfg['reviewDir'], exist_ok=True)
+
+def ready():
+    for _ in range(100):
+        if js('window.videoReady && window.videoReady()'):
+            return
+        time.sleep(0.05)
+    raise RuntimeError('video assets did not become ready')
+
+def inspect_mode(name, reduced):
+    features = [{{'name':'prefers-reduced-motion','value':'reduce'}}] if reduced else []
+    cdp('Emulation.setEmulatedMedia', media='', features=features)
+    cdp('Page.reload', ignoreCache=True)
+    wait_for_load()
+    ready()
+    preflight = js('window.videoPreflight()')
+    clicks = js('window.clickVisibility()')
+    captures = []
+    for index, sample in enumerate(cfg['samples'], 1):
+        js(f"window.seek({{sample['time']}})")
+        path = f"{{cfg['reviewDir']}}/{{name}}-beat-{{index:02d}}.png"
+        capture_screenshot(path)
+        captures.append({{'path': path, 'time': sample['time'], 'label': sample['label']}})
+    click_captures = []
+    for index, click in enumerate(clicks, 1):
+        for state, key in (('click', 'time'), ('result', 'resultTime')):
+            js(f"window.seek({{click[key]}})")
+            path = f"{{cfg['reviewDir']}}/{{name}}-click-{{index:02d}}-{{state}}.png"
+            capture_screenshot(path)
+            click_captures.append({{
+                'path': path, 'time': click[key],
+                'label': f"beat {{click['beat']}} · {{state}}",
+            }})
+    return {{'preflight': preflight, 'clicks': clicks, 'captures': captures,
+            'clickCaptures': click_captures}}
+
+try:
+    previous = current_tab()['targetId']
+except Exception:
+    previous = None
+target = None
+try:
+    target = new_tab()
+    goto_url(cfg['url'])
+    wait_for_load()
+    ready()
+    normal = inspect_mode('normal', False)
+    reduced = inspect_mode('reduced', True)
+    print(cfg['marker'] + json.dumps({{'normal': normal, 'reduced': reduced}}))
+finally:
+    try:
+        cdp('Emulation.setEmulatedMedia', media='', features=[])
+    except Exception:
+        pass
+    try:
+        switch_tab(previous) if previous else new_tab()
+    except Exception:
+        try:
+            new_tab()
+        except Exception:
+            pass
+    if target is not None:
+        try:
+            close_tab(target)
+        except Exception:
+            pass
+"""
+    return run_harness(code, timeout=max(60, len(samples) * 3))
+
+
+def contact_sheet(captures: list[dict], output: Path, title: str) -> None:
+    cols, tile_w, tile_h, label_h, gap, banner = 4, 400, 225, 34, 8, 42
+    rows = max(1, math.ceil(len(captures) / cols))
+    sheet = Image.new(
+        "RGB",
+        (cols * tile_w + (cols + 1) * gap, banner + rows * (tile_h + label_h + gap) + gap),
+        "#171a20",
+    )
+    draw, font = ImageDraw.Draw(sheet), ImageFont.load_default()
+    draw.text((gap, 15), title, fill="#ffffff", font=font)
+    for index, capture in enumerate(captures):
+        image = Image.open(capture["path"]).convert("RGB")
+        preview = ImageOps.contain(image, (tile_w, tile_h), Image.Resampling.LANCZOS)
+        col, row = index % cols, index // cols
+        x, y = gap + col * (tile_w + gap), banner + gap + row * (tile_h + label_h + gap)
+        sheet.paste(preview, (x + (tile_w - preview.width) // 2, y))
+        label = f"{capture['label']}  {float(capture['time']):.2f}s"
+        draw.text((x, y + tile_h + 9), label, fill="#d7dbe3", font=font)
+    sheet.save(output, quality=91)
+
+
+def masked_frame(recording: Path, comp: dict, frame: str) -> Image.Image:
+    viewport = comp["viewport"]
+    vw, vh = float(viewport["w"]), float(viewport["h"])
+    redactions = comp.get("redact") or {}
+    privacy = comp.get("privacy") or {}
+    mask = privacy.get("mask") or {}
+    pad = float(privacy.get("pad") or 8)
+    image = Image.open(recording / frame).convert("RGB")
+    sx, sy = image.width / vw, image.height / vh
+    draw = ImageDraw.Draw(image)
+    for rectangle in redactions.get(frame, []):
+        rect_pad = float(rectangle.get("pad", pad))
+        x0 = max(0, (float(rectangle["x"]) - rect_pad) * sx)
+        y0 = max(0, (float(rectangle["y"]) - rect_pad) * sy)
+        x1 = min(image.width, (float(rectangle["x"]) + float(rectangle["w"]) + rect_pad) * sx)
+        y1 = min(image.height, (float(rectangle["y"]) + float(rectangle["h"]) + rect_pad) * sy)
+        fill = rectangle.get("fill", mask.get("fill", "#f2f4f7"))
+        stroke = rectangle.get("stroke", mask.get("stroke", "#e2e7ec"))
+        radius = float(rectangle.get("radius", mask.get("radius", 7))) * min(sx, sy)
+        draw.rounded_rectangle(
+            (x0, y0, x1, y1), radius=radius, fill=fill,
+            outline=stroke or None, width=max(1, round(min(sx, sy))),
+        )
+    return image
+
+
+def privacy_review(recording: Path, comp: dict) -> tuple[Path, list[dict]]:
+    review_dir = recording / ".privacy-review"
+    review_dir.mkdir(exist_ok=True)
+    for stale in review_dir.glob("*.jpg"):
+        stale.unlink()
+    captures = []
+    redactions = comp.get("redact") or {}
+    for frame in video.used_frames(comp):
+        source = recording / frame
+        if not source.is_file():
+            raise RuntimeError(f"missing frame: {frame}")
+        output = review_dir / frame
+        masked_frame(recording, comp, frame).save(output, quality=94)
+        captures.append(
+            {
+                "path": str(output),
+                "time": 0,
+                "label": f"privacy · {frame} · masks:{len(redactions.get(frame, []))}",
+            }
+        )
+    return review_dir, captures
+
+
+def review(recording: Path) -> int:
+    started = time.monotonic()
+    for name in OBSOLETE_REVIEW_FILES:
+        (recording / name).unlink(missing_ok=True)
+    comp = compile_recording(recording, write=True)
+    shutil.copy2(TEMPLATE, recording / "video.html")
+    privacy_dir, privacy_captures = privacy_review(recording, comp)
+    samples = review_samples(comp)
+    review_dir = recording / ".renderer-review"
+    review_dir.mkdir(exist_ok=True)
+    for stale in review_dir.glob("*.png"):
+        stale.unlink()
+    with serve(recording) as url:
+        result = _review_browser(recording, url, samples)
+
+    errors = []
+    warnings = []
+    all_captures = list(privacy_captures)
+    for mode in ("normal", "reduced"):
+        errors.extend(f"{mode}: {error}" for error in result[mode]["preflight"].get("errors", []))
+        warnings.extend(
+            f"{mode}: {warning}"
+            for warning in result[mode]["preflight"].get("warnings", [])
+        )
+        errors.extend(
+            f"{mode}: beat {click['beat']} click is outside the safe viewport"
+            for click in result[mode]["clicks"] if not click.get("visible")
+        )
+        for capture in result[mode]["captures"]:
+            all_captures.append({**capture, "label": f"{mode} · {capture['label']}"})
+        for capture in result[mode]["clickCaptures"]:
+            all_captures.append({**capture, "label": f"{mode} · {capture['label']}"})
+
+    sheet = recording / "video-review-contact-sheet.jpg"
+    contact_sheet(all_captures, sheet, "PRIVACY · EVERY BEAT · EXACT CLICK + RESULT")
+
+    report = {
+        "errors": errors,
+        "warnings": warnings,
+        "duration": round(sum(float(beat.get("dur") or 0) for beat in comp.get("beats") or []), 3),
+        "artifactHashes": {
+            name: video.file_hash(recording / name) for name in sorted(REVIEW_ARTIFACTS)
+        },
+        "normal": result["normal"],
+        "reduced": result["reduced"],
+        "contactSheet": str(sheet),
+        "privacyReviewDir": str(privacy_dir),
+        "elapsedSeconds": round(time.monotonic() - started, 3),
+    }
+    report_path = recording / "renderer-review.json"
+    report_path.write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8")
+    print(f"review sheet: {sheet}")
+    print(f"full-resolution privacy review: {privacy_dir}")
+    print(f"renderer review: {len(errors)} error(s) in {report['elapsedSeconds']:.1f}s")
+    return 1 if errors else 0
+
+
+def _start_export(recording: Path, url: str, webm: Path) -> dict:
+    payload = {"url": url, "downloadPath": str(recording), "filename": webm.name, "marker": MARKER}
+    filename_js = json.dumps(webm.name)
+    code = f"""
+import json, time
+cfg = json.loads({json.dumps(json.dumps(payload))})
+try:
+    previous = current_tab()['targetId']
+except Exception:
+    previous = None
+target = new_tab()
+goto_url(cfg['url'])
+wait_for_load()
+for _ in range(100):
+    if js('window.videoReady && window.videoReady()'):
+        break
+    time.sleep(0.05)
+else:
+    raise RuntimeError('video assets did not become ready')
+preflight = js('window.videoPreflight()')
+clicks = js('window.clickVisibility()')
+cdp('Browser.setDownloadBehavior', behavior='allow', downloadPath=cfg['downloadPath'], eventsEnabled=True)
+cdp('Page.bringToFront')
+started = js('''(() => {{
+  window.__exported = null; window.__exportError = null;
+  window.exportVideo({filename_js})
+    .catch(error => window.__exportError = String(error));
+  return true;
+}})()''')
+print(cfg['marker'] + json.dumps({{'target': target, 'previous': previous, 'preflight': preflight, 'clicks': clicks, 'started': started}}))
+"""
+    return run_harness(code, timeout=30)
+
+
+def _close_editor(url: str, previous: str | None = None) -> bool:
+    payload = {"url": url, "previous": previous, "marker": MARKER}
+    code = f"""
+import json
+cfg = json.loads({json.dumps(json.dumps(payload))})
+downloads_reset = True
+try:
+    cdp('Browser.setDownloadBehavior', behavior='default', eventsEnabled=False)
+except Exception:
+    downloads_reset = False
+targets = [tab for tab in list_tabs() if tab.get('url') == cfg['url']]
+try:
+    switch_tab(cfg['previous']) if cfg.get('previous') else new_tab()
+except Exception:
+    new_tab()
+for tab in targets:
+    try:
+        close_tab(tab)
+    except Exception:
+        pass
+print(cfg['marker'] + json.dumps({{'closed': True, 'downloadsReset': downloads_reset}}))
+"""
+    try:
+        result = run_harness(code, timeout=15)
+    except Exception:
+        return False
+    return result.get("downloadsReset") is True
+
+
+def _run(command: list[str], cwd: Path, timeout: float = 120) -> subprocess.CompletedProcess:
+    proc = subprocess.run(command, cwd=cwd, text=True, capture_output=True, timeout=timeout, check=False)
+    if proc.returncode:
+        raise RuntimeError((proc.stderr or proc.stdout).strip())
+    return proc
+
+
+def _probe(path: Path) -> dict:
+    proc = _run([
+        "ffprobe", "-v", "error", "-show_entries",
+        "format=duration,size:stream=codec_name,width,height,pix_fmt,r_frame_rate",
+        "-of", "json", str(path),
+    ], path.parent)
+    return json.loads(proc.stdout)
+
+
+def export(recording: Path, output_name: str, reviewed: bool) -> int:
+    if not reviewed:
+        raise RuntimeError("inspect the review sheet and full-resolution privacy frames, then rerun with --reviewed")
+    if not shutil.which("ffmpeg") or not shutil.which("ffprobe"):
+        raise RuntimeError("ffmpeg and ffprobe are required")
+    review_path = recording / "renderer-review.json"
+    if not review_path.is_file():
+        raise RuntimeError("run browser-harness video review first")
+    review_report = json.loads(review_path.read_text(encoding="utf-8"))
+    if review_report.get("errors"):
+        raise RuntimeError("renderer review has blocking errors")
+    video.verify_source_manifest(recording)
+    comp = load_composition(recording)
+    expected_comp = compile_recording(recording, write=False)
+    if comp != expected_comp:
+        raise RuntimeError("composition.js is not the current compiled brief; rerun review")
+    artifact_hashes = review_report.get("artifactHashes") or {}
+    if set(artifact_hashes) != REVIEW_ARTIFACTS:
+        raise RuntimeError("renderer review lacks content hashes; rerun it")
+    for name, expected_hash in artifact_hashes.items():
+        path = recording / name
+        if not path.is_file() or video.file_hash(path) != expected_hash:
+            raise RuntimeError(f"{name} changed after review; rerun it")
+    renderer = recording / "video.html"
+    if video.file_hash(renderer) != video.file_hash(TEMPLATE):
+        raise RuntimeError("renderer is not the current shared template; rerun review")
+
+    output = Path(output_name)
+    if not output.is_absolute():
+        output = recording / output
+    if output.suffix.lower() != ".mp4":
+        raise RuntimeError("--output must end in .mp4")
+    webm = output.with_suffix(".webm")
+    for path in (webm, output):
+        if path.exists() or path.with_name(path.name + ".crdownload").exists():
+            raise RuntimeError(f"refusing to overwrite {path}")
+
+    expected = sum(float(beat.get("dur") or 0) for beat in comp.get("beats") or [])
+    started = time.monotonic()
+    with serve(recording) as url:
+        browser = None
+        try:
+            browser = _start_export(recording, url, webm)
+            if browser["preflight"].get("errors"):
+                raise RuntimeError(
+                    "export preflight failed: " + "; ".join(browser["preflight"]["errors"])
+                )
+            if any(not click.get("visible") for click in browser["clicks"]):
+                raise RuntimeError("export click visibility failed")
+            deadline = time.monotonic() + expected + 30
+            partial = webm.with_name(webm.name + ".crdownload")
+            while time.monotonic() < deadline:
+                if webm.is_file() and not partial.exists() and webm.stat().st_size:
+                    size = webm.stat().st_size
+                    time.sleep(0.25)
+                    if webm.stat().st_size == size:
+                        break
+                time.sleep(0.25)
+            else:
+                raise RuntimeError(f"timed out waiting for {webm}")
+        finally:
+            if not _close_editor(url, (browser or {}).get("previous")):
+                raise RuntimeError(
+                    "could not restore Chrome download behavior; restart Chrome"
+                )
+    capture_seconds = time.monotonic() - started
+
+    conversion_started = time.monotonic()
+    _probe(webm)
+    _run([
+        "ffmpeg", "-v", "error", "-i", str(webm), "-c:v", "libx264",
+        "-crf", "20", "-pix_fmt", "yuv420p", "-movflags", "+faststart", str(output),
+    ], recording)
+    conversion_seconds = time.monotonic() - conversion_started
+
+    verify_started = time.monotonic()
+    probe = _probe(output)
+    actual = float(probe["format"]["duration"])
+    if abs(actual - expected) > max(1.0, expected * 0.08):
+        raise RuntimeError(f"export duration {actual:.2f}s does not match composition {expected:.2f}s")
+    _run(["ffmpeg", "-v", "error", "-err_detect", "explode", "-i", str(output), "-f", "null", "-"], recording)
+
+    review_dir = recording / ".renderer-review"
+    final_captures = []
+    for index, at in enumerate((min(1.0, expected / 4), expected / 2, max(0.0, expected - 0.8)), 1):
+        path = review_dir / f"final-{index:02d}.jpg"
+        _run(["ffmpeg", "-v", "error", "-y", "-ss", f"{at:.3f}", "-i", str(output), "-frames:v", "1", str(path)], recording)
+        final_captures.append({"path": str(path), "time": at, "label": ("intro", "middle", "outcome")[index - 1]})
+    final_sheet = recording / "renderer-final-contact-sheet.jpg"
+    contact_sheet(final_captures, final_sheet, "FINAL MP4 SAMPLE")
+    verify_seconds = time.monotonic() - verify_started
+
+    report = {
+        "output": str(output),
+        "webm": str(webm),
+        "expectedDuration": round(expected, 3),
+        "actualDuration": actual,
+        "captureSeconds": round(capture_seconds, 3),
+        "conversionSeconds": round(conversion_seconds, 3),
+        "verificationSeconds": round(verify_seconds, 3),
+        "elapsedSeconds": round(time.monotonic() - started, 3),
+        "sha256": video.file_hash(output),
+        "probe": probe,
+        "finalContactSheet": str(final_sheet),
+    }
+    report_path = recording / "video-export.json"
+    report_path.write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8")
+    print(f"video: {output}")
+    print(f"final review: {final_sheet}")
+    print(f"verified {actual:.2f}s MP4 in {report['elapsedSeconds']:.1f}s")
+    return 0