Share the Chrome launcher and retarget CdpClient onto deno-cri

[cwickham]

Stacked on #14815 (feat/axe-scan-command).

Description

This is the follow-up promised in
#14815 (comment),
where @cderv asked why the axe scanner does not reuse cri.ts.

The short answer from that thread: a Chrome driver has three layers, and the
answer differs at each one.

1. Launcher — start the process: flags, profile dir, wait for the CDP
   port, kill on exit.
2. Transport — a generic pipe to the running browser. It sends any CDP
   command, awaits the result, subscribes to events, and closes.
3. Task logic — which commands to send, in what order, with what
   recovery. For mermaid that is the cri.ts facade. For the scanner it is
   scanCell.

Layers 1 and 2 were duplicated. This PR removes both copies. Layer 3 stays
separate, because mermaid's commands and the scanner's commands are different
jobs. After this PR, no launcher code and no protocol code exists twice among
quarto's CDP drivers. (src/core/puppeteer.ts is a third, puppeteer-based
launch path — withHeadlessBrowser, reached through
withPuppeteerBrowserAndPage and inPuppeteer. Nothing outside that file
enters it, so I left it alone and only made sure the new comments do not
claim it away.)

No user-visible change, so no changelog entry.

Part 1: one launcher

launchChrome() in the new src/core/cri/launch.ts starts headless Chrome
for both callers. It owns the flag set, the QUARTO_CHROMIUM_HEADLESS_MODE
escape hatch, the optional throwaway --user-data-dir, stderr draining, exit
cleanup, and the wait for the CDP endpoint.

The two old launchers differed in six ways. Three are now unified and three
are passed in:

Difference	Was	Now
--renderer-process-limit=1	cri only	passed in by cri
--hide-scrollbars	scanner only	passed in by the scanner
throwaway --user-data-dir	scanner only	passed in by the scanner
stdout	cri piped it and never read it	"null" for both
stderr	cri read it once after a failure, the scanner drained it	drained for both
exit cleanup	cri used registerForExitCleanup, the scanner used onCleanup	registerForExitCleanup for both

The three unifications each fix something in the failure path:

• An unread stdout pipe is a way for Chrome to block on a full buffer.
• cri's old error path could hang. It awaited cmd.status for a Chrome that
  was running happily but had not opened the port, and it asserted that one
  read had drained the whole stderr pipe.
• onCleanup handlers cannot be unregistered, so a mermaid-heavy render grew
  the cleanup list by one dead closure per file.

I left the throwaway profile dir as the scanner's own, and it is the one
decision I am least sure of. Giving mermaid an isolated profile is arguably
correct for the same reason it is correct here — a Chrome the user already
has running can otherwise short-circuit the launch. But mermaid renders sit
in the hot path of ordinary user renders, a fresh profile costs Chrome's
first-run work every time, and this PR is meant to remove duplication rather
than change mermaid. Happy to unify it if you disagree.

One more change came out of this. registerForExitCleanup() never installed
the handler that kills its own registry — only execProcess() did. A command
that spawns a browser and never shells out could therefore register a process
and still orphan it on Ctrl-C. quarto call axe is exactly that command,
which is why it used onCleanup directly. registerForExitCleanup() now
installs the handler itself.

One timing changed, in the failure direction only. cri's wait for the CDP
endpoint goes from 3s to the shared 15s, which only lengthens how long a
genuinely broken launch takes to report. A healthy Chrome still returns as
soon as the endpoint answers.

Part 2: one transport

CdpClient in scan.ts kept its own WebSocket internals: message framing, an
id counter, a pending map, a listener registry. That was the third copy of
that machinery in the tree, after deno-cri and whatever Chrome runs on the
other end. Those internals are now the vendored deno-cri
(src/core/cri/deno-cri/), the same client cri.ts connects with.

The typed interface is unchanged, because the unit tests stub it and three
behaviours are what fail-closed cells depend on (all three now also covered
against a real browser — see Verification):

• send<T> resolves with the command result, or rejects.
• once(method) returns { event, cancel }, so a cell that timed out can
  stop caring about a load event that belongs to it.
• Close rejects everything still in flight.

deno-cri does not do the third one. It notices a dropped socket and emits
disconnect, then leaves every in-flight command unsettled forever. So
CdpClient tracks in-flight sends itself and rejects them on close or on
disconnect. A crashed tab fails its own cell inside --timeout instead of
hanging the scan.

Target discovery went with it: deno-cri picks the page target, and creates
one if the browser has none (#4653), so scan.ts's own /json/list polling
is gone. The launcher's wait for the endpoint is the only wait left.
Connecting retries five times at 100ms, the interval cri.ts measured its way
to.

No vendored code is touched. One behaviour is not carried over: the old
client logged and ignored a frame that did not parse as JSON, where deno-cri
parses inside the socket's onmessage handler, so an unparseable frame exits
the process. Chrome does not send such frames, and guarding it would mean
patching deno-cri/chrome.js for a case never observed, so it is left alone.

Known cost: connecting through deno-cri fetches /json/protocol to
build its domain shorthands. That is roughly 1 MB of JSON, once per scan, on a
run that already takes minutes. cri.ts has paid it per render for years.

Explicitly out of scope

• cri.ts exporting a typed transport as a core surface. That is the cleaner
  end state, and it waits on the scanner's needs settling — concurrent tabs in
  particular.
• Any change to mermaid's facade behaviour.
• Any change to the vendored deno-cri sources.

Verification

• 147 axe unit tests and 9 tests/smoke/axe/ smoke tests pass, at
  every commit that touches them.

• 3 mermaid smoke tests pass (mermaid-svg-docx, mermaid-gfm-svg,
  mermaid-multi-diagram).

• A mermaid-format: png render produces a byte-identical PNG before and
  after (sha256 9ee2aef2…).

• A full quarto-web scan: 416 pages found, 373 scanned, 1504 cells,
  before and after. Identical finding set (the same 300 signature ids), the
  same {total: 300, new: 300, baselined: 0}, the same 12 not-ok cells, and
  all 1504 cell statuses identical. Timing is unchanged: 639s of cell time
  before, 643s after, median cell 355ms in both.

  What is not byte-identical is which cells six occurrences were attributed
  to, on OJS tables, a leaflet map and a headroom navbar — all client-side
  rendering. I ran the unchanged code a second time as a control, and those
  two runs of the same code differ from each other in 21 attributions. So
  the after-run sits inside the existing run-to-run noise, and this is the
  client-side render race llm-docs/axe-scan-architecture.md already
  documents.

• Fail-closed against a real browser is now a test rather than a manual
  check: tests/smoke/axe/axe-transport-failclosed.test.ts. With a command
  the browser can never answer in flight, closing the client, sending after
  close, and the connection dropping from the far end all reject with
  CDP connection closed. Every wait has a deadline that reports as hung,
  so a transport that never settles fails rather than passes. Mutation-checked:
  reverting abandonPending to deno-cri's own behaviour fails it with
  hung: nothing settled within 15000ms. Runs in ~0.7s.

• deno check src/quarto.ts and deno lint are clean on every changed file.

Checklist

I have (if applicable):

• referenced the GitHub issue this PR closes — no issue. This answers a
  review thread on Add quarto call axe, a hidden experimental site accessibility scanner #14815 (linked above)
• updated the appropriate changelog in the PR — no user-visible change
• ensured the present test suite passes
• added new tests — axe-transport-failclosed.test.ts, covering the half
  a stubbed client cannot: that a real CdpClient rejects at all when the
  connection goes
• created a separate documentation PR

llm-docs/axe-scan-architecture.md is updated: its scan-stage section
described two launchers and a hand-rolled WebSocket, with both of these
changes listed as future work.

AI-assisted PR

• AI tool used: Claude Code
• Codebase grounding: local clone
• Human review: I have reviewed, tested, and verified the AI-generated content before submitting.

[posit-snyk-bot]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[cwickham]

@cderv this is now up to date with the recent changes on #14815 All commits went through roborev. One question for you, there are no tests here beyond the existing axe and mermaid tests that consume it. Is it worth adding tests for some of the launcher failure modes?

[cderv]

LGTM.

About the test this is a good idea to maybe add some more. I'll do that either in this PR before merge or after.

I'll take over to merge both.

Thanks a lot for the work on this !!