# Reference-build parity + live runtime validation (ShopProQuote-style migrations)

Use this when the user asks to make a target web app behave the same as a known-good reference build (especially after backend swaps like Firebase → PocketBase).

## 1) Fastest parity path for HTML interaction bugs

If target pages have accumulated inline fallbacks (onclick handlers, duplicate modal managers, auth guard snippets) and behavior diverges from reference:

1. Back up target HTML files (`*.bak.*`).
2. Copy reference HTML files over target for the relevant pages.
3. Apply only deterministic backend bootstrap rewrites (e.g. `src="firebase.js"` → `src="pocketbase.js"`).
4. Verify parity by diffing with normalization (reference content + the one allowed rewrite).

This is usually faster and safer than manually removing dozens of injected handlers one-by-one.

## 2) Evidence-first runtime validation checklist

After parity sync, run real click-path checks and report explicit pass/fail evidence per action:

- Dashboard: open/close key modals (financial, tasks, create task)
- Repair Orders: tab switching (active/history/quote generator)
- Quote form: clear/save click-path (look for API request signals)
- Appointments: create modal open/submit/close + created item visible
- Customers: search/filter clear and edit/open flows (or report blocked by dataset)

Evidence format should include:

- button id clicked
- modal/content visibility before/after
- URL after navigation/login
- request counts or concrete DOM text signals

## 3) Environment workaround: Playwright on Ubuntu 26

On Ubuntu 26, `python -m playwright install chromium` may fail with unsupported-browser errors.

Reliable fallback used in-session:

1. `python3 -m pip install playwright`
2. `python3 -m playwright install chrome`
3. Launch with channel Chrome:

```python
browser = p.chromium.launch(channel='chrome', headless=True, args=['--ignore-certificate-errors'])
page = browser.new_page(ignore_https_errors=True)
```

Use this for local HTTPS self-signed targets like `https://127.0.0.1:3447`.

## 4) Flake-resistant validation for edit/delete flows

UI-only assertions are not enough for list/card actions (especially appointments/customers edit/delete). Use a two-layer check:

1. **Network assertion**: capture the expected request (e.g., `DELETE /api/collections/appointments/records/{id}`) and status.
2. **State assertion**: verify post-action backend state (`GET` returns `404` for deleted id) plus UI disappearance.

Also use robust targeting for action menus:

- re-query visible cards right before click (avoid stale handles)
- open action menu, then wait for concrete menu item visibility
- after click, wait for either success toast OR API-state change

If a run is inconsistent, report as automation flake unless backend state disproves deletion.

## 5) Reporting discipline

If blocked (auth/data/permissions), mark checks as `blocked` with exact reason.
Do not claim pass without concrete runtime evidence.