# Content parity: how it is checked

The owner's requirement: every page keeps exactly the same text, images, video and links, and SEO does not regress. This file explains how the team proves it, and what the tools do and do not count as a difference.

## Commands

| Command | What it does |
|---|---|
| `php scripts/parity/check.php` | Fetches all 15 rebuilt pages from `http://127.0.0.1:8105` and compares them with the original plus the approved changes (see below). Writes `docs/qa/parity-latest.md`. Exit code 1 on any difference. |
| `php scripts/parity/check.php --original` | Same, against the original only (lists every difference, approved or not). |
| `php scripts/parity/check.php --base=http://127.0.0.1:8101 home about` | Other server, selected pages. |
| `php scripts/parity/check.php --json` | Same result as JSON on stdout. |
| `php scripts/parity/check.php -v` | Also lists harmless differences (info). |
| `php scripts/parity/check.php --allow-missing` | Pages not built yet (HTTP 404) do not fail the run. |
| `php artisan test --filter=Parity` | Same comparison in-process (`tests/Feature/Parity/PageParityTest.php`); pages without a Blade view are skipped. `BaselineIntegrityTest` fails if anyone edits the baseline JSON by hand. |
| `php scripts/parity/baseline.php` | Rebuilds `scripts/parity/baseline/*.json` from `reference/html/`. Only needed when the extraction rules change. `--check` verifies the files are current. |
| `php scripts/parity/validate-baseline.php` | Independent cross-check: every word of the raw page text that the extractor did not keep is listed. |
| `php scripts/parity/selftest.php` | Proves the check catches defects (19 kinds of deliberate damage) and does not flag harmless re-implementations. |

## Approved differences (modernisation phase)

The owner approved eight improvements (`docs/MODERNISATION_BRIEF.md`) that change some text, headings, links, alt texts and meta. The baseline still describes the original and is **never edited** (`BaselineIntegrityTest`). The approved changes are a separate, reviewable layer:

| File | Contents |
|---|---|
| `scripts/parity/approved/_shared.json` | Changes on every page (footer headings h4 to h2, "Request A Demo", "Design Studio Tool", footer year, "Cookie settings", cookie notice text and buttons, cookie "Privacy Policy" link), with `except` where a page differs, plus the idea-2 rule for AVIF/WebP image variants |
| `scripts/parity/approved/{page}.json` | Changes on one page (meta, wording, heading levels, alt texts, Pricing/Design Studio table, FAQ and Talk to Sales strip, IDMS "Watch Video" link) |
| `scripts/parity/lib/Approved.php` | Format and rules (operations `meta`, `text`, `text-insert`, `heading`, `heading-insert`, `link`, `link-add`, `image-alt`, `image-remove`, `lottie-remove`, ...) |

Each entry has the old value, the new value, the idea number and a reason. `check.php` and `PageParityTest` build *expected = baseline + approved changes* and compare the page with it. So:

- an unapproved difference fails exactly as before;
- an approved change that is **not** on the page fails (the page still shows the old value, which the expected snapshot no longer has);
- an entry whose old value is not in the baseline (stale or mistyped approval) fails as `approved: approval entry does not apply to the baseline`; `count` pins the number of occurrences;
- an AVIF/WebP variant (`/media/_v/{path}-{ext}[-{N}w].{avif|webp}`) is accepted only when its source image is itself expected on the page.

`php scripts/parity/check.php --original` still compares with the untouched original (useful to list every difference the modernisation made). The report `docs/qa/parity-latest.md` lists, per page, the approved changes found and their count. Self-tests: `selftest.php` section 4 and `PageParityTest::test_approved_layer_catches_removed_words_and_reverted_changes` (a removed word, a reverted typo fix, a reverted footer year, a reverted alt text, a removed Decline button, an unknown image variant and a stale approval entry must all fail).

Not covered by text parity: content inside `data-parity-ignore` (the phone bar, the full-screen menu and the video pop-up), which is checked in the browser instead (`docs/QA_REPORT_MODERNISATION.md`).

## What is extracted (same rules on both sides)

From `<head>`: `<title>`, meta description, canonical, robots, `html lang`, all `og:*`/`article:*` and `twitter:*` metas, JSON-LD `@type`s.

From `<body>`, in document order:

- **Text blocks.** Text is collected per block-level element (`p`, `div`, `li`, `h1`-`h6`, `button`, `td`, ...); inline elements (`span`, `a`, `strong`, `em`, `br`) stay inside the block. Whitespace, non-breaking spaces and zero-width characters are normalised and HTML entities decoded. Case, punctuation and typos are kept exactly ("Test Drive Calender" must stay).
- **Headings** h1-h6 with level and text.
- **Links**: visible text (or `aria-label`, screen-reader text, image alt, title when the link has no visible text) and `href`.
- **Images**: `img` src and alt, inline `background-image` URLs, video posters.
- **Videos** (`video`/`source` src), **iframes** (src, title), **Lottie** JSON sources found in any attribute.

URL normalisation: `https://idealers.net/wp-content/uploads/...` becomes `/media/...`; `https://idealers.net/x/`, `http://127.0.0.1:8105/x/` and `/x/` are the same; a link to a configured page without its trailing slash (`/request-demo`) counts as the slash form (`/request-demo/`) because both reach the same page (the original linked four pages without the slash; linking to the slash form saves a redirect). External URLs are compared exactly.

## What is deliberately ignored

| Ignored | Why |
|---|---|
| `script`, `style`, `svg`, `noscript`, `template`, `head` contents in the body | Not content |
| Skip link ("Skip to content") | Navigation aid, both sites may have one |
| Screen-reader-only text (`screen-reader-text`, `elementor-screen-only`, `sr-only`, `visually-hidden`) and `aria-hidden="true"` subtrees, for text blocks | Not visible; it is still used as the name of icon-only links |
| A menu (element with "nav"/"menu" in a class, or `<nav>`) whose links all appeared in an earlier menu | The original renders the main menu twice (desktop + mobile). The rebuild's mobile copy is ignored by the same rule |
| Elements with `data-parity-ignore` | Escape hatch for a responsive duplicate the rule above does not catch. Listed in the report as info. It can only hide *extra* content: if it hides the only copy of something, that text shows as missing |
| Elementor elements hidden on desktop, tablet and mobile at once | Never visible. Only case: the "Stickers & Buyer Guide" section on `inventory-management`. The rebuild must **not** show it |
| Elementor spacers, shape dividers, overlays, mobile menu toggles, cookie-notice close icon, mouse-cursor widget | Plugin chrome, no content |
| Images under `/wp-content/plugins/` (The Plus device frames such as `desktop-imac-minimal.png`, alt "Plus desktop device") and, in the rebuild, `/media/devices/*` | The device frame is decoration supplied by the plugin; the screen images inside the frames *are* checked |
| Links with `href="#"` or `javascript:` | Dropdown toggles; the rebuild may use `<button>`. Their text is still checked as a text block |
| Link `target` | Reported as a warning only |

Special cases in the original: Elementor counters hold "0" in the HTML and count up with JavaScript, so the extractor uses the final value (`100%`, `+300`); the counter prefix/number/suffix render without spaces. Pricing old price / suffix, testimonial name / title and the cookie text / button are separate boxes on screen and are split into separate blocks.

## How differences are classified

The text blocks of both pages are aligned (longest common subsequence). Every stretch that does not match is classified:

| Result | Meaning | Fails? |
|---|---|---|
| missing text / extra text | Block only on one side | yes |
| changed text | Similar block with different wording; both versions and the word-level difference are shown | yes |
| text moved | Identical block in a different position (order changed) | yes |
| whitespace differs | Same characters, different spacing (words glued or split) | warning |
| same text, different block boundaries | E.g. two `<p>` merged into one: identical words, identical order | info |
| title / description / canonical differ, robots contains noindex | | yes |
| heading missing / extra / changed / level changed, number of h1 differs | | yes |
| missing / extra link, link text changed, link href changed | | yes |
| accessible name added to an icon-only link | Improvement | info |
| missing / extra image, alt text changed | | yes |
| alt added where the original had an empty alt | Improvement | info |
| video poster attribute missing | The original's own thumbnail image covers it | warning |
| missing / extra video or iframe, Lottie source missing | | yes |
| Open Graph / Twitter / JSON-LD / `lang` differences, `img` without `alt` attribute, iframe without `title` | SEO and accessibility hygiene | warning |

### Critical external URLs (explicit checks)

These are checked by exact string, in addition to the generic link diff, and are pinned in `BaselineIntegrityTest`:

| Page | What | URL |
|---|---|---|
| contact | idealers.app form iframe | `https://idealers.app/apply/idealers/embedded/contact` |
| request-demo | idealers.app form iframe | `https://idealers.app/apply/idealers/embedded/request_demo` |
| talk-to-sales | idealers.app form iframe | `https://idealers.app/apply/idealers/embedded/talk_to_sales` |
| pricing | Starter ($99/month), "Get Started" | `https://buy.stripe.com/28odULgNc3d70CIdQQ` |
| pricing | Premium ($199/month), "Get Started" | `https://buy.stripe.com/5kA4kb9kK00V2KQ4gh` |
| pricing | Ultimate ($399/month), "Get Started" | `https://buy.stripe.com/aEU3g7cwW8xr4SYdQS` |
| design-studio-tool | Designer ($39.99, was $79.99), "Order Now" | `https://buy.stripe.com/00gdUL7cCcNHdpubIL` |
| design-studio-tool | Marketer ($59.99, was $119.99), "Order Now" | `https://buy.stripe.com/eVa4kb40qaFz716cMQ` |
| design-studio-tool | Hands-Up ($99.99), "Order Now" | `https://buy.stripe.com/9AQ7wn54u8xr85a3ci` |

Each Stripe URL was matched to its plan by reading the pricing-table markup in `reference/html/` (plan title and price immediately before the button). The check also fails if the Stripe links appear in a different plan order, which would mean a button sits under the wrong plan. All six open in a new tab on the original (`target="_blank"`).

### Documented exceptions

- **Accepted additions** (`ParityComparer::ACCEPTED_EXTRA_TEXT`): text the rebuild must add, reported as info with the reason. Only one today: the cookie notice on `crm-system`. The saved original of that page (and the live page, checked 2026-11-17) has no cookie notice, unlike the other 14 pages; the rebuild shows it everywhere because the outline requires it and analytics consent depends on it.
- **Decorative backgrounds** (`asset_refs` in each baseline): images the original loads from its stylesheets or widget settings (hero backgrounds, custom mouse-cursor images) rather than from the HTML. If the rebuild puts one of these in an inline `background-image`, it is reported as info, not as an extra image. An extra `<img>` always fails.
- **JSON-LD subtypes**: `AboutPage`/`ContactPage` satisfy the original `WebPage`, `LocalBusiness` and similar satisfy `Organization`.

## Baseline sizes (original pages)

| Page | Text blocks | Links | Images | Headings | iframes | Videos |
|---|---:|---:|---:|---:|---:|---:|
| home | 93 | 57 | 14 | 24 | 0 | 0 |
| about | 55 | 41 | 7 | 12 | 0 | 1 |
| pricing | 95 | 44 | 4 | 11 | 0 | 0 |
| contact | 70 | 55 | 6 | 17 | 1 | 1 |
| idms-idealers-management-system | 77 | 41 | 11 | 19 | 0 | 0 |
| inventory-management | 60 | 41 | 6 | 15 | 0 | 0 |
| leads-center | 57 | 41 | 11 | 13 | 0 | 0 |
| website | 64 | 41 | 11 | 17 | 0 | 0 |
| marketing-tools | 74 | 41 | 9 | 19 | 0 | 0 |
| crm-system | 57 | 41 | 5 | 14 | 0 | 0 |
| design-studio-tool | 115 | 46 | 9 | 22 | 0 | 0 |
| request-demo | 55 | 47 | 6 | 12 | 1 | 1 |
| talk-to-sales | 51 | 41 | 5 | 10 | 1 | 1 |
| privacy-policy | 136 | 45 | 2 | 22 | 0 | 0 |
| terms-condition | 92 | 41 | 2 | 22 | 0 | 0 |

Every page includes the shared header (15 blocks: phone line and menu) and footer/pre-footer/cookie notice (about 38 blocks; `talk-to-sales` and `inventory-management` show a shorter pre-footer).

## How the baseline was validated

1. Read by hand against the HTML for home, about, pricing, contact, idms, design-studio-tool, privacy-policy and the short pages: no real content dropped, no plugin text kept.
2. `validate-baseline.php`: on every page the only words dropped from the raw body text are the skip link (3 words), the mobile copy of the menu (26 words), the three screen-reader names of the footer social icons, the counters' "0" placeholders, the carousel's screen-reader "Next/Previous" on design-studio-tool and, on inventory-management, the section hidden on every device. The only "added" words are the counter end values and one place where the original itself glues two words ("practicable.Your Rights" in the privacy policy; it is a `<strong>` inside the same paragraph, so it renders glued too).
3. `selftest.php`: each original page against its own baseline gives zero failures and zero warnings (except the expected "iframe has no title" accessibility warning); 19 deliberate defects are all caught; a hand-written rebuild of the about page with completely different markup passes.

## For builders

- Run `php scripts/parity/check.php --base=http://127.0.0.1:810X your-page` while you build. The report shows both versions for every change.
- If your mobile menu or another responsive duplicate is reported as extra text, add `data-parity-ignore` to the duplicate's root element (not to the visible desktop copy).
- Do not add visible text that the original does not have (for example a "Decline" button in the cookie notice); it will be reported as extra text and needs the owner's approval.

## Approved differences (dark redesign)

`scripts/parity/approved/home.json` has 16 more entries (idea `"dark"`) for the owner-approved home concept: five section-order moves (`text` run reorders and the +500 headings moved with `heading-remove` / `heading-insert`), two decorative images removed (`blank.webp`, `img-17.png`), four pictures the design adds (`image-add`, with their alt texts), and the decorative Lottie of the old leads section (`lottie-remove`, an operation added for this). Each entry carries its reason; the list and the judgement for each are in `docs/QA_REPORT_DARK.md`, item 1. The other 14 pages needed no new entries.
