cornhsu-parity 1.1.0 → 2.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 許彧銘 Hsu Yu-Ming (Cornhsu)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -11,7 +11,7 @@
 ## GitHub Action
 
 ```yaml
-- uses: HSU-YU-MING/cornhsu-parity@v1   # @v1 tracks the latest 1.x (interfaces frozen since 1.0)
+- uses: HSU-YU-MING/cornhsu-parity@v2   # @v2 tracks the latest 2.x (interfaces frozen within a major)
   with:
     config: parity.config.json      # optional, defaults to parity.config.json
     target: /pricing                # optional, check only this route (omit for all)
@@ -63,13 +63,13 @@ PR comment, updating the same comment rather than adding new ones.
 
 | | |
 |---|---|
-| Releases | 27 on NuGet (v0.1.0 → v1.1.0). Pushing a tag publishes via OIDC Trusted Publishing — zero long-lived keys in the repo |
+| Releases | 29 on NuGet (v0.1.0 → v2.1.0). Pushing a tag publishes via OIDC Trusted Publishing — zero long-lived keys in the repo |
 | Compared properties | Size, padding, spacing, typography, color (CIEDE2000 ΔE), relative position — **absolute coordinates are deliberately excluded** (they are guaranteed false positives in a flexible layout) |
 | Design sources | 4: the Figma API, a rendering snapshot, an image + annotations (pixel sampling — any tool that exports a PNG works), or JSON |
 | Implementation sources | The web (including **shadow DOM, same-origin iframes, and multiple responsive breakpoints**) plus **Electron** (attached to the live window over CDP) |
-| Tests | **208**, covering the CIEDE2000 reference data set (Sharma), match disambiguation, position false-positive guards, image sampling, and real-browser capture regressions |
+| Tests | **1047**, covering the CIEDE2000 reference data set (Sharma), match disambiguation, position false-positive guards, image sampling, and real-browser capture regressions |
 | Proven in CI | The GitHub Action is validated by **real PRs in an external repo**: blocking the PR, commenting automatically (updating in place), and baseline regression gating |
-| Proven in production | **All 21 pages of cornhsu.com are gated by Parity itself** — dogfooding has already found and fixed three flaky root causes (most recently a scroll-triggered entrance animation; see 0.11.1) |
+| Proven in production | **All 26 pages of cornhsu.com are gated by Parity itself** — dogfooding has already found and fixed three flaky root causes (most recently a scroll-triggered entrance animation; see 0.11.1) |
 
 ## Install
 
@@ -86,15 +86,23 @@ dotnet tool install -g Cornhsu.Parity
 > The npm build is the same self-contained native executable; you only download the one for
 > your platform (win32-x64 / win32-arm64 / linux-x64 / linux-arm64 / darwin-x64 / darwin-arm64).
 > Playwright normally bundles its own copy of Node; the npm build strips that out and uses the
-> Node you already have, which saves about 88 MB per platform package.
+> Node you already have, which saves at least 88 MB per platform package. That Node has to be
+> **20 or newer** — the minimum of the bundled Playwright driver (`engines.node` says so).
+
+> **`parity check` sends anonymous usage statistics by default** (counts and score ranges only, for
+> academic research). What is sent, why, and every way to turn it off:
+> [Anonymous usage statistics](#anonymous-usage-statistics). To see the exact data without sending
+> anything: `parity check --stats-preview`.
 
 ## Quick start
 
 ```sh
 parity init                # Generate a parity.config.json template
-parity install-browser     # First run only: download Playwright Chromium
+parity install-browser     # Download Playwright Chromium: on first run, and again after an
+                           #   upgrade if check says Chromium is not installed
 export FIGMA_TOKEN=...     # Only the file_content:read scope is needed
 parity check               # Compare; writes a report and sets the exit code
+                           #   (--stats-preview: print the anonymous statistics it would send, send nothing)
 parity report              # Re-render the Markdown report from an existing report.json
                            #   (no re-scan; --md writes a file, otherwise it prints to stdout)
 parity snapshot            # Freeze the currently rendered UI as the design baseline —
@@ -105,6 +113,11 @@ parity lint                # Design lint: are the design file's values inside th
                            #   design-token set? (design only, no implementation)
 parity check --reverse     # Reverse view, for a designer redrawing an existing page:
                            #   how does my draft differ from what ships? (never gates)
+parity bug-report          # (experimental) Collect version / OS / Node / Chromium info and print
+                           #   it with a pre-filled GitHub issue link. bug-report itself connects to nothing;
+                           #   opening the link sends the masked report to github.com (it rides in
+                           #   the URL). No issue until you submit the form. --config adds a
+                           #   structural summary without URLs, routes, keys, tokens or paths
 ```
 
 When working inside this repo:
@@ -125,24 +138,29 @@ serious-severity gaps — which is exactly the behaviour you want from a CI gate
   "figmaFileKey": "abcd1234",
   "designToken": "env:FIGMA_TOKEN",
   "mapFile": "parity.map.json",              // manual fallback mapping (layer name → selector)
-  "tokensFile": "tokens.json",               // optional: design tokens (name → value);
+  "tokensFile": "tokens.json",               // optional: design tokens, a flat object of string values
+                                             //   ({"brand": "#2563EB", "space-4": "16px"}; // comments ok);
                                              //   suggested fixes will name the matching token
   "targets": [
     { "route": "/", "frame": "10:2", "url": "http://localhost:8080/" }
   ],
   "compare": { "position": "relative" },     // relative = compare relative position (default); none = skip position
-  "tolerances": { "sizePx": 2, "spacingPx": 2, "colorDeltaE": 2.0, "positionPx": 4 },
+  "tolerances": { "sizePx": 2, "spacingPx": 2, "colorDeltaE": 2.0, "fontSizePx": 0.5, "positionPx": 4 },
   "ignore": ["[data-parity-ignore]"],
   "gate": {
-    "failOn": ["critical", "serious"],
-    "minMatchRate": 0                        // optional: FAIL outright below this match rate (0–1); 0 = no threshold
-  }
+    "failOn": ["critical", "serious"],       // any of minor / medium / serious / critical, one per string
+    "minMatchRate": 0                        // optional: below this match rate (0–1) → exit 3, see below; 0 = no threshold
+  },
+  "stats": { "share": true }                 // optional: false turns anonymous usage statistics off;
+                                             //   see "Anonymous usage statistics" below (also projectId)
 }
 ```
 
 > Besides gaps, the gate also validates **match integrity**: zero matches (or zero design nodes)
-> is always a GATE FAIL — with nothing matched there are no gaps to catch, so a silent PASS
-> would be a false pass, usually caused by a wrong url or frame. `--baseline` mode is not exempt.
+> always fails, with exit code 3 (`MATCH INTEGRITY TOO LOW`) rather than 1 — with nothing
+> matched there are no gaps to catch, so a silent PASS would be a false pass, usually caused by
+> a wrong url or frame. A match rate below `gate.minMatchRate` fails the same way, with exit
+> code 3. `--baseline` mode is not exempt; `--reverse` never gates and always exits 0.
 
 ## Targets: a web page or an Electron desktop app
 
@@ -209,15 +227,20 @@ Only the things that should hold no matter how the layout flows:
   as references (TEXT/HUG boxes are never references, TEXT is never a target, and Y is honestly
   skipped when everything above is text), so line-height drift in a flowing layout does not
   produce false positives. Turn it off with `compare.position: "none"`.
-- **Typography**: size, weight, line-height and letter-spacing are compared exactly;
-  font-family is a **soft gap** and never gates.
+- **Typography**: size and letter-spacing are compared as numbers within `tolerances.fontSizePx`,
+  line-height within `tolerances.sizePx`; weight has no tolerance — any difference is a gap
+  (under 200 apart is medium, 200 or more is serious). font-family is a **soft gap**: it is
+  reported (severity `minor`, marked soft) but costs no fidelity points and **never gates** —
+  not even when `failOn` includes `minor`, and `--baseline` mode does not count it as new.
 - **Color**: thresholded on CIEDE2000 (ΔE), not hex equality. Parsing covers modern syntax
   (`rgb(37 99 235 / .5)`, `color(srgb …)`, `oklch()`, `color(display-p3 …)`).
 - **Absolute x/y is deliberately never compared**: it legitimately differs in a flexible layout,
   so comparing it means false positives, which means losing trust.
 
-> When the design source is Figma, layer names in the report (both the Markdown and the local UI)
-> **link back to that node in Figma** — a designer clicks once and lands on the layer.
+> When the design source is Figma, layer names in the report (the Markdown written by
+> `check --md` or re-rendered by `parity report`, and the local UI) **link back to that node in
+> Figma** — a designer clicks once and lands on the layer. When `designFile` is set it wins over
+> `figmaFileKey`, so a snapshot- or JSON-based report carries no Figma links.
 
 ## Two workflows for designers
 
@@ -245,7 +268,9 @@ frame's size**, so a 375-wide phone frame makes your media queries fire naturall
 ```
 
 `route` is only a label in the report, so pick something recognizable. You only need `width` /
-`height` on a target when the frame's width is not the viewport width you want to test.
+`height` on a target when the frame's size is not the viewport you want to test. Each one
+overrides its own axis: `width` alone keeps the default height of 800, `height` alone keeps the
+frame's width.
 
 ## Shadow DOM / iframes
 
@@ -262,7 +287,8 @@ unaffected and works as usual).
 
 1. **Automatic text anchoring**: design TEXT content ↔ page text (matched only when unique;
    when several elements share the text, the layer name disambiguates — and it still refuses to force a match)
-2. **Layer name ↔ id / class / aria-label**: `CTA Button` matches `class="cta-button"` automatically
+2. **Layer name ↔ id / class / aria-label** (falling back to `data-testid` when there is no
+   aria-label): `CTA Button` matches `class="cta-button"` automatically
 3. **Container inference**: an unmatched container is inferred from the lowest common ancestor of
    its already-matched descendants (pure structure — no guessing)
 4. **Manual fallback**: add `data-parity="Layer Name"` in your HTML, or write
@@ -286,11 +312,102 @@ src/Parity.Engine/        The engine; FidelityEngine is the only entry point
   DesignSources/          IDesignSource + Figma (REST + local cache) / Json
   ImplementationSources/  IImplementationSource + Web (Playwright)
   Comparison/             Normalizer / Matcher / DiffEngine / ColorDelta (CIEDE2000)
-src/Parity.Cli/           The dotnet tool shell: parity check / init / install-browser
+src/Parity.Report/        The report contract: report.json types, ReportWire, the fidelity score,
+                          baseline comparison — no package dependencies, so no Playwright
+src/Parity.Cli/           The dotnet tool shell: parity check / init / install-browser,
+                          the local report UI (parity serve) and parity push (experimental)
+src/Parity.Storage/       Baseline history (EF Core + SQLite), behind parity baseline
+src/Parity.Server/        Team dashboard shell (ASP.NET Core) — not published to NuGet
+src/Parity.Server.Data/   Its database (EF Core + SQLite, migrations from day one)
+web/                      The dashboard front end (React + Vite + TypeScript); the build
+                          output lands in src/Parity.Server/wwwroot
 tests/Parity.Tests/       Unit tests (including the CIEDE2000 reference data)
 samples/demo/             Offline demo: a deliberately broken page + a design JSON
 ```
 
+There are three shells, and **the engine does not know that any of them exist**:
+
+1. **CLI** (`Parity.Cli`) — `parity check` in a terminal or in CI. This is the only shell
+   published as a package (NuGet / npm / the GitHub Action).
+2. **Local report UI** (`parity serve`) — a zero-build SPA bound to 127.0.0.1, for the
+   person who is actually fixing the gaps.
+3. **Team dashboard** (`Parity.Server` + `web/`) — somewhere the reports can accumulate, so
+   that trends exist and so that people who never touch the tool have a place to look. You
+   deploy it yourself; it is not on NuGet, and it is **still in development** (see M7 below).
+
+> **Where the dashboard keeps its data.** The web host and the admin commands (`create-project`,
+> `create-invite`) find the SQLite database the same way: `ConnectionStrings:parity` (from
+> `appsettings.json` or the `ConnectionStrings__parity` environment variable), then
+> `PARITY_SERVER_DB` (a file path), then `parity-server.db` in the working directory. This is the
+> reverse of .NET's usual "environment beats appsettings": a connection string in
+> `appsettings.json` wins over `PARITY_SERVER_DB` — to override it from the environment, set
+> `ConnectionStrings__parity`. The reason: an explicit connection string is the more specific
+> setting, and the integration tests inject one that a developer's `PARITY_SERVER_DB` must not
+> redirect.
+
+### One dashboard, two tools
+
+The same server also takes reports from **[XamlContrast](https://github.com/HSU-YU-MING/cornhsu-xamlcontrast)**
+(the static WCAG contrast audit for XAML apps): `xamlcontrast --push <report.json>` sends the file
+its `--json` option wrote, through the same `POST /api/runs`, marked with an `X-Parity-Tool: xamlcontrast`
+header (`parity push` sends no such header, which the server reads as `parity`). A project can hold runs
+from both tools. XamlContrast runs get their own overview card per project (pairs below AA, fail · warn,
+coverage), a fail/warn trend, and an issue list (file and line, element, foreground and background as
+written in the XAML, the ratio in each theme, the threshold). Each XamlContrast run also shows what changed
+since the previous XamlContrast run on the same branch — new, worse, fixed and improved pairs — compared the
+way XamlContrast's own `--baseline` does (a pair is file, element, foreground and background, without the line
+number; more places or a lower worst ratio is worse). Like `parity push`, the XamlContrast side is
+**experimental** until the dashboard is publicly deployed.
+
+### Hosting it yourself
+
+The repo root has a `Dockerfile`. The image contains the server, its data layer and the report types,
+and nothing else: no browser, no engine (CI checks this).
+
+```sh
+docker build -t parity-server .
+docker run -d --name parity -p 8080:8080 -v parity-data:/data \
+  -e Parity__PublicUrl=https://parity.example.com \
+  -e ASPNETCORE_FORWARDEDHEADERS_ENABLED=true \
+  parity-server
+docker exec parity dotnet Parity.Server.dll create-project my-site          # prints the CI token once
+docker exec parity dotnet Parity.Server.dll create-invite my-site you@example.com owner
+```
+
+| Setting | What it does |
+|---|---|
+| `Parity__PublicUrl` | The address people open. Invite links are built from it, not from the `Host` the server sees (behind a proxy that can be an internal name). It must be an absolute `http(s)` URL; a bad value stops the server and the admin commands. |
+| `Parity__KeysDirectory` | Where the keys that sign the login cookie live. Preset to `/data/keys` in the image. Without it, every redeploy of a container signs everyone out. |
+| `PARITY_SERVER_DB` | The SQLite database. Preset to `/data/parity-server.db` in the image. |
+| `ASPNETCORE_FORWARDEDHEADERS_ENABLED=true` | Behind a reverse proxy, **required**, and only behind a proxy you trust (otherwise anyone can forge their client IP). Without it the server sees one IP for everybody, and a single person can lock all users out of login with 20 attempts a minute. |
+
+- **Everything lives in `/data`**: mount a volume there. TLS is the job of the proxy or platform in front.
+- **Run one instance.** The database is SQLite and login attempts are serialized inside one process;
+  more than one instance needs a different database first.
+- **Backups**: `docker exec parity dotnet Parity.Server.dll backup /data/backup-2026-10-26.db` writes a
+  consistent copy while the server keeps running (SQLite `VACUUM INTO`; it never overwrites a file and
+  never creates a missing database). Copy it off the machine. To restore: stop the server, put the copy
+  where the database was, start it again.
+- **Uptime**: `GET /healthz` is anonymous and answers `ok` only when the database answers, `503` otherwise.
+
+### The iron rule: the cloud never runs a browser
+
+`Parity.Server`'s only endpoint that takes in scan results is `POST /api/runs` (its other
+write endpoints only manage sign-in, invites, members, tokens and run deletion), and what it
+accepts is **a report that has already finished running**. There is no "give me a URL and I will go scan it"
+endpoint, and there will not be one: **scanning always happens on your own machine or in your
+CI**, where the page, the credentials and the localhost port already are.
+
+This is not an implementation detail — it is the security claim of the whole design. It is why
+the dashboard has **no SSRF surface at all**: it is never handed a URL to fetch. And it is
+enforced structurally rather than by policy — the server projects do not reference the engine
+at all, only `Parity.Report` (the report types, which have no package dependencies), so neither
+Playwright nor its driver is anywhere in the server's build output. A test walks the server's
+whole project-reference graph and turns CI red if any project in it references Playwright or
+the engine; another turns it red the moment server code references a Playwright type or the
+engine's capture side (`FidelityEngine`, `IImplementationSource`, or anything in
+`ImplementationSources.Web`, which is the code that opens Chromium).
+
 ## Local report UI (M3)
 
 ```sh
@@ -321,12 +438,12 @@ jobs:
       contents: read
       pull-requests: write   # lets the action post the fidelity report as a PR comment
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       # Start your site (or deploy to a preview URL and point the config's url at it)
       - run: |
           npm ci && npm run build
           npm run preview &   # e.g. serving on localhost:8080
-      - uses: HSU-YU-MING/cornhsu-parity@v1   # @v1 tracks the latest 1.x
+      - uses: HSU-YU-MING/cornhsu-parity@v2   # @v2 tracks the latest 2.x
         with:
           config: parity.config.json
           figma-token: ${{ secrets.FIGMA_TOKEN }}   # omit when the design source is a local JSON file
@@ -334,25 +451,49 @@ jobs:
 
 Behaviour:
 
-- **PR comment**: posts a fidelity report (score + gap table + **suggested fixes**) and keeps
+- **PR comment**: posts a fidelity report (score + gap table + **suggested fixes**, ending with a
+  "Report a misjudgment" link to the issue form — a link only, nothing is sent) and keeps
   updating that same comment instead of adding new ones — so PMs and reviewers see it without
   ever touching the tool.
 - **Blocks the PR**: gaps beyond `gate.failOn` → exit 1 → red PR. (**The comment is posted
   first, then the gate is enforced.**)
-- **Artifacts**: `report.json` plus the Markdown report are uploaded for download.
+- **Artifacts**: `report.json` plus the Markdown report are uploaded for download (artifact
+  name `parity-report` unless you set `artifact-name`; `report.json` and `parity-report.md` at its
+  root). `report.json` is picked up from `.parity/report.json` next to the config file — where
+  `check` writes it — even when `config` points into a subdirectory.
+- **Running it more than once per workflow run**: prefer a **matrix** (one job per site or config), and
+  give each call its own `artifact-name` (e.g. `parity-report-${{ matrix.site }}`). Each name gets its
+  own artifact and keeps its own PR comment; two calls with the same name collide on the artifact upload.
+  Two calls in **one job** work only while the first one passes: when its gate fails, the job stops at
+  that call's last step and the second call never runs (no report, no comment, no artifact for it).
+- **Anonymous usage statistics**: on by default ([what and why](#anonymous-usage-statistics));
+  `share-stats: false` turns them off. The job summary gets one line saying whether they were sent, or why not.
 
 Action inputs: `config` / `target` / `working-directory` / `version` / `figma-token` /
-`baseline` (regression mode) / `comment` (turn off the PR comment) / `upload-report`.
+`baseline` (regression mode) / `comment` (turn off the PR comment) / `upload-report` /
+`artifact-name` (default `parity-report`; letters, digits, `.`, `_`, `-`, at most 100 characters, not starting with `-` and not only dots) /
+`share-stats` (default `true`; exactly `true` or `false` — anything else stops the action before it installs Parity).
 
 > The action installs the tool with `dotnet tool install -g Cornhsu.Parity` (published on
-> nuget.org). This repo's own `.github/workflows/ci.yml` instead **builds from source** and runs
-> the offline demo as a self-check, so it does not depend on a published release.
+> nuget.org) — the latest 2.x when `version` is omitted, so `@v2` never jumps to a future 3.x,
+> or exactly the `version` you pass. **Within one job the tool is installed once per call into the same
+> global location, and a later call cannot install a lower version than an earlier one** (`dotnet tool`
+> refuses to downgrade) — e.g. a first call without `version` installs the latest 2.x, and a second call
+> with `version: 2.0.0` fails. Give every call in a job the same `version`, or use a matrix. This repo's own `.github/workflows/ci.yml` instead **builds from
+> source** and runs the offline demo as a self-check, so it does not depend on a published release.
+>
+> **Upgrading from `@v1`?** `v1` stays at 1.1.0, whose action installs the newest release of *any*
+> major when `version` is omitted — so an unpinned `@v1` workflow already runs 2.x. Switch to `@v2` and
+> work through the "upgrade required" list in the CHANGELOG's 2.0.0 entry, or set `version: 1.1.0` to
+> stay on 1.x for now.
 
 ## Report vocabulary (for anyone parsing `report.json`)
 
+- **Unknown keys** — consumers must ignore keys they do not recognize. Within 2.x, `report.json` only *gains* fields; existing keys are never removed, renamed or given a different type (that would be 3.0). Closed sets below never gain members within 2.x either.
 - `severity` — **closed set** (spelling and membership frozen): `none` / `minor` / `medium` / `serious` / `critical`. `status`: `mismatch` / `missing`.
 - `unmatched[].reason` — **open set**: parsers must tolerate unknown values; known spellings never change. Currently: `no-anchor`, `ambiguous-or-missing-text`, `randomized-id`, `size-implausible`.
 - `nodes[].matchedBy` — **open set**, same rule. Currently: `selector`, `explicit`, `auto-text`, `auto-name`, `auto-container`.
+- `direction` (top level, since 2.0.0) — **closed set**: `forward` (a normal `check`) / `reverse` (`check --reverse`: expected and actual swapped, never gated). Always written; files without it read as `forward`. Readers accept exactly the lowercase strings `"forward"` and `"reverse"` — any other value (other casing, a number, `null`) is an error, not a guess. `parity report` does not gate a reverse report, and `parity push` refuses one.
 
 ## Regression gating: baselines (M5)
 
@@ -387,17 +528,111 @@ file is released immediately), and the engine's `BaselineComparer` is a pure, un
 - [x] **M3** Local report UI (`parity serve --watch`, Kestrel bound to 127.0.0.1) + `parity map` interactive matching
 - [x] **M4** GitHub Action: a reusable composite action (`action.yml`) + this repo's own CI (build / test / offline-demo self-check)
 - [x] **M5** EF Core + SQLite baselines and history (regression gating + score trend) + `ImageDesignSource` (image + annotations + pixel sampling) + `parity snapshot` (freeze the current state as the baseline)
-- [ ] **M6** (optional) Cloud shell: public-URL scanning + SSRF protection
+- [ ] **M6** (optional) Cloud shell: public-URL scanning + SSRF protection — **deliberately
+  declined** (2026-07-18). This is *not* what M7 is: M7 never scans anything. The reasoning is
+  kept in [ROADMAP.md](ROADMAP.md).
+- [ ] **M7** Team dashboard shell (`Parity.Server` + `Parity.Server.Data` + `web/`) — **in
+  progress, not yet released.** `parity push` (**experimental**: the server is not publicly deployed
+  yet, so the command and its server protocol may change in a 2.x minor release and join the interface
+  freeze once the server ships) sends a finished `report.json` to a server you host yourself; the dashboard renders the gaps as an engineering blueprint drawn from the
+  measured coordinates (no screenshot upload), an overview and score trend per project and
+  route, and accounts / project roles / invite links. It also takes XamlContrast reports
+  ([one dashboard, two tools](#one-dashboard-two-tools)). Its own internal M1–M4.6 are done; of its
+  M5, the deployment groundwork is done (a Docker image, the public URL, persisted sign-in keys,
+  online backups), the actual hosting (a host, a domain, TLS) is not. **It receives
+  reports, it never scans** — see the iron rule above.
 
 > Open work, known blind spots and the next priorities are in [ROADMAP.md](ROADMAP.md);
 > version history is in [CHANGELOG.md](CHANGELOG.md).
 
+## Anonymous usage statistics
+
+From 2.1.0, `parity check` sends **anonymous usage statistics**, once per run — **on by default, in CI
+too**. They are counts and score ranges used for **academic research** on how far real
+implementations drift from their designs; only aggregate results are published. The public data page — what is collected, what it is used
+for, how long it is kept — is **<https://stats.cornhsu.com/>**.
+
+**When.** Only `parity check`, and only when it produced a report (exit 0, 1 or 3). `--reverse`,
+`--stats-preview`, every other command and any run that ends in exit 2 send nothing.
+
+**Everything that is sent:**
+
+| Field | Meaning |
+|---|---|
+| `schema`, `tool` | Always `1` and `"parity"` |
+| `toolVersion` | The Parity version, e.g. `2.1.0` (no commit hash) |
+| `os` | `windows`, `linux`, `macos` or `other` |
+| `ci` | Whether `CI` or `GITHUB_ACTIONS` is `true` |
+| `projectId` | `null`, unless you set `stats.projectId` yourself (see below) |
+| `data.score` | The fidelity score `check` printed (0–100) |
+| `data.gateFailed` | Whether `check`'s exit code was not 0 (so `--baseline` and exit 3 count as they did in your CI) |
+| `data.pages` | How many targets the report covers |
+| `data.designSource` | `figma`, `snapshot` (a file written by `parity snapshot`), `file` (any other design JSON) or `image` |
+| `data.designNodes`, `data.matched` | Design nodes and matched nodes, summed over all pages |
+| `data.severity` | Gap counts per severity: `critical`, `serious`, `medium`, `minor` |
+| `data.props` | For each property with at least one gap: how many gaps, how many were `missing`, and how many fall in each range of `abs(delta)` — px for lengths (`offsetX`/`offsetY`, size, padding, `itemSpacing`, `cornerRadius`, `fontSize`, `lineHeight`, `letterSpacing`: <1, 1–2, 2–4, 4–8, 8–16, 16–32, ≥32), ΔE for `color`/`background` (<1, 1–2, 2–5, 5–10, 10–20, ≥20), and weight steps for `fontWeight` (<100, 100–200, 200–300, ≥300). `fontFamily` has no ranges, only counts |
+
+**Never sent:** URLs, routes, page or layer names, selectors, file names or paths, screenshots, colour
+values, design content, tokens, repository names or IDs, user names, machine names. The request has no
+User-Agent and no cookies. The collector does not store IP addresses or the time a record arrived (only
+its date); Cloudflare, which hosts the collector, sees the connection address at its edge, as any network
+provider does.
+
+**No ID unless you add one.** Without `stats.projectId`, nothing links one run to another or to you —
+which also means a record cannot be picked out and deleted afterwards. If you want your runs counted as
+one project (and deletable on request), make up a random ID — for example `openssl rand -hex 12`, or
+`[guid]::NewGuid().ToString('N')` in PowerShell. Parity never derives one from your repository, paths or
+machine, and an ID that is not 16–64 characters of `A–Z a–z 0–9 _ -` is a config error (exit 2):
+
+```jsonc
+"stats": {
+  "share": true,                                  // false turns statistics off
+  "projectId": "REPLACE-with-your-own-random-id"  // optional; never copy someone else's
+}
+```
+
+**Preview.** `parity check --stats-preview` runs the check as usual, sends nothing, and prints the exact
+JSON to stderr, followed by whether it would be sent — or why not. The exit code, stdout and the report
+files are unchanged.
+
+**Turning it off.** Any one of these is enough; they are checked in this order, and the first that says
+no wins:
+
+1. `DO_NOT_TRACK` set to anything except `0` or `false` — always wins.
+2. `CORNHSU_SHARE_STATS` (shared with [XamlContrast](https://github.com/HSU-YU-MING/cornhsu-xamlcontrast))
+   or `PARITY_SHARE_STATS` set to `false` — in fact any value other than `1`, `true`, `yes` or `on`, so a
+   typo errs on the side of *not* sending.
+3. `"stats": { "share": false }` in `parity.config.json`.
+4. The GitHub Action's `share-stats: false` (it sets `PARITY_SHARE_STATS=false`).
+5. Builds from source and other non-release builds (any version starting with `0.0.0-`, such as `0.0.0-dev`) never send.
+
+Like every other key in the config, a misspelt one is ignored: `"stats": { "shrae": false }` turns
+nothing off. `--stats-preview` tells you whether a switch took effect.
+
+**Notice.** The first time `check` sends on a machine, it prints a short notice to stderr and leaves a
+marker file, `cornhsu/parity-stats-notice` in your user settings directory (`%APPDATA%` on Windows,
+`~/.config` elsewhere), so the notice is not repeated — delete the file to see it again. In CI it prints
+one line every time statistics were sent. Nothing is printed when nothing is sent, and nothing ever goes
+to stdout. The GitHub Action also writes one line to the job summary: sent, or why not.
+
+**Cost.** The request waits at most 1.5 s to connect and 3 s in total, is never retried and never follows
+a redirect. When it fails — offline, a firewall, the collector is down — nothing is printed and nothing
+else changes: the exit code, stdout, the report files and the PR comment are exactly what they would have
+been.
+
 ## Security
 
+- **What Parity connects to**: the Figma API (only with a Figma design source), the dashboard you name
+  for `parity push`, and `stats.cornhsu.com` for the [anonymous usage statistics](#anonymous-usage-statistics)
+  of `parity check` (unless turned off). The page under test is opened by the local browser. Nothing else.
 - The Figma token comes from an environment variable (`env:FIGMA_TOKEN`); it never reaches a log
   and never goes in a URL (it is sent as the `X-Figma-Token` header).
-- Fetched frames are cached in `.parity/cache` (gitignored), so re-runs do not hit Figma and can
-  compare offline.
+- Fetched frames are cached in `.parity/cache` (add `.parity/` to your `.gitignore`), so re-runs do
+  not hit Figma and can compare offline.
+- The local report UI binds 127.0.0.1 only, and additionally rejects unexpected `Host` headers
+  (DNS rebinding) and cross-origin `POST`s (CSRF).
+- **The team dashboard never scans anything** — it only receives finished reports, so it has no
+  SSRF surface. See [the iron rule](#the-iron-rule-the-cloud-never-runs-a-browser).
 
 ## See also
 
@@ -413,8 +648,12 @@ same author, built on the same philosophy: numeric checks that gate CI. Parity a
 implementation match the design?**" (fidelity); XamlContrast answers "**can anyone actually see
 what we built?**" (WCAG contrast, scanned statically from XAML source). One guards fidelity, the
 other readability — and its static color resolution is also the groundwork for the expected values
-of this project's future `WpfImplementationSource` desktop adapter.
+of this project's future `WpfImplementationSource` desktop adapter (see §4.5 of the
+[project plan](docs/Parity專案規畫書.md), in Traditional Chinese).
 
 ## License
 
-MIT
+MIT. The NuGet and npm packages also bundle third-party components (Playwright, ImageSharp,
+SQLite and others; the npm packages also include the .NET runtime). Their licenses are listed in
+[THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md), which ships inside the NuGet package and every npm
+platform package.

package/bin/parity.js

@@ -17,24 +17,31 @@
 const { spawnSync } = require("node:child_process");
 const path = require("node:path");
 
-// 平台 → 子套件名 / 執行檔名
+// 平台 → 子套件名 / 執行檔名。必須與 npm/prepare.mjs 的 TARGETS 一一對應
+// (RepoInvariantsTests 會比對;1.1.0 漏了兩個 arm64,平台包有發佈、npx 卻說不支援)
 const TARGETS = {
   "win32 x64": { pkg: "@cornhsu/parity-win32-x64", bin: "parity.exe" },
+  "win32 arm64": { pkg: "@cornhsu/parity-win32-arm64", bin: "parity.exe" },
   "linux x64": { pkg: "@cornhsu/parity-linux-x64", bin: "parity" },
+  "linux arm64": { pkg: "@cornhsu/parity-linux-arm64", bin: "parity" },
   "darwin x64": { pkg: "@cornhsu/parity-darwin-x64", bin: "parity" },
   "darwin arm64": { pkg: "@cornhsu/parity-darwin-arm64", bin: "parity" },
 };
 
+// 啟動腳本自己的錯誤一律 exit 2:CLI 的契約是 0 通過 / 1 落差超 gate / 2 執行錯誤 / 3 可信度不足,
+// 回 1 會被 CI 讀成「設計還原度不合格」。訊息用英文,與 CLI 本體一致(0.12.0 起)。
+const EXECUTION_ERROR = 2;
+
 const key = `${process.platform} ${process.arch}`;
 const target = TARGETS[key];
 
 if (!target) {
   console.error(
-    `Cornhsu.Parity 沒有 ${key} 的預先建置版本。\n` +
-      `目前支援:${Object.keys(TARGETS).join("、")}\n` +
-      `其他平台請改用 .NET 版本:dotnet tool install -g Cornhsu.Parity`
+    `cornhsu-parity: there is no prebuilt build for ${key}.\n` +
+      `Supported: ${Object.keys(TARGETS).join(", ")}\n` +
+      `On other platforms use the .NET tool instead: dotnet tool install -g Cornhsu.Parity`
   );
-  process.exit(1);
+  process.exit(EXECUTION_ERROR);
 }
 
 let binary;
@@ -45,11 +52,11 @@ try {
   binary = path.join(path.dirname(manifest), "bin", target.bin);
 } catch {
   console.error(
-    `找不到平台套件 ${target.pkg}。\n` +
-      `可能是安裝時加了 --no-optional,或安裝過程中斷。\n` +
-      `請重新安裝:npm install cornhsu-parity`
+    `cornhsu-parity: the platform package ${target.pkg} is not installed.\n` +
+      `It is an optional dependency, so the install may have skipped it (--no-optional / --omit=optional) or been interrupted.\n` +
+      `Reinstall: npm install cornhsu-parity`
   );
-  process.exit(1);
+  process.exit(EXECUTION_ERROR);
 }
 
 const result = spawnSync(binary, process.argv.slice(2), {
@@ -62,8 +69,8 @@ const result = spawnSync(binary, process.argv.slice(2), {
 });
 
 if (result.error) {
-  console.error(`無法執行 ${binary}:${result.error.message}`);
-  process.exit(1);
+  console.error(`cornhsu-parity: could not run ${binary}: ${result.error.message}`);
+  process.exit(EXECUTION_ERROR);
 }
 
 // 被訊號中斷時 status 會是 null;轉成慣例的 128+signal,別讓 CI 誤判為成功

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cornhsu-parity",
-  "version": "1.1.0",
+  "version": "2.1.0",
   "description": "Property-Level Design QA that can gate your CI. Compares real numeric values from your Figma file against the rendered UI and fails the PR when the implementation drifts from the design.",
   "keywords": [
     "figma",
@@ -31,14 +31,14 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "optionalDependencies": {
-    "@cornhsu/parity-win32-x64": "1.1.0",
-    "@cornhsu/parity-win32-arm64": "1.1.0",
-    "@cornhsu/parity-linux-x64": "1.1.0",
-    "@cornhsu/parity-linux-arm64": "1.1.0",
-    "@cornhsu/parity-darwin-x64": "1.1.0",
-    "@cornhsu/parity-darwin-arm64": "1.1.0"
+    "@cornhsu/parity-win32-x64": "2.1.0",
+    "@cornhsu/parity-win32-arm64": "2.1.0",
+    "@cornhsu/parity-linux-x64": "2.1.0",
+    "@cornhsu/parity-linux-arm64": "2.1.0",
+    "@cornhsu/parity-darwin-x64": "2.1.0",
+    "@cornhsu/parity-darwin-arm64": "2.1.0"
   }
 }