lann · Jul 26, 2026 · Jul 26, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -57,8 +57,9 @@ conformance/            # cross-implementation conformance suite — see
   signing-guest/        #   host-only guest for surfaces the in-guest
                         #     provider does not export (ecdsa-sign)
   adapters/             #   per-target drivers: wasmtime, composed-driver (for
-                        #     the composed target), jco (Node gates; the
-                        #     browser target needs Chromium and runs manually)
+                        #     the composed target), jco (Node gates everywhere;
+                        #     the browser target gates in CI, locally opt-in
+                        #     via CONFORMANCE_BROWSER=1 with Chrome installed)
   runner/               #   classifies results against manifests.toml and
                         #     renders conformance/matrix.md
   manifests.toml        #   per-target expectations (policy-driven)
@@ -138,7 +139,7 @@ Run the recipes that cover what you changed, and fix anything they report.
 | `just test` | any Rust host/guest code (includes the guest-under-Wasmtime integration test). |
 | `just build-component` | the `crypto-demo` guest or its WIT. |
 | `just test-webcrypto-composed` | the `guest-impl` provider, the demo driver, or any WIT (composes guest + provider + driver with `wac plug` and runs under `wasmtime`). |
-| `just conformance` | any host/guest behavior the suite asserts — the WIT surface, an implementation, the conformance guest/vectors/translation policy, or manifests. Gates on the wasmtime, composed, and jco-node targets (Node 24+; jco-browser needs a Chromium install and is run manually). |
+| `just conformance` | any host/guest behavior the suite asserts — the WIT surface, an implementation, the conformance guest/vectors/translation policy, or manifests. Gates on the wasmtime, composed, and jco-node targets (Node 24+); jco-browser additionally gates in CI (the Actions runner ships Chrome) — locally, opt in with `CONFORMANCE_BROWSER=1` (needs Chrome/Chromium 137+). |
 | `just transpile` | anything affecting the component's interfaces, or the jco flags in `examples/jco-demo/package.json`. |
 | `just test-node` | the jco host (`webcrypto.js`) or the component it runs. |
 | `just check` | broad Rust/WIT changes — the quick gate for most commits. |

diff --git a/README.md b/README.md
@@ -115,8 +115,9 @@ All three implementations run identical guest components. The conformance
 suite (Wycheproof HMAC-SHA-256, AES-GCM, and ChaCha20-Poly1305 vectors and
 NIST CAVP SHA-2 vectors under multiple stream-chunking schedules, plus
 API-contract probes) gates the wasmtime, composed, and jco-node
-targets; the `crypto-demo` guest additionally covers the jco
-host end to end.
+targets everywhere, and the jco-browser target in CI (locally, opt in
+with `CONFORMANCE_BROWSER=1`; needs Chrome/Chromium 137+); the
+`crypto-demo` guest additionally covers the jco host end to end.
 
 A note on the in-guest provider: wasm offers no portable constant-time
 guarantees, so [`guest-impl/README.md`](guest-impl/README.md) classifies

diff --git a/conformance/README.md b/conformance/README.md
@@ -23,8 +23,9 @@ adapters/
   composed-driver/   # CLI driver for the composed in-guest target (guest +
                    #   in-guest provider via `wac plug`); prints results JSON
   jco/             # Node + headless-Chromium adapters over jco-impl's
-                   #   webcrypto.js (jco-node gates; the browser target
-                   #   needs a Chromium install and is run manually)
+                   #   webcrypto.js (jco-node gates everywhere; jco-browser
+                   #   gates in CI, locally opt-in via CONFORMANCE_BROWSER=1
+                   #   with Chrome/Chromium 137+ installed)
 runner/            # classification + matrix.md rendering
 ```
 

diff --git a/conformance/adapters/jco/src/run-browser.mjs b/conformance/adapters/jco/src/run-browser.mjs
@@ -3,8 +3,9 @@
 // Chromium (137+, which ships JSPI), and writes
 // `conformance/results/jco-browser.json`.
 //
-// Not gating (it needs a Chromium install); run it manually with
-// `just conformance-jco-browser`.
+// Gates in CI (the Actions runner image ships Chrome); locally it needs a
+// Chrome/Chromium install — run it with CONFORMANCE_BROWSER=1 just
+// conformance, or directly with `just conformance-jco-browser`.
 import { createServer } from "node:http";
 import { readFile, access } from "node:fs/promises";
 import { join, extname } from "node:path";

diff --git a/conformance/manifests.toml b/conformance/manifests.toml
@@ -13,9 +13,11 @@ expected-fail = []
 [targets.composed]
 expected-fail = []
 
-# The jco-node target is gating (part of `just conformance`); jco-browser is
-# enumerated but not gating (it needs a Chromium install and is run manually,
-# so it produces no results in CI and the runner warns rather than fails).
+# The jco-node target is gating everywhere (part of `just conformance`).
+# jco-browser gates in CI (the Actions runner ships Chrome); locally it needs
+# a Chrome/Chromium install and runs only when opted in with
+# CONFORMANCE_BROWSER=1, so the runner warns rather than fails on a missing
+# results file.
 
 # Browser WebCrypto implements no ChaCha20-Poly1305 (the WICG proposal is
 # unimplemented), so the jco host declines both `chacha-variant`s as

diff --git a/justfile b/justfile
@@ -121,15 +121,29 @@ conformance-timeout := "600"
 # unexpected-pass.
 #
 # Enabled targets: wasmtime, composed, and jco-node (Node 24+ with npm
-# required). jco-browser is not gating — it needs a Chromium install; run it
-# manually with `just conformance-jco-browser` (the runner warns on targets
-# without results rather than failing).
-conformance: conformance-wasmtime conformance-composed conformance-jco-node
+# required) — plus jco-browser under GitHub Actions (the runner image ships
+# Chrome) or when opted in locally with CONFORMANCE_BROWSER=1 (needs
+# Chrome/Chromium 137+; the runner warns on targets without results rather
+# than failing).
+conformance: conformance-wasmtime conformance-composed conformance-jco-node _conformance-jco-browser-gate
     cargo run --release -p conformance-runner -- \
         --manifests conformance/manifests.toml \
         --results conformance/results \
         --matrix-out conformance/matrix.md
 
+# Run the jco-browser conformance target when gating applies: always under
+# GitHub Actions, locally only with CONFORMANCE_BROWSER=1 (skips with a
+# notice otherwise). The `conformance` recipe's runner pass classifies the
+# results.
+_conformance-jco-browser-gate:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    if [ "${GITHUB_ACTIONS:-}" != "true" ] && [ "${CONFORMANCE_BROWSER:-}" != "1" ]; then
+        echo "skipping the jco-browser conformance target (opt in with CONFORMANCE_BROWSER=1; needs Chrome/Chromium 137+)"
+        exit 0
+    fi
+    just conformance-jco-browser
+
 # Build the shared conformance guest component into conformance/guest/build/.
 build-conformance-guest:
     cargo build --release -p conformance-guest --target wasm32-unknown-unknown
@@ -189,7 +203,7 @@ conformance-jco-node: build-conformance-guest build-signing-guest
 
 # Run the conformance corpus under the jco host in headless Chromium (137+;
 # auto-detected, or set CHROME_PATH). Writes conformance/results/jco-browser.json.
-# Not gating — needs a Chromium install; run it manually.
+# Gates in CI; local `just conformance` runs it only with CONFORMANCE_BROWSER=1.
 conformance-jco-browser: build-conformance-guest
     cd conformance/adapters/jco && npm run transpile && \
         timeout {{conformance-timeout}} npm run run:browser