@crvy/rprtr 0.2.4 → 0.3.1

package/CHANGELOG.md

@@ -5,6 +5,61 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.1] - 2026-08-24
+
+### Added
+
+- **server:** Warn once that native Windows docker mode is experimental
+
+### Documentation
+
+- Windows OS support design spec (WSL2 recommended, native win32 experimental)
+- Windows OS support implementation plan
+- Recommend WSL2 on Windows, mark native win32 docker mode experimental
+- **server:** Refresh stale comments after docker-support extraction
+
+### Fixed
+
+- **server:** Separator-agnostic rewriteContainerPath for Windows hosts
+- **server:** Posix --test-list entries in docker mode
+- **server:** Mount --test-list tmpfile at a fixed container path
+- **server:** Keep host PATH and Windows env noise out of docker containers
+## [0.3.0] - 2026-08-24
+
+### Added
+
+- **reporter:** Portable artifacts mode via CRVY_RPRTR_PORTABLE_ARTIFACTS
+- **server:** --update-snapshots run flag and docker-unavailable run reason
+- **server:** Carry run mode and phase in run-status broadcasts
+- **server:** Docker CLI helpers and container command resolution
+- **server:** DockerLauncher spawning playwright runs in containers
+- **server:** Run-mode resolution, docker launcher wiring, and docker CLI flags
+- **ui:** Run mode badge, update-baselines action, and image-pull state
+
+### Changed
+
+- **run-controller:** Extract RunLauncher strategy with LocalLauncher
+
+### Documentation
+
+- **spec:** Docker browser execution design
+- **plan:** Docker browser execution implementation plan
+- Docker mode usage and options
+- Docker rendering determinism findings; correct baseline arch guidance
+
+### Fixed
+
+- **run-controller:** Make UI re-run work on Playwright 1.59+
+- **server:** Surface auto-mode docker fallback warning
+- **server:** Rewrite container paths in reporter register payloads
+- **server:** Rewrite host paths in docker container command args
+- **server:** Warn when --config path is unreachable inside container
+- **reporter:** Content-addressed artifact names for static-host portability
+- **server:** Route docker runs via rootDir-keyed --test-list with host paths
+
+### Testing
+
+- CI-gated docker smoke test for containerized runs
 ## [0.2.4] - 2026-07-06
 
 ### Added

package/README.md

@@ -122,6 +122,47 @@ If you generate a report on one operating system and then open it on another (fo
 
 For fully portable artifact loading across operating systems, run the reporter in CI mode (`ci: true`) and ship the `screenshots/` directory alongside the report JSON.
 
+## Docker Mode
+
+Run Playwright browsers inside a pinned Docker container so screenshot baselines are reproducible across machines — no local browser or system-dependency installation required.
+
+```bash
+npx crvy-rprtr --run-mode docker
+```
+
+The server still runs on your host; only `playwright test` executes in the container, against the official `mcr.microsoft.com/playwright:v<your @playwright/test version>-noble` image with your project bind-mounted. Reporters stream results back live, and approve/update flows work unchanged.
+
+| Mode             | Behavior                                                                        |
+| ---------------- | ------------------------------------------------------------------------------- |
+| `auto` (default) | Docker when a daemon is reachable, local on CI, warned local fallback otherwise |
+| `docker`         | Always Docker; runs fail fast with `docker-unavailable` when the daemon is down |
+| `local`          | Never Docker                                                                    |
+
+| Option                         | Description                                                                                                                                                                  |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--run-mode <mode>`            | `local`, `docker`, or `auto` (default: `auto`)                                                                                                                               |
+| `--docker-image <image>`       | Custom image. With a custom image, the container-side package manager is auto-detected from your lockfile (`npx` / `pnpm exec` / `yarn` / `bunx`); the image must contain it |
+| `--docker-platform <platform>` | `linux/amd64` or `linux/arm64` (default: host architecture)                                                                                                                  |
+
+Programmatic equivalents: `startServer({ runMode: 'docker', docker: { image, platform, command, extraArgs } })`. `docker.command` overrides the container-side invocation verbatim (e.g. `['pnpm', 'exec', 'playwright']`); `docker.extraArgs` appends raw `docker run` flags.
+
+### Windows
+
+The recommended Windows setup is **WSL2**: enable Docker Desktop's WSL2 integration (Settings → Resources → WSL integration), keep the project inside the WSL filesystem (e.g. `~/proj` in your distro, not `/mnt/c/...` — bind-mounts from `/mnt/c` are slow and lack inotify events), and run `npx crvy-rprtr` from the WSL shell. Paths and rendering then behave exactly as on Linux, so baselines match CI.
+
+Running natively on a Windows host (PowerShell/cmd) works but is **experimental**: Docker Desktop translates the `C:\proj:/work` mount, and crvy-rprtr rewrites Windows paths in container arguments, but this path has no CI coverage — expect a one-time experimental warning on the first run. Local (`--run-mode local`) Windows runs can never match Linux CI baselines (DirectWrite vs fontconfig text rendering) — which is exactly the problem Docker mode solves, so prefer WSL2.
+
+Known limitations on native Windows: UNC project roots (`\\server\share\...`) are unsupported; drive-letter casing is normalized (`C:` ≡ `c:`), but path body case is not; Windows-specific host env vars (`PATH`, `TEMP`, `APPDATA`, `ProgramFiles`, ...) are filtered out so the container keeps its own environment (user env vars like API keys are still forwarded); single-file bind mounts (used for `--test-list`) can be flaky on some Docker Desktop versions — if the container sees an empty or missing test list, that is why.
+
+Notes:
+
+> **Important — baselines are image-specific, not architecture-specific.** Text rendering follows the image's fontconfig: Ubuntu-based images (including the default `mcr.microsoft.com/playwright:*-noble`) render text with subpixel (LCD) antialiasing and slight hinting, while Debian-based images (e.g. `node:24` + `playwright install --with-deps`) render grayscale with full hinting — different pixels _and_ slightly different text widths. Generate and verify baselines in the **same image** everywhere (CI and local), and regenerate baselines once after switching image flavor. See [docs/docker-screenshot-determinism.md](docs/docker-screenshot-determinism.md) for the full investigation.
+
+- Baselines are **not** architecture-specific for typical DOM/text pages: amd64 and arm64 variants of the same image render bit-identically in practice (verified: 100/103 tests byte-identical between an amd64 CI runner and Apple Silicon). Use the native architecture on every host — do **not** pin `--docker-platform` to force amd64 emulation on Apple Silicon (Rosetta/QEMU is slower and less stable, and buys nothing). Residual risk: canvas 2D / complex SVG / WebGL content can show tiny cross-arch anti-aliasing diffs; handle per-test with `maxDiffPixels`.
+- If your `playwright.config.ts` uses `webServer`, that server now starts inside the container: it must bind `0.0.0.0`, and hosts it references must resolve inside the container.
+- Timezone and locale are pinned (`TZ=UTC`, `LANG=C.UTF-8`, `LC_ALL=C.UTF-8`) so date/number rendering in screenshots is stable; override via `docker.extraArgs` if you need a different locale under test.
+- The "Run & update baselines" button (▶↻) regenerates baselines inside the container, keeping generation and verification in the same image.
+
 ## Programmatic API
 
 ```ts