@tractiontactics/tt-fidelity 0.2.1

package/AGENTS.md

@@ -0,0 +1,41 @@
+# Agent contract — `@tractiontactics/tt-fidelity`
+
+You are measuring a prototype against a TT WP Theme draft. **You are not the grader.**
+
+## Hard rules
+
+1. **Run the checker.** Paste `QUEUE.md` or the WORK PLAN from stdout / `fidelity.json`. Do not invent a fidelity report from memory or from a successful API write.
+2. **Exit 0 means measured pixel parity** for compared sections at requested viewports (`--mode full` or `pixel`). `--mode styles` exit 0 is triage only — never claim the page is done.
+3. **"Matched" means measured.** Unverifiable claims must be labelled as such.
+4. **One WORK PLAN task**, then re-run with `--round` incremented. Do not batch speculative fixes.
+5. **Never apply a rule site-wide** until `instances_per_page` (in clusters / QUEUE) shows it is a real default. Blanket CSS from a rare seam creates hundreds of false findings.
+6. **Cache:** the tool cache-busts by default. If draft and live disagree, purge host/CDN and re-run — do not “fix” ghosts.
+7. **Escalate** tokens → block Style/Advanced → minimal `PUT /custom-css` → theme change → HTML template. Cite `ttRowId` / `ttBlockIds` when present.
+
+## Loop
+
+```bash
+npx @tractiontactics/tt-fidelity \
+  --proto "<PROTOTYPE_URL>" \
+  --draft "<DRAFT_PREVIEW_URL>" \
+  --viewports 1280,768,390 \
+  --out ./fidelity \
+  --mode full \
+  --round N \
+  --max-rounds 6
+```
+
+- Exit **0** → page (or chrome scope) done for this URL pair.
+- Exit **1** → do TASK 1 from the plan; re-measure.
+- Exit **2** → fix install / auth / `--roles`; do not guess missing sections.
+- Exit **3** → stop; report residuals; consider history restore.
+
+## Large sites
+
+Compare one prototype page to its draft at a time, or pass `--pages`. Use `--scope chrome` then `--scope content`. Prefer `--only-failing` after the first full pass.
+
+## Forbidden
+
+- Certifying “100% parity” without exit 0 from the pixel gate.
+- Substituting fetch-only CSS analysis for the main path.
+- Ignoring section count mismatches (structural first).

package/README.md

@@ -0,0 +1,150 @@
+# @tractiontactics/tt-fidelity
+
+Section-first visual fidelity for prototype → TT WP Theme builds.
+
+**Pixel / perceptual section screenshots are the acceptance gate.** Computed styles explain *what* to change. Exit `0` means every compared section is under the clean threshold — not that an agent believed the page matched.
+
+```bash
+npm i -D playwright && npx playwright install chromium
+
+npx @tractiontactics/tt-fidelity \
+  --proto "https://prototype.example.com/page" \
+  --draft "https://site.example.com/?p=12&preview=true" \
+  --viewports 1280,768,390 \
+  --out ./fidelity \
+  --mode full
+```
+
+Monorepo:
+
+```bash
+node tools/fidelity-diff/fidelity-diff.mjs --proto … --draft … --out ./fidelity
+npm run fidelity:test   # self-tests
+```
+
+## Publishing to npm
+
+Do **not** use a 2FA-bypass granular access token (deprecated / blocked for publish).
+
+**First publish** (creates the package). npm requires **account 2FA** or a granular token that can publish — a plain login session is not enough.
+
+1. Enable 2FA on your npm account (if not already):  
+   https://www.npmjs.com/settings/~/account/security → Authenticator app  
+   (or `npm profile enable-2fa auth-and-writes` and follow prompts)
+2. Create a **Granular Access Token** (not classic):  
+   https://www.npmjs.com/settings/~/tokens → Generate new token → Granular  
+   - Permissions: **Read and write**  
+   - Packages / scopes: `@tractiontactics` (or “All packages” for the org)  
+   - **Bypass 2FA:** leave **off** if your account 2FA works with `--otp`; turn **on** only for a one-shot first publish if interactive OTP still fails (token is being deprecated for publish ~2027 — replace with Trusted Publishing after)
+3. Point npm at that token and publish with a **real** 6-digit authenticator code (not the placeholder `XXXXXX`):
+
+```bash
+cd tools/fidelity-diff
+npm config set //registry.npmjs.org/:_authToken=npm_YOUR_TOKEN_HERE
+npm whoami
+npm publish --access public --otp=123456   # real code from your authenticator
+```
+
+**Later releases:** prefer GitHub Actions trusted publishing (OIDC).
+
+1. On [npmjs.com](https://www.npmjs.com) → package → **Settings → Trusted Publisher**  
+   - GitHub repo: `tractiontactics/tt-wp-platform`  
+   - Workflow filename: `publish-tt-fidelity.yml`
+2. Bump `version` in this `package.json`, commit, tag, push:
+   ```bash
+   git tag tt-fidelity-v0.2.2
+   git push origin tt-fidelity-v0.2.2
+   ```
+   Workflow: [`.github/workflows/publish-tt-fidelity.yml`](../../.github/workflows/publish-tt-fidelity.yml) — no `NPM_TOKEN`.
+
+Until the package is published, agents should use the monorepo path above.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| **0** | Pixel gate clean (or styles clean in `--mode styles` only) |
+| **1** | Differences remain — continue the loop |
+| **2** | Could not run / low landmark coverage |
+| **3** | `--max-rounds` reached with diffs still present |
+
+## Modes
+
+| Mode | Exit 0 from | Styles |
+| --- | --- | --- |
+| `full` (default) | Section pixel scores | Explainer + work plan enrichment |
+| `pixel` | Section pixel scores | Skipped |
+| `styles` | Computed-style diffs (triage only) | Authoritative for this mode only |
+
+**Do not treat `--mode styles` exit 0 as visual parity.** Gradients, borders via `background-image`, and inline SVG are invisible to a property census.
+
+## Severity bands (pixel score = differing pixels / area)
+
+| Band | Score | Meaning |
+| --- | --- | --- |
+| clean | < 0.10 | Pass |
+| fix | 0.10–0.40 | Fix settings / tokens |
+| rebuild | ≥ 0.40 | Rebuild section |
+
+Override fail cut with `--threshold` (default `0.10`).
+
+## CLI
+
+| Flag | Purpose |
+| --- | --- |
+| `--proto` / `--draft` | Single URL pair |
+| `--pages <file>` | JSON `[{id,proto,draft}]` or `proto\|draft` lines |
+| `--out <dir>` | `fidelity.json`, `QUEUE.md`, `shots/sections/…` |
+| `--mode full\|pixel\|styles` | See above |
+| `--viewports` | Default `1280,768,390` |
+| `--scope full\|chrome\|content` | Section / landmark scope |
+| `--cache-bust` / `--no-cache-bust` | Default **on** (`tt_nocache=`); logs cache headers |
+| `--concurrency <n>` | Parallel pages |
+| `--only-failing` | Skip sections clean in prior `fidelity.json` |
+| `--roles` | Landmark map when defaults miss |
+| `--round` / `--max-rounds` | Agent loop |
+| `--json` | Extra copy of the document |
+| Auth / cookies | `--auth`, `--draft-auth`, `--cookie` |
+
+## Programmatic API
+
+```js
+import { runFidelity } from '@tractiontactics/tt-fidelity';
+
+const result = await runFidelity({
+  proto: 'https://…',
+  draft: 'https://…',
+  viewports: [1280, 390],
+  mode: 'full',
+  outDir: './fidelity'
+});
+// result.exitCode, result.summary, result.pages, result.clusters, result.document, result.text
+```
+
+Schema: [`fidelity.schema.json`](./fidelity.schema.json) (`schema_version: 2`).
+
+## How measurement works
+
+1. Load both URLs at the same viewport (cache-busted by default).
+2. Discover **sections**: draft prefers `.tt-pb-row` / `data-tt-row`; prototype prefers `main > section`.
+3. Align by document order; count mismatch → structural task.
+4. Screenshot each pair, normalize canvas, `pixelmatch` → score + band.
+5. Optionally capture landmark computed styles (explainer).
+6. Cluster failing headings across `--pages` → `QUEUE.md` leverage list.
+7. Emit TT ids (`data-tt-row` / `data-tt-block`) when present for `PUT /pages/{id}/layout`.
+
+## Agent contract
+
+See **[AGENTS.md](./AGENTS.md)**. Short version:
+
+1. Run the checker; paste `QUEUE.md` / JSON — do not self-author “100% parity.”
+2. Exit 0 = pixel gate. Styles alone ≠ done.
+3. One WORK PLAN task → re-measure → increment `--round`.
+4. Never apply a finding site-wide until `instances_per_page` justifies it.
+5. Trust `--cache-bust` (default on).
+
+Platform docs: [fidelity-measurement.md](../../WordPress%20Theme/Plugin/docs/fidelity-measurement.md), [prototype-to-site.md](../../WordPress%20Theme/Plugin/docs/prototype-to-site.md).
+
+## Theme hooks (0.15.3+)
+
+Builders emit additive `data-tt-row` / `data-tt-block` with layout JSON ids (stable even when `advanced.custom_id` overrides HTML `id`). Paint unchanged.

package/bin/tt-fidelity.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../fidelity-diff.mjs';

package/fidelity-diff.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * Backward-compatible entry — delegates to src/cli.mjs
+ */
+import { main } from './src/cli.mjs';
+
+main(process.argv.slice(2));

package/fidelity.schema.json

@@ -0,0 +1,77 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://tractiontactics.com/schemas/fidelity.v2.json",
+	"title": "TT Fidelity Report",
+	"type": "object",
+	"required": ["schema_version", "mode", "exit_code", "pages"],
+	"properties": {
+		"schema_version": { "const": 2 },
+		"package_version": { "type": "string" },
+		"mode": { "enum": ["full", "pixel", "styles"] },
+		"threshold": {
+			"type": "object",
+			"properties": {
+				"clean": { "type": "number" },
+				"fix": { "type": "number" },
+				"rebuild": { "type": "number" }
+			}
+		},
+		"round": { "type": "integer" },
+		"max_rounds": { "type": "integer" },
+		"exit_code": { "type": "integer", "enum": [0, 1, 2, 3] },
+		"summary": { "type": "object" },
+		"clusters": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"properties": {
+					"key": { "type": "string" },
+					"label": { "type": "string" },
+					"pages": { "type": "integer" },
+					"avgScore": { "type": "number" },
+					"instancesPerPage": { "type": "number" }
+				}
+			}
+		},
+		"work_plan": { "type": "array" },
+		"pages": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"required": ["id", "proto", "draft", "viewports"],
+				"properties": {
+					"id": { "type": "string" },
+					"proto": { "type": "string" },
+					"draft": { "type": "string" },
+					"viewports": {
+						"type": "array",
+						"items": {
+							"type": "object",
+							"properties": {
+								"width": { "type": "integer" },
+								"sections": {
+									"type": "array",
+									"items": {
+										"type": "object",
+										"properties": {
+											"index": { "type": "integer" },
+											"protoSelector": { "type": "string" },
+											"draftSelector": { "type": "string" },
+											"ttRowId": { "type": ["string", "null"] },
+											"ttBlockIds": { "type": "array", "items": { "type": "string" } },
+											"score": { "type": "number" },
+											"band": { "enum": ["clean", "fix", "rebuild"] },
+											"shotPaths": { "type": "object" }
+										}
+									}
+								},
+								"cacheHeaders": { "type": "object" },
+								"coverage": { "type": "object" }
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

package/fixtures/draft-opaque.html

@@ -0,0 +1,57 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Fixture draft — opaque markup</title>
+<!--
+  Same visual page as proto.html but with markup that defeats convention-based
+  selectors: no <header>/<nav>/<main>/<footer>, no ARIA roles, and hashed
+  class names of the kind a CSS-modules or utility-first build emits.
+
+  Used to prove fidelity-diff does NOT report a false "clean" when its role
+  selectors match nothing. It should report low coverage loudly instead.
+-->
+<style>
+  * { box-sizing: border-box; }
+  body { margin: 0; font-family: system-ui, sans-serif; color: #0f172a; }
+  .Hdr_a1b2 { display: flex; justify-content: space-between; align-items: center;
+              padding: 16px 24px; background: #fff; border-bottom: 1px solid #e2e8f0; }
+  .Nav_c3d4 { display: flex; gap: 16px; }
+  .Nav_c3d4 > .Lnk_e5f6 { font-size: 14px; font-weight: 600; color: #0f172a;
+                          text-decoration: none; padding: 8px 4px; }
+  .Wrap_g7h8 { max-width: 1280px; margin: 0 auto; padding: 0 40px; }
+  .Ttl_i9j0 { font-size: 36px; line-height: 1.1; margin: 64px 0 24px; }
+  .Cta_k1l2 { display: inline-block; background: #059669; color: #fff;
+              padding: 12px 24px; border-radius: 4px; font-size: 18px; font-weight: 700;
+              text-decoration: none; }
+  .Blk_m3n4 { padding: 40px 0; }
+  .Grd_o5p6 { display: grid; grid-template-columns: repeat(2, 1fr); gap: 32px; }
+  .Itm_q7r8 { padding: 20px; border-radius: 8px; background: #f8fafc; }
+  .Ftr_s9t0 { padding: 48px 40px; background: #0f172a; color: #fff; margin-top: 80px; }
+</style>
+</head>
+<body>
+<div class="Hdr_a1b2">
+  <div class="Brand_u1v2">Acme</div>
+  <div class="Nav_c3d4">
+    <a class="Lnk_e5f6" href="/">Home</a>
+    <a class="Lnk_e5f6" href="/services">Services</a>
+    <a class="Lnk_e5f6" href="/about">About</a>
+  </div>
+</div>
+<div class="Wrap_g7h8">
+  <div class="Ttl_i9j0">Trusted local experts</div>
+  <a class="Cta_k1l2" href="/quote">Get a quote</a>
+  <div class="Blk_m3n4">
+    <div class="Sub_w3x4">What we do</div>
+    <div class="Grd_o5p6">
+      <div class="Itm_q7r8"><div>Repairs</div><p>Fast and tidy.</p></div>
+      <div class="Itm_q7r8"><div>Installs</div><p>Done properly.</p></div>
+      <div class="Itm_q7r8"><div>Servicing</div><p>On schedule.</p></div>
+    </div>
+  </div>
+</div>
+<div class="Ftr_s9t0">© Acme</div>
+</body>
+</html>

package/fixtures/draft.html

@@ -0,0 +1,61 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Fixture draft</title>
+<!--
+  Deliberate drift from proto.html, used to verify fidelity-diff reports the
+  right numbers. Expected findings:
+    fonts   : body/nav/h1 family Georgia -> system-ui; h1 48px -> 36px; nav 16px -> 14px
+    menus   : header padding 24/40 -> 16/24; nav gap 32px -> 16px; nav-item count 4 -> 3
+    colours : .btn background #047857 -> #059669; .btn radius 8px -> 4px; card radius 12px -> 8px
+    padding : .btn 16/32 -> 12/24; .card 32px -> 20px; section 64px -> 40px
+    flow    : .cards grid 3 cols -> 2 cols
+    gaps    : .cards gap 24px -> 32px
+    widths  : main max-width 1120px -> 1280px
+-->
+<style>
+  * { box-sizing: border-box; }
+  body { margin: 0; font-family: system-ui, sans-serif; color: #0f172a; }
+  header { display: flex; justify-content: space-between; align-items: center;
+           padding: 16px 24px; background: #ffffff; border-bottom: 1px solid #e2e8f0; }
+  nav { display: flex; gap: 16px; }
+  nav a { font-family: system-ui, sans-serif; font-size: 14px; font-weight: 600;
+          color: #0f172a; text-decoration: none; padding: 8px 4px; }
+  main { max-width: 1280px; margin: 0 auto; padding: 0 40px; }
+  h1 { font-size: 36px; line-height: 1.1; letter-spacing: -0.02em; margin: 64px 0 24px; }
+  .btn { display: inline-block; background: #059669; color: #ffffff;
+         padding: 12px 24px; border-radius: 4px; font-size: 18px; font-weight: 700;
+         text-decoration: none; }
+  section { padding: 40px 0; }
+  .cards { display: grid; grid-template-columns: repeat(2, 1fr); gap: 32px; }
+  .card { padding: 20px; border-radius: 8px; background: #f8fafc;
+          box-shadow: 0 1px 3px rgba(0,0,0,0.08); }
+  footer { padding: 48px 40px; background: #0f172a; color: #ffffff; margin-top: 80px; }
+</style>
+</head>
+<body>
+<header>
+  <div class="logo">Acme</div>
+  <nav>
+    <a href="/">Home</a>
+    <a href="/services">Services</a>
+    <a href="/about">About</a>
+  </nav>
+</header>
+<main>
+  <h1>Trusted local experts</h1>
+  <a class="btn" href="/quote">Get a quote</a>
+  <section>
+    <h2>What we do</h2>
+    <div class="cards">
+      <div class="card"><h3>Repairs</h3><p>Fast and tidy.</p></div>
+      <div class="card"><h3>Installs</h3><p>Done properly.</p></div>
+      <div class="card"><h3>Servicing</h3><p>On schedule.</p></div>
+    </div>
+  </section>
+</main>
+<footer>© Acme</footer>
+</body>
+</html>

package/fixtures/pages/cluster-a-draft.html

@@ -0,0 +1,19 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Cluster page A draft</title>
+<style>
+  body { margin: 0; font-family: system-ui, sans-serif; }
+  section { padding: 40px; background: #f1f5f9; }
+  .cta { padding: 40px; background: #94a3b8; color: #fff; }
+</style>
+</head>
+<body>
+<main>
+  <section><h2>Welcome A</h2></section>
+  <section class="cta"><h2>Prefer to talk it through?</h2></section>
+</main>
+</body>
+</html>

package/fixtures/pages/cluster-a-proto.html

@@ -0,0 +1,19 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Cluster page A</title>
+<style>
+  body { margin: 0; font-family: system-ui, sans-serif; }
+  section { padding: 40px; background: #f1f5f9; }
+  .cta { padding: 40px; background: #047857; color: #fff; }
+</style>
+</head>
+<body>
+<main>
+  <section><h2>Welcome A</h2></section>
+  <section class="cta"><h2>Prefer to talk it through?</h2></section>
+</main>
+</body>
+</html>

package/fixtures/pages/cluster-b-draft.html

@@ -0,0 +1,19 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Cluster page B draft</title>
+<style>
+  body { margin: 0; font-family: system-ui, sans-serif; }
+  section { padding: 40px; background: #fff; }
+  .cta { padding: 40px; background: #cbd5e1; color: #fff; }
+</style>
+</head>
+<body>
+<main>
+  <section><h2>Welcome B</h2></section>
+  <section class="cta"><h2>Prefer to talk it through?</h2></section>
+</main>
+</body>
+</html>

package/fixtures/pages/cluster-b-proto.html

@@ -0,0 +1,19 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Cluster page B</title>
+<style>
+  body { margin: 0; font-family: system-ui, sans-serif; }
+  section { padding: 40px; background: #fff; }
+  .cta { padding: 40px; background: #047857; color: #fff; }
+</style>
+</head>
+<body>
+<main>
+  <section><h2>Welcome B</h2></section>
+  <section class="cta"><h2>Prefer to talk it through?</h2></section>
+</main>
+</body>
+</html>

package/fixtures/pages/cluster-pages.json

@@ -0,0 +1,12 @@
+[
+  {
+    "id": "cluster-a",
+    "proto": "REPLACE_PROTO_A",
+    "draft": "REPLACE_DRAFT_A"
+  },
+  {
+    "id": "cluster-b",
+    "proto": "REPLACE_PROTO_B",
+    "draft": "REPLACE_DRAFT_B"
+  }
+]

package/fixtures/pixel-diverge.html

@@ -0,0 +1,28 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Pixel diverge draft — gradient only</title>
+<style>
+  /* Same computed colour/padding as proto for sampled landmarks, but hero paints via gradient */
+  body { margin: 0; font-family: Georgia, serif; background: #fff; color: #111; }
+  main { max-width: 800px; margin: 0 auto; }
+  section { padding: 48px 24px; }
+  h2 { margin: 0 0 12px; font-size: 28px; }
+  p { margin: 0; line-height: 1.5; }
+  /* background-image is invisible to the colours bucket (background-color only) */
+  section:first-child {
+    background-color: #ffffff;
+    background-image: linear-gradient(135deg, #047857 0%, #0ea5e9 100%);
+    color: #fff;
+  }
+</style>
+</head>
+<body>
+<main>
+  <section><h2>Intro</h2><p>Same paint on both sides.</p></section>
+  <section><h2>Details</h2><p>Second section content.</p></section>
+</main>
+</body>
+</html>

package/fixtures/pixel-identical.html

@@ -0,0 +1,21 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Pixel identical proto</title>
+<style>
+  body { margin: 0; font-family: Georgia, serif; background: #fff; color: #111; }
+  main { max-width: 800px; margin: 0 auto; }
+  section { padding: 48px 24px; }
+  h2 { margin: 0 0 12px; font-size: 28px; }
+  p { margin: 0; line-height: 1.5; }
+</style>
+</head>
+<body>
+<main>
+  <section><h2>Intro</h2><p>Same paint on both sides.</p></section>
+  <section><h2>Details</h2><p>Second section content.</p></section>
+</main>
+</body>
+</html>

package/fixtures/proto.html

@@ -0,0 +1,51 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Fixture prototype</title>
+<style>
+  * { box-sizing: border-box; }
+  body { margin: 0; font-family: Georgia, serif; color: #0f172a; }
+  header { display: flex; justify-content: space-between; align-items: center;
+           padding: 24px 40px; background: #ffffff; border-bottom: 1px solid #e2e8f0; }
+  nav { display: flex; gap: 32px; }
+  nav a { font-family: Georgia, serif; font-size: 16px; font-weight: 600;
+          color: #0f172a; text-decoration: none; padding: 8px 4px; }
+  main { max-width: 1120px; margin: 0 auto; padding: 0 40px; }
+  h1 { font-size: 48px; line-height: 1.1; letter-spacing: -0.02em; margin: 64px 0 24px; }
+  .btn { display: inline-block; background: #047857; color: #ffffff;
+         padding: 16px 32px; border-radius: 8px; font-size: 18px; font-weight: 700;
+         text-decoration: none; }
+  section { padding: 64px 0; }
+  .cards { display: grid; grid-template-columns: repeat(3, 1fr); gap: 24px; }
+  .card { padding: 32px; border-radius: 12px; background: #f8fafc;
+          box-shadow: 0 1px 3px rgba(0,0,0,0.08); }
+  footer { padding: 48px 40px; background: #0f172a; color: #ffffff; margin-top: 80px; }
+</style>
+</head>
+<body>
+<header>
+  <div class="logo">Acme</div>
+  <nav>
+    <a href="/">Home</a>
+    <a href="/services">Services</a>
+    <a href="/about">About</a>
+    <a href="/contact">Contact</a>
+  </nav>
+</header>
+<main>
+  <h1>Trusted local experts</h1>
+  <a class="btn" href="/quote">Get a quote</a>
+  <section>
+    <h2>What we do</h2>
+    <div class="cards">
+      <div class="card"><h3>Repairs</h3><p>Fast and tidy.</p></div>
+      <div class="card"><h3>Installs</h3><p>Done properly.</p></div>
+      <div class="card"><h3>Servicing</h3><p>On schedule.</p></div>
+    </div>
+  </section>
+</main>
+<footer>© Acme</footer>
+</body>
+</html>

package/fixtures/roles-opaque.json

@@ -0,0 +1,13 @@
+[
+  ["header",   [".Hdr_a1b2", "header"], 1],
+  ["logo",     [".Brand_u1v2", ".logo"], 1],
+  ["nav",      [".Nav_c3d4", "nav"], 1],
+  ["nav-item", [".Nav_c3d4 > a", "nav a"], 8],
+  ["main",     [".Wrap_g7h8", "main"], 1],
+  ["h1",       [".Ttl_i9j0", "h1"], 1],
+  ["h2",       [".Sub_w3x4", "h2"], 4],
+  ["button",   [".Cta_k1l2", "a.button", ".btn"], 6],
+  ["section",  [".Blk_m3n4", "main > section"], 8],
+  ["card",     [".Itm_q7r8", ".card"], 6],
+  ["footer",   [".Ftr_s9t0", "footer"], 1]
+]