Add optional Microsoft Clarity heatmaps with privacy controls

[jimdc]

Summary

Adds an optional Microsoft Clarity integration for click and scroll heatmaps so the site owner can see which parts of the public UI are hard to use. The loader is dormant until a project id is configured — no live id is committed. When configured, Clarity loads asynchronously, fails soft if blocked, respects Do Not Track / Global Privacy Control, and masks form fields (including email) before any script runs.

Privacy posture (plain English)

CityScroll can load Microsoft Clarity to collect anonymous heatmaps of where people click and scroll, so hard-to-use parts of the site can be fixed. Form fields and typed text — including email — are masked and are not sent as plain text. Clarity does not load when a browser signals Do Not Track or Global Privacy Control, and the site works fully if Clarity is blocked or offline. Clarity is not used for advertising or personal profiles. First-party aggregate analytics and Cloudflare’s cookieless page-view totals remain separate.

Operator steps (project id)

Clarity requires a project under a Microsoft account. Until the id is set, the integration stays off.

1. Sign in at https://clarity.microsoft.com/ with the site owner’s Microsoft account.
2. Add a new project for cityscroll.org (and any live aliases you want measured).
3. Open Settings → Setup and copy the project id (also visible in the project URL: https://clarity.microsoft.com/projects/view/<PROJECT_ID>/).
4. Open Settings → Masking and set masking mode to Strict (entire page content masked; input content is always masked in every mode).
5. Optional but recommended for a civic site: under Settings → Setup → Advanced, turn Cookies off until a consent flow exists. Multi-page session stitching is weaker without cookies; heatmaps still work.
6. Enable the loader by one of:
   • Set CONFIGURED_PROJECT_ID in site/clarity.js to the real id and redeploy, or
   • Set window.CROL_CLARITY_PROJECT_ID = "<id>" in a small script before clarity.js, or
   • Add <meta name="crol-clarity-project-id" content="<id>"> on public pages.
7. Confirm in the browser Network tab that https://www.clarity.ms/tag/<id> loads when DNT/GPC are off, and does not load when Do Not Track or Global Privacy Control is on.
8. Spot-check a subscribe/feedback form: email fields carry data-clarity-mask="true".

What changed

• site/clarity.js — config path, DNT/GPC skip, input masking, non-blocking tag inject
• All public HTML pages load clarity.js after first-party analytics.js
• Email fields on home subscribe and About feedback are masked in markup
• About → Privacy copy updated in English and all ten shipping locales
• SECURITY.md and AGENTS.md note the optional third-party script
• Characterization: node --test test/clarity.test.mjs

Validation

• node --test test/clarity.test.mjs — pass
• python3 test/standards/i18n_keys.py — pass
• python3 test/standards/i18n_fallback_sync.py — pass
• reading-level ratchet — about.html improved vs baseline; suite pass

Status

dormant-until-configured — merge ships the wiring; live heatmaps begin only after the operator pastes a real project id and sets Strict masking.