# Deterministic Install & Headless Chromium

Offline runners must avoid ad-hoc network calls while staying reproducible. The Angular workspace now ships a locked dependency graph and helpers for provisioning a Chromium binary without embedding it directly in `npm install`.

## Prerequisites

- Node.js **20.11.0** or newer (matches the `engines` constraint).
- npm **10.2.0** or newer.
- Local npm cache location available to both the connected “seed” machine and the offline runner (for example, `/opt/stellaops/npm-cache`).

## One-Time Cache Priming (Connected Host)

```bash
export NPM_CONFIG_CACHE=/opt/stellaops/npm-cache
npm run ci:install
```

`ci:install` executes `npm ci --prefer-offline --no-audit --no-fund` so every package and integrity hash lands in the cache without touching arbitrary registries afterwards.

If you plan to bundle a Chromium binary, download it while still connected:

```bash
npx @puppeteer/browsers install chrome@stable --path .cache/chromium
```

Archive both the npm cache and `.cache/chromium/` directory; include them in your Offline Kit transfer.

## Offline Runner Execution

1. Extract the pre-warmed npm cache to the offline host and export `NPM_CONFIG_CACHE` to that directory.
2. Optionally copy the `.cache/chromium/` folder next to `package.json` (the Karma launcher auto-detects platform-specific paths inside this directory).
3. Run `npm run ci:install` to restore dependencies without network access.
4. Validate Chromium availability with `npm run verify:chromium`. This command exits non-zero and prints the search paths if no binary is discovered.
5. Execute tests via `npm run test:ci` (internally calls `verify:chromium` before running `ng test --watch=false`).

## Chromium Options

- **System package** – Install `chromium`, `chromium-browser`, or `google-chrome-stable` via your distribution repository or the Offline Kit. The launcher checks `/usr/bin/chromium-browser`, `/usr/bin/chromium`, and `/usr/bin/google-chrome(-stable)` automatically.
- **Environment override** – Set `CHROME_BIN` or `STELLAOPS_CHROMIUM_BIN` to the executable path if you host Chromium in a custom location.
- **Offline cache drop** – Place the extracted archive under `.cache/chromium/` (`chrome-linux64/chrome`, `chrome-win64/chrome.exe`, or `chrome-mac/Chromium.app/...`). The Karma harness resolves these automatically.

Consult `src/Web/StellaOps.Web/README.md` for a shortened operator flow overview.