@junixlabs/uxcli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 junixlabs
+
+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

@@ -0,0 +1,81 @@
+# UXCLI
+
+`uxcli` measures a running UI against its design commitments. Built for AI coding agents that need to verify the frontend they just wrote.
+
+**Status:** early. Three flow probes (WCAG 3.3.4, 3.3.7, 3.2.3), a gate that proves each probe can fail, a verdict card, and a second reader. On npm as `@junixlabs/uxcli`; the command is `uxcli`.
+
+**Core rule: no commitment, no verdict.** Every finding cites the commitment it enforces: W3C's, yours, or none. Where no one has committed, `uxcli` says nothing.
+
+## Why
+
+- Automated accessibility tools check one page at a time. Defects that span screens (data entered on step 1 missing from the review on step 3, navigation order changing between pages) have no automated check today.
+- Agents cannot see what they render. The common failure is not blindness but false confirmation: given a screenshot of a broken UI, the agent reports success.
+- Existing UI review tools produce false positives, and one false positive is enough for a developer to disable the tool.
+
+## Install and use
+
+Node 20+.
+
+```
+npm install -g @junixlabs/uxcli
+npx playwright-core install chromium-headless-shell   # once; or set UXCLI_CHROME to a Chromium binary
+uxcli run journey.json                                # verdict card
+uxcli run journey.json --json                         # full evidence packet
+uxcli run journey.json --refute                       # a fresh second reader checks each fail from the screenshots (needs the claude CLI, or set UXCLI_REFUTER)
+uxcli gate                                            # every probe must fail on its seeded fixture and stay silent on the clean twin
+uxcli why 3.3.7                                       # the probe's definition
+```
+
+`npx @junixlabs/uxcli <command>` works without the global install. To hack on it: `git clone https://github.com/junixlabs/uxcli && cd uxcli && npm install`, then `node bin/uxcli.js` in place of `uxcli`. An example journey is in `examples/sylius-guest-checkout.json`.
+
+A journey is the commitment: the steps of one process, which step commits, and what the human declares (`sameProcess`, `checkedPass`, `reversible`). See `test/journeys/checkout.json`.
+
+## How it works
+
+The one input the machine cannot derive, the journey, is written by a human. Everything else is measured. The agent may propose a commitment; it may not commit it.
+
+| Available | Planned |
+|---|---|
+| `run <journey>` measure a flow; card by default, `--json`, `--refute` | `run <url>` single-screen probes (focus-visible, text-spacing, contrast) |
+| `gate` run every probe's falsification pair | `principles` skill: what the product commits to, as thresholds |
+| `why <rule>` the probe's definition | `diff a b --gate` drift between builds |
+
+Every probe ships with a pair of fixtures: one where it must fail, one where it must stay silent. A probe without that pair cannot say `fail`. `gate` enforces it.
+
+What comes next, and in what order, is in [ROADMAP.md](ROADMAP.md).
+
+## Rules of output
+
+- Every finding carries a provenance: `spec`, `project`, or `opinion`.
+- Every probe carries a method status: `method-validated` or `method-unproven`. Unproven probes report `finding`, never `fail`.
+- Nine verdicts: `pass`, `fail`, `finding`, `not-applicable`, `not-committed`, `unmeasurable`, `suppressed`, `stale`, `untested`. Only `fail` blocks a merge.
+- No threshold set means `not-committed`, not `fail`.
+- Cannot measure means `unmeasurable`, never `pass`.
+- Every exception ships with a coverage test.
+- No score, no summary line, no conformance claim.
+
+## Evidence so far
+
+Method checked against public test suites and unseen sites before product code; the flow probes checked on a seeded fixture, on real apps, and on agents.
+
+| Probe | Suite | Result |
+|---|---|---|
+| focus-visible | W3C ACT, 7 cases | 7/7 |
+| focus-visible | GOV.UK, 22 pages, 1,244 focusable elements | 0 false fails |
+| text-spacing (locked) | W3C ACT, 62 cases | 62/62, after 3 definition fixes |
+| contrast (delegated to axe-core) | W3C ACT, 32 cases | 24/32, 0 false positives, 7 `cantTell` |
+| focus-visible, text-spacing | 20 unseen pages, 5 sites, definitions frozen and hashed first | 0 false fails |
+| flow probes 3.3.4 / 3.3.7 / 3.2.3 | seeded checkout fixture, probe frozen before the fixture existed | 3/3 caught, silent on the clean twin |
+| flow probes | 10 flows on 4 real apps the probes had never seen | 0 false fails; one real 3.3.7 defect found by hand that the probe then missed, now caught |
+| verdict card vs JSON packet | 40 fresh agent sessions fixing the seeded fixture | 0 reported done with a check failing; card sessions edited only the cited file 19/20, JSON 7/20 |
+| planted wrong `fail` | 20 agent sessions on the clean fixture | 2/10 rewrote the site to satisfy it without the tool; 0/10 with the tool in hand |
+
+Not yet shown: precision on more than 10 real flows; recall on defects seeded into real pages by someone who does not tune the probes; any of this on a second model.
+
+## Non-goals
+
+Conformance certification. Visual regression. Scores. Design critique.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/VISION.md

@@ -0,0 +1,71 @@
+# UXCLI
+
+**Every verdict cites the commitment it enforces: W3C's, yours, or none.**
+**Where no one has committed, UXCLI says nothing.**
+
+## Design should be executable.
+
+Software has machines that refuse a build that breaks a contract. Nothing refuses a build that breaks a journey. A journey map dies at handoff. A token becomes a suggestion. A principle becomes a thread. What ships is whatever survived, and no instrument can say how far it drifted from what was decided.
+
+UXCLI is that instrument. It measures the running product against the commitments that produced it: the journeys that matter, the tokens that define the system, the principles that govern behavior. It drives a real browser. It follows flows. It measures change over time. It locates drift between builds to the element and the file. It sees defects that exist between screens, not only inside them.
+
+This matters now because the author of the interface is changing. Agents produce more frontend than humans can inspect. The agent that writes the interface cannot be the authority that declares it correct. It needs perception, not another opinion.
+
+A commitment becomes a measurement. A measurement produces evidence. Evidence earns a verdict.
+
+**Your design, executable.**
+
+## The next layer is not generation. It is perception.
+
+axe answers *is this page broken?* Dembrandt answers *did the tokens drift?* Nothing answers *does the flow the user came for still complete?* The difference is the input. Those tools read a page. UXCLI reads a page and the commitment, and the commitment is a journey. That input makes a new class of defect measurable.
+
+- **Between screens.** Data entered on step one, absent from the review on step three. Navigation that reorders itself between pages. No page-level tool can see this, because no page-level tool remembers.
+- **Across time.** A toast that lives 800 ms when the principle says four seconds. Motion is data, not noise to freeze.
+- **Between builds.** Drift, reported at the element and the file that caused it. Never as a score.
+- **At five scales.** One element. One screen. One flow. The whole design system. The delta between two builds. One instrument, five zoom levels.
+
+## Who runs it
+
+The human operating a coding agent. The pain is specific: the agent reports success with proof of failure in hand. UXCLI is the instrument an agent runs before it is allowed to say done.
+
+Commitments are written by a human, before the build, and versioned. The agent may propose one. It may not commit it. The party being measured never authors the measure in the same run.
+
+Developers get the same instrument as a pre-merge gate: findings that need no re-checking before fixing, and a `fail` that blocks.
+
+## Why it stays on
+
+A review tool that lies three times is disabled forever. UXCLI is built around one rule and its consequences.
+
+**No commitment, no verdict.** A commitment is a threshold with a named owner and a written source. W3C is a named owner, so WCAG runs by default. Nobody signed taste, so taste never runs.
+
+- Every finding names its provenance: `spec`, `project`, or `opinion`. Opinion without a written principle stays silent.
+- Every probe declares its method. An unproven method can raise a `finding`, never a `fail`.
+- No commitment yields `not-committed`, not `fail`. Cannot measure yields `unmeasurable`, never `pass`.
+- Nine verdicts. One blocks a merge.
+- The opening rule set contains only probes proven not to false-positive, and at least one of them is a flow rule.
+
+A tool with no opinions of its own has nothing to be wrong about.
+
+**UXCLI wins by saying less, and being right.**
+
+## Shape
+
+Two skills write commitments: `journey`, `principles`. Seven commands measure: `init`, `run`, `sheet`, `query`, `scan`, `diff --gate`, `why`. Everything that carries a name carries `id · why · correct-when · applies-when`.
+
+UXCLI does not score design. It does not certify taste. It does not replace visual regression. It does not turn uncertainty into green checks.
+
+## Where it stands
+
+| Axis | Evidence | Verdict |
+|---|---|---|
+| Method | focus-visible 7/7 W3C ACT, 22 GOV.UK pages 0 false fails; text-spacing 62/62; axe contrast 0 FP. Definitions frozen and hashed, then 20 unseen pages on 5 sites: 0 false fails. Three independent detectors and chrome-devtools-mcp #86 converged on the same computed-style approach. | Confirmed |
+| The flow claim | The gap is real: axe has no rules for 3.3.4 / 3.3.7 / 3.2.3; Evinced and Lighthouse aggregate per page. Three flow probes written from the WCAG text before any fixture existed. Seeded fixture: 3/3 caught, silent on the clean twin. 10 flows on 4 real apps the probes had never seen, definitions frozen: 0 false fails; one real 3.3.7 defect found by hand that the probe did not see. | Measured on fixtures. Unproven at scale. |
+| Adoption | The strongest community pain is agents that report success with proof of failure in hand. 40 fresh Sonnet sessions on the seeded fixture, 20 of them running the tool themselves: 0 reported done while a check still failed, and none treated `unmeasurable` as a pass. Agents given the card edited only the cited file in 19 of 20 sessions; agents given the full JSON packet, in 7 of 20. Given a planted wrong `fail`, 2 of 10 agents without the tool rewrote the site to satisfy it; 0 of 10 with the tool in hand did, all re-ran it and disputed. | Measured on one model and one fixture. The resistance comes from re-running the measurement, not from the report's wording. |
+
+Next, in order: 20 flows on apps the probes have never seen; recall from defects seeded into real pages by someone who does not tune the probes; a second model on the planted-verdict test.
+
+**The part worth building is the part not yet proven.**
+
+## Sources
+
+developersdigest.tech/blog/ai-design-slop-and-how-to-spot-it · impeccable.style/slop · solodesign.cc/blog/ai-design-slop-the-tells · github.com/ChromeDevTools/chrome-devtools-mcp/issues/86 · github.com/anthropics/claude-code/issues/38948 · news.ycombinator.com/item?id=46594200 · arxiv.org/abs/2503.15885 · arxiv.org/abs/2502.10884 · dequeuniversity.com/rules/axe/4.10 · github.com/dembrandt/dembrandt

package/bin/uxcli.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+// uxcli — UI/UX review for coding agents. No commitment, no verdict.
+import fs from 'node:fs'; import path from 'node:path'; import { fileURLToPath } from 'node:url';
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const [cmd, ...rest] = process.argv.slice(2);
+const flags = new Set(rest.filter(a => a.startsWith('--') && !a.includes('='))); const args = rest.filter(a => !a.startsWith('--'));
+const opt = k => (rest.find(a => a.startsWith('--' + k + '=')) || '').split('=').slice(1).join('=') || null;
+const usage = `usage:
+  uxcli run <journey.json> [--json] [--out=DIR] [--refute]
+      measure one flow; card by default, --json for the evidence packet; screenshots for fails in DIR (default .uxcli/<journey>);
+      --refute asks a fresh second reader (UXCLI_REFUTER, default claude -p) to confirm or dispute each fail from the images alone
+  uxcli gate                          run every probe's falsification pair; exit 1 unless all hold
+  uxcli why <rule>                    print a probe's definition (e.g. why 3.3.7, why redundant-entry)
+browser: playwright-core; set UXCLI_CHROME to a Chromium binary if none is installed for playwright.`;
+try {
+  if (cmd === 'run' && args[0]) {
+    const { loadJourney } = await import('../src/journey.js'); const { runJourney } = await import('../src/run.js'); const { card } = await import('../src/card.js');
+    const outDir = opt('out') || path.join('.uxcli', path.basename(args[0], '.json'));
+    const result = await runJourney(loadJourney(path.resolve(args[0])), { outDir });
+    if (flags.has('--refute')) { const { refute } = await import('../src/refute.js'); for (const p of result.probes) if (p.verdict === 'fail') p.refute = refute(p); }
+    console.log(flags.has('--json') ? JSON.stringify(result, null, 1) : card(result));
+    process.exit(result.probes.some(p => p.verdict === 'fail') ? 2 : 0);
+  } else if (cmd === 'gate') {
+    const { gate } = await import('../src/gate.js'); process.exit((await gate()) ? 0 : 1);
+  } else if (cmd === 'why' && args[0]) {
+    const dirs = fs.readdirSync(path.join(ROOT, 'src/probes'));
+    const hit = dirs.find(d => d === args[0] || fs.readFileSync(path.join(ROOT, 'src/probes', d, 'spec.md'), 'utf8').split('\n')[0].includes('WCAG ' + args[0]));
+    if (!hit) { console.error('no probe for ' + args[0] + '; have: ' + dirs.join(', ')); process.exit(1); }
+    console.log(fs.readFileSync(path.join(ROOT, 'src/probes', hit, 'spec.md'), 'utf8'));
+  } else { console.log(usage); process.exit(cmd ? 1 : 0); }
+} catch (e) { console.error('uxcli: ' + (e.message || e)); process.exit(1); }

package/examples/sylius-guest-checkout.json

@@ -0,0 +1,11 @@
+{
+  "name": "Sylius v2 demo guest checkout (B1 round 2)",
+  "checkedPass": true,
+  "steps": [
+    { "url": "https://v2.demo.sylius.com/en_US/products/denim-daydream", "click": "#add-to-cart-button" },
+    { "url": "https://v2.demo.sylius.com/en_US/checkout/address", "fill": { "#sylius_shop_checkout_address_customer_email": "uxcli1788625992@example.org", "#sylius_shop_checkout_address_billingAddress_firstName": "Jane", "#sylius_shop_checkout_address_billingAddress_lastName": "Doe", "#sylius_shop_checkout_address_billingAddress_street": "12 High Street", "#sylius_shop_checkout_address_billingAddress_countryCode": "United States", "#sylius_shop_checkout_address_billingAddress_city": "New York", "#sylius_shop_checkout_address_billingAddress_postcode": "10001" }, "submit": "form[name=sylius_shop_checkout_address] button[type=submit]" },
+    { "url": "https://v2.demo.sylius.com/en_US/checkout/select-shipping", "submit": "form[name=sylius_shop_checkout_select_shipping] button[type=submit]" },
+    { "url": "https://v2.demo.sylius.com/en_US/checkout/select-payment", "submit": "form[name=sylius_shop_checkout_select_payment] button[type=submit]" },
+    { "url": "https://v2.demo.sylius.com/en_US/checkout/complete", "commit": true, "submit": "form button[type=submit]:has-text('Place order')" }
+  ]
+}

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@junixlabs/uxcli",
+  "version": "0.1.0",
+  "description": "UI/UX review for coding agents. No commitment, no verdict.",
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/junixlabs/uxcli.git" },
+  "homepage": "https://github.com/junixlabs/uxcli#readme",
+  "bugs": { "url": "https://github.com/junixlabs/uxcli/issues" },
+  "keywords": ["accessibility", "wcag", "ui-review", "playwright", "coding-agents"],
+  "type": "module",
+  "bin": { "uxcli": "bin/uxcli.js" },
+  "files": ["bin", "src", "test", "examples", "README.md", "VISION.md", "LICENSE"],
+  "engines": { "node": ">=20" },
+  "scripts": { "test": "node bin/uxcli.js gate" },
+  "dependencies": { "playwright-core": "^1.58.0" }
+}

package/src/browser.js

@@ -0,0 +1,103 @@
+// Browser helpers shared by the run and by probes that replay steps.
+import { chromium } from 'playwright-core';
+import { THIRD, CHROME, normUrl } from './util.js';
+
+export async function launch() {
+  const executablePath = process.env.UXCLI_CHROME || process.env.CHROME_EXE || undefined;
+  try { return await chromium.launch({ executablePath, headless: true }); }
+  catch (e) { if (/executable doesn't exist|install/i.test(String(e))) throw new Error('no Chromium for playwright-core. Run: npx playwright-core install chromium-headless-shell   (or set UXCLI_CHROME to a Chromium binary)'); throw e; }
+}
+
+// In-page collectors. Injected as source so every probe reads the DOM the same way.
+export const PAGE_FNS = `
+  const THIRD = ${JSON.stringify(THIRD)}; const CHROME = ${JSON.stringify(CHROME)};
+  const norm = s => String(s ?? '').trim().toLowerCase().replace(/\\s+/g, ' ');
+  const vis = el => { if (!el.getClientRects().length) return false; const cs = getComputedStyle(el); return cs.visibility !== 'hidden' && cs.display !== 'none' && parseFloat(cs.opacity) > 0; };
+  const third = el => !!el.closest(THIRD);
+  const label = el => {
+    if (el.getAttribute('aria-label')) return el.getAttribute('aria-label');
+    const lb = el.getAttribute('aria-labelledby'); if (lb) { const t = lb.split(/\\s+/).map(id => document.getElementById(id)?.textContent || '').join(' ').trim(); if (t) return t; }
+    if (el.id) { const l = document.querySelector('label[for="' + CSS.escape(el.id) + '"]'); if (l && l.textContent.trim()) return l.textContent; }
+    const wrap = el.closest('label'); if (wrap) { const t = wrap.textContent.trim(); if (t) return t; }
+    return el.getAttribute('title') || el.getAttribute('placeholder') || '';
+  };
+  const identity = el => {
+    const ac = (el.getAttribute('autocomplete') || '').trim().toLowerCase().split(/\\s+/).filter(Boolean);
+    const section = ac.find(t => t.startsWith('section-') || t === 'shipping' || t === 'billing') || '';
+    const token = ac.filter(t => !(t.startsWith('section-') || t === 'shipping' || t === 'billing')).pop() || '';
+    const fs = el.closest('fieldset'); const legend = fs ? norm(fs.querySelector('legend')?.textContent) : '';
+    return { autocomplete: token, section, legend, name: el.getAttribute('name') || '', type: (el.getAttribute('type') || el.tagName).toLowerCase(), label: norm(label(el)), tag: el.tagName.toLowerCase(), id: el.id || '' };
+  };
+  const editable = el => !el.disabled && !el.readOnly && vis(el) && !third(el) && !['hidden','password','submit','button','search','reset','image','file','checkbox','radio'].includes((el.getAttribute('type')||'').toLowerCase());
+  const processInputs = () => { const form = document.querySelector('[data-uxcli-scope]'); if (!form) return []; return [...form.querySelectorAll('input, textarea, select')].filter(el => editable(el) && !el.closest(CHROME)).map(el => ({ ...identity(el), value: el.tagName === 'SELECT' ? (el.selectedOptions[0]?.textContent || el.value) : el.value })); };
+  const visibleText = () => { const hidden = [...document.querySelectorAll(THIRD)]; hidden.forEach(e => e.setAttribute('data-uxcli-hide', '1')); const st = document.createElement('style'); st.textContent = '[data-uxcli-hide]{display:none!important}'; document.head.appendChild(st); const t = document.body.innerText; st.remove(); hidden.forEach(e => e.removeAttribute('data-uxcli-hide')); return t; };
+  const readTexts = () => (document.querySelector('main') || document.body).textContent + '\\u0000' + [...document.querySelectorAll('input, textarea, select')].map(e => e.value).join('\\u0001');
+  const fields = () => [...document.querySelectorAll('input, textarea, select')].filter(e => vis(e) && !third(e)).map(e => ({ value: e.tagName === 'SELECT' ? (e.selectedOptions[0]?.textContent || e.value) : e.value, ro: e.readOnly || e.disabled, editable: editable(e) }));
+  const controls = () => [...document.querySelectorAll('a[href], button, [role=button], input[type=submit], input[type=button]')].filter(e => vis(e) && !third(e) && !e.closest(CHROME)).map(e => ({ href: e.href || '', text: norm(e.textContent || e.value || e.getAttribute('aria-label')) }));
+  const navs = () => { const all = [...document.querySelectorAll('nav, [role="navigation"]')].filter(n => !third(n)); let un = 0; return all.map(n => { const al = n.getAttribute('aria-label'); const lb = n.getAttribute('aria-labelledby'); let name = al || (lb ? lb.split(/\\s+/).map(id => document.getElementById(id)?.textContent || '').join(' ') : ''); name = norm(name); const key = name ? 'name:' + name : 'unnamed:' + (un++); const links = [...n.querySelectorAll('a[href]')].filter(a => !third(a)).map(a => ({ href: a.href, text: norm(a.textContent) || norm(a.getAttribute('aria-label')) || '' })); return { key, links }; }); };
+`;
+export const evalIn = (page, body) => page.evaluate(new Function(PAGE_FNS + ' return (' + body + ')();'));
+export const evalEl = (locator, body) => locator.evaluate(new Function('el', PAGE_FNS + ' return (' + body + ')(el);'));
+
+export async function settle(page) {
+  await page.waitForLoadState('domcontentloaded', { timeout: 30000 }).catch(() => {});
+  await page.waitForLoadState('load', { timeout: 15000 }).catch(() => {});
+  await page.waitForLoadState('networkidle', { timeout: 8000 }).catch(() => {});
+  await page.waitForTimeout(300);
+}
+export async function arrive(page, step) {
+  if (step.url && normUrl(page.url()) !== normUrl(step.url)) { await page.goto(step.url, { waitUntil: 'load', timeout: 45000 }); await settle(page); return 'goto'; }
+  await settle(page); return 'flow';
+}
+export async function noise(page) { const a = await evalIn(page, '() => readTexts()'); await page.waitForTimeout(600); const b = await evalIn(page, '() => readTexts()'); return a !== b; }
+
+// Mark the process scope for this step: the submit control's form, else the nearest region around the control.
+export async function markScope(page, step) {
+  await page.evaluate(() => document.querySelectorAll('[data-uxcli-scope]').forEach(f => f.removeAttribute('data-uxcli-scope')));
+  const sel = step.submit || step.click; if (!sel) return null;
+  try {
+    const ctl = page.locator(sel).first(); if (!await ctl.count()) return null;
+    return await ctl.evaluate(el => { const f = el.closest('form'); if (f) { f.setAttribute('data-uxcli-scope', '1'); return 'form'; } const c = el.closest('fieldset, section, article, [role=region], [role=main], main') || document.querySelector('main') || document.body; c.setAttribute('data-uxcli-scope', '1'); return 'region:' + c.tagName.toLowerCase(); });
+  } catch { return null; }
+}
+
+// Fill a step's fields. Records every non-password value with the field's identity; returns the step's auth flag.
+export async function fillStep(page, step, idx, recorded) {
+  let auth = false;
+  for (const [sel, spec] of Object.entries(step.fill || {})) {
+    const value = typeof spec === 'object' ? spec.value : spec; const marks = typeof spec === 'object' ? { essential: !!spec.essential, security: !!spec.security } : {};
+    const loc = page.locator(sel).first();
+    const id = await evalEl(loc, 'el => { const i = identity(el); i.required = el.required || el.getAttribute("aria-required") === "true"; i.minlength = el.getAttribute("minlength") ? parseInt(el.getAttribute("minlength"), 10) : 0; return i; }');
+    if (id.tag === 'select') await loc.selectOption({ label: String(value) }).catch(() => loc.selectOption(String(value))); else await loc.fill(String(value));
+    const display = id.tag === 'select' ? await loc.evaluate(el => el.selectedOptions[0]?.textContent || el.value) : String(value);
+    if (id.type === 'password') { auth = true; continue; }
+    const credentialCandidate = /user|login|email/i.test(id.name + ' ' + id.id + ' ' + id.label) || id.type === 'email' || /^(username|email)$/.test(id.autocomplete);
+    recorded.push({ ...id, ...marks, value: String(value), display, step: idx, selector: sel, credentialCandidate });
+  }
+  return auth;
+}
+// Perform the step's action. Returns 'submitDidNotNavigate' when a submit left the URL unchanged.
+export async function act(page, step) {
+  const sel = step.submit || step.click; if (!sel) return null;
+  const before = page.url();
+  await page.locator(sel).first().click({ timeout: 15000 });
+  await page.waitForFunction(u => location.href !== u, before, { timeout: 5000 }).catch(() => {});
+  await settle(page);
+  return step.submit && normUrl(page.url()) === normUrl(before) ? 'submitDidNotNavigate' : null;
+}
+export async function screen(page, i, rec) {
+  return { step: i, url: rec.url, noise: rec.noise, text: await evalIn(page, '() => visibleText()'), ro: await evalIn(page, '() => fields()'), links: await evalIn(page, '() => controls()') };
+}
+
+// Evidence: screenshot of a region with the cited fields outlined. Returns a PNG buffer or null.
+export async function shot(page, regionSelector, highlight = []) {
+  try {
+    await page.evaluate(sels => { for (const s of sels) for (const el of document.querySelectorAll(s)) { el.setAttribute('data-uxcli-mark', '1'); el.style.outline = '3px solid #d40000'; el.style.outlineOffset = '2px'; } }, highlight);
+    const loc = regionSelector ? page.locator(regionSelector).first() : null;
+    const buf = loc && await loc.count() && await loc.isVisible() ? await loc.screenshot({ timeout: 5000 }) : await page.screenshot({ timeout: 5000 });
+    await page.evaluate(() => document.querySelectorAll('[data-uxcli-mark]').forEach(el => { el.style.outline = ''; el.style.outlineOffset = ''; el.removeAttribute('data-uxcli-mark'); }));
+    return buf;
+  } catch { return null; }
+}
+export const fieldSelector = f => f.id ? '#' + CSS_escape(f.id) : f.name ? `[name="${f.name.replace(/"/g, '\\"')}"]` : null;
+const CSS_escape = s => s.replace(/([^a-zA-Z0-9_-])/g, '\\$1');

package/src/card.js

@@ -0,0 +1,27 @@
+// The verdict card: what the working agent reads. Low hundreds of tokens; --json carries the evidence.
+const V = v => ({ pass: 'PASS', fail: 'FAIL', unmeasurable: 'UNMEASURABLE', 'not-applicable': 'N/A', 'not-committed': 'NOT-COMMITTED', blocked: 'BLOCKED' }[v] || String(v).toUpperCase());
+const short = s => { s = String(s); if (s.startsWith('t:')) return s.slice(2); s = s.slice(2); const i = s.lastIndexOf('/'); return (i >= 0 ? s.slice(i + 1) : s).slice(0, 60) || s.slice(0, 60); };
+export function card(result) {
+  const L = [`uxcli run · ${result.journey}`, ''];
+  for (const p of result.probes) {
+    const proof = p.proof?.length ? `  proof  ${p.proof.join('  ')}` + (p.refute ? `\n  reader ${p.refute.tested ? (p.refute.parsed ? (p.refute.agrees ? 'agrees' : 'DISPUTES') + ' — ' + p.refute.reason : 'unparsed: ' + p.refute.raw) : 'not run: ' + p.refute.why}` : '') : null;
+    const head = `${p.sc} ${p.probe.replace('flow.', '').padEnd(22)} ${V(p.verdict).padEnd(13)}`;
+    const rule = `  rule   WCAG ${p.sc} (spec)${p.override ? ` · process joined by sameProcess ${JSON.stringify(p.override.sameProcess)} (project)` : ''}`;
+    if (p.verdict === 'fail' && p.sc === '3.3.7') {
+      const fields = [...new Set(p.reasked.map(m => m.field.name || m.field.id))], steps = [...new Set(p.reasked.map(m => m.step))], first = [...new Set(p.reasked.map(m => m.firstEnteredStep))];
+      L.push(head, `  what   ${fields.join(', ')} asked again on step ${steps.join(',')}; first entered on step ${first.join(',')}`, `  where  ${p.reasked[0].url}  ${fields.map(f => '#' + f).join(', ')}`, rule, `  check  Reach this screen through the earlier steps. ${fields.length > 1 ? 'Are these fields' : 'Is this field'} empty although you typed the value${fields.length > 1 ? 's' : ''} earlier?`); if (proof) L.push(proof);
+    } else if (p.verdict === 'fail' && p.sc === '3.3.4') {
+      const c = p.branches.confirmed, ck = p.branches.checked;
+      L.push(head, `  what   ${c.missing.length} of ${c.missing.length + c.present.length} entered values are not shown on the commit screen; no change control; validation ${ck.tested ? 'tested: ' + ck.evidence : 'untested'}`, `  where  ${result.steps.find(s => s.i === c.screen)?.url}`, rule, `  check  On this screen, can you see ${c.missing.slice(0, 3).map(m => JSON.stringify(m.value)).join(', ')} and a way to change them before committing?`); if (proof) L.push(proof);
+    } else if (p.verdict === 'fail' && p.sc === '3.2.3') {
+      const x = p.inversion;
+      L.push(head, `  what   ${x.mechanism} order differs between steps ${x.stepA} and ${x.stepB}; first inverted pair ${x.firstInvertedPair.map(short).join(' / ')}`, rule, `  check  Compare the ${x.mechanism.replace(/^name:/, '')} menu on both pages; are those two items in swapped order?`); if (proof) L.push(proof);
+    } else if (p.verdict === 'pass') {
+      const why = p.sc === '3.3.4' ? `via ${p.branch}${p.branches?.confirmed?.changeMechanism ? ` · change control "${typeof p.branches.confirmed.changeMechanism === 'string' ? p.branches.confirmed.changeMechanism : p.branches.confirmed.changeMechanism.text}"` : ''}${p.branches?.checked?.evidence ? ` · ${p.branches.checked.evidence}` : ''}`
+        : p.sc === '3.3.7' ? `${p.satisfied.length} matched field${p.satisfied.length > 1 ? 's' : ''}, ${[...new Set(p.satisfied.map(m => m.mechanism))].join('/')}`
+        : `${p.comparedPairs} pairs, ${Object.keys(p.mechanisms || {}).length} mechanisms, no inversion`;
+      L.push(`${head} ${why}`);
+    } else L.push(`${head} ${(p.why || '').split(';')[0].slice(0, 100)}`);
+  }
+  return L.join('\n');
+}

package/src/gate.js

@@ -0,0 +1,33 @@
+// uxcli gate: every probe's falsification pair must fail where it must and stay silent where it must, and the fixture hashes must match.
+import fs from 'node:fs'; import path from 'node:path'; import os from 'node:os'; import crypto from 'node:crypto'; import { fileURLToPath, pathToFileURL } from 'node:url';
+import { loadJourney } from './journey.js'; import { runJourney, PROBES } from './run.js'; import { launch } from './browser.js';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const sha = f => crypto.createHash('sha256').update(fs.readFileSync(f)).digest('hex');
+export function hashTree(dir) { const out = {}; for (const f of fs.readdirSync(dir).sort()) { const p = path.join(dir, f); if (fs.statSync(p).isFile()) out[f] = sha(p); } return out; }
+
+export async function gate({ log = console.log } = {}) {
+  const browser = await launch(); let ok = true;
+  const site = path.join(ROOT, 'test/fixtures/checkout'); const siteHashes = hashTree(site);
+  for (const probe of PROBES) {
+    const dir = path.join(ROOT, 'src/probes', probe.id.replace('flow.', ''));
+    const pair = JSON.parse(fs.readFileSync(path.join(dir, 'pair.json'), 'utf8'));
+    const problems = [];
+    for (const [f, h] of Object.entries(pair.hashes.site)) if (siteHashes[f] !== h) problems.push(`site/${f} hash changed`);
+    for (const [f, h] of Object.entries(pair.hashes.mustFail)) if (sha(path.join(dir, 'must-fail', f)) !== h) problems.push(`must-fail/${f} hash changed`);
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'uxcli-gate-'));
+    const build = (overlay) => { const d = fs.mkdtempSync(path.join(tmp, 'v-')); fs.cpSync(site, d, { recursive: true }); if (overlay) fs.cpSync(overlay, d, { recursive: true }); return pathToFileURL(d + '/').href; };
+    const jPath = path.join(ROOT, pair.journey);
+    const vf = (await runJourney(loadJourney(jPath, { base: build(path.join(dir, 'must-fail')) }), { browser })).probes.find(p => p.sc === probe.sc);
+    const vp = (await runJourney(loadJourney(jPath, { base: build(null) }), { browser })).probes.find(p => p.sc === probe.sc);
+    fs.rmSync(tmp, { recursive: true, force: true });
+    const fOk = vf.verdict === 'fail', pOk = ['pass', 'not-applicable'].includes(vp.verdict);
+    if (!fOk) problems.push(`must-fail returned ${vf.verdict}`); if (!pOk) problems.push(`must-pass returned ${vp.verdict}`);
+    if (problems.length) ok = false;
+    log(`${probe.sc} ${probe.id.padEnd(28)} must-fail: ${vf.verdict.padEnd(6)} must-pass: ${vp.verdict.padEnd(14)} ${problems.length ? 'FAIL  ' + problems.join('; ') : 'ok'}`);
+    log(`      operator: ${pair.operator}`);
+  }
+  await browser.close();
+  log(ok ? 'GATE PASS' : 'GATE FAIL');
+  return ok;
+}

package/src/journey.js

@@ -0,0 +1,13 @@
+import fs from 'node:fs';
+// Journey = the commitment. { name, checkedPass?, reversible?, sameProcess?: [[from,to]], steps: [{ url?, fill?, click?, submit?, commit?, userReorder? }] }
+export function loadJourney(file, vars = {}) {
+  let text = fs.readFileSync(file, 'utf8');
+  for (const [k, v] of Object.entries(vars)) text = text.split('{{' + k + '}}').join(v);
+  const J = JSON.parse(text);
+  if (!Array.isArray(J.steps) || !J.steps.length) throw new Error('journey needs steps[]');
+  if (!J.steps[0].url) throw new Error('first step needs a url');
+  if (J.steps.filter(s => s.commit).length > 1) throw new Error('at most one step may be marked commit');
+  for (const [a, b] of J.sameProcess || []) if (!(a >= 0 && b >= a && b < J.steps.length)) throw new Error('sameProcess range out of bounds');
+  J.name ||= file;
+  return J;
+}

package/src/probes/consistent-navigation/must-fail/review.html

@@ -0,0 +1,76 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Review your order – Fixture Shop</title>
+  <link rel="stylesheet" href="style.css">
+</head>
+<body>
+<header>
+  <div class="wrap">
+    <a class="brand" href="home.html">Fixture Shop</a>
+    <nav aria-label="Main">
+      <ul>
+        <li><a href="home.html">Home</a></li>
+        <li><a href="cart.html">Cart <span class="badge">2<span class="sr"> items</span></span></a></li>
+        <li><a href="shop.html">Shop</a></li>
+        <li><a href="account.html">Account</a></li>
+        <li><a href="help.html">Help</a></li>
+      </ul>
+    </nav>
+  </div>
+</header>
+<main class="wrap">
+  <h1>Review your order</h1>
+  <p>Check everything is correct before you place your order.</p>
+
+  <h2>Items</h2>
+  <table>
+    <thead>
+      <tr><th scope="col">Item</th><th scope="col" class="num">Qty</th><th scope="col" class="num">Price</th></tr>
+    </thead>
+    <tbody>
+      <tr><td>Ceramic mug</td><td class="num">1</td><td class="num">£12.00</td></tr>
+      <tr><td>Notebook, A5, dotted</td><td class="num">1</td><td class="num">£8.50</td></tr>
+    </tbody>
+  </table>
+  <p class="total">Total: £20.50</p>
+
+  <h2>Your details</h2>
+  <dl id="summary">
+    <div><dt>Full name</dt><dd><span id="out-name"></span><a href="details.html#name">Change<span class="sr"> full name</span></a></dd></div>
+    <div><dt>Email address</dt><dd><span id="out-email"></span><a href="details.html#email">Change<span class="sr"> email address</span></a></dd></div>
+    <div><dt>Street address</dt><dd><span id="out-address"></span><a href="details.html#address">Change<span class="sr"> street address</span></a></dd></div>
+    <div><dt>Postcode</dt><dd><span id="out-postcode"></span><a href="details.html#postcode">Change<span class="sr"> postcode</span></a></dd></div>
+    <div><dt>Country</dt><dd><span id="out-country"></span><a href="details.html#country">Change<span class="sr"> country</span></a></dd></div>
+  </dl>
+
+  <form id="order-form" action="done.html" method="get">
+    <button type="submit">Place order</button>
+  </form>
+  <script>
+    (function () {
+      var fields = ['name', 'email', 'address', 'postcode', 'country'];
+      var saved = {};
+      try { saved = JSON.parse(sessionStorage.getItem('checkout') || '{}'); } catch (e) {}
+      fields.forEach(function (f) {
+        document.getElementById('out-' + f).textContent = saved[f] || '';
+      });
+      document.getElementById('order-form').addEventListener('submit', function (ev) {
+        ev.preventDefault();
+        sessionStorage.setItem('orderPlaced', '1');
+        location.href = 'done.html';
+      });
+    })();
+  </script>
+</main>
+<footer>
+  <div class="wrap">
+    <a href="privacy.html">Privacy</a>
+    <a href="terms.html">Terms</a>
+    <a href="contact.html">Contact</a>
+  </div>
+</footer>
+</body>
+</html>

package/src/probes/consistent-navigation/pair.json

@@ -0,0 +1,23 @@
+{
+ "journey": "test/journeys/checkout.json",
+ "operator": "review.html: Cart and Shop are swapped in nav[aria-label=Main]; every other page keeps Home, Shop, Cart, Account, Help",
+ "hashes": {
+  "site": {
+   "account.html": "3972383a0e127789055e87f517e5812e7d0aadf98a979748b9468cbf5cdcef29",
+   "cart.html": "c40a826acc5df143e6c8bdb8b2ad95b6c236a1bf24315ef4a729902209fa3125",
+   "contact.html": "fe0b4f737714599aea8ffc61a0e3e66e66eb2ef900f97f29970d90085bdfb457",
+   "details.html": "866dedf0b0ff5baea57490907b07d2f726f00c69add81128e7938438e8f4d987",
+   "done.html": "714bfde7c1ba4e24d162f1faf9ab781ac0d06f44b149441c4845e740dcc32102",
+   "help.html": "e457b0e9a716019065de458d89114c37fbd14e67ada1ec69c8a2f65efbd1acbf",
+   "home.html": "287874d84b918ed8d6c16ce73d9ab631a489a5f9263933811e8ea960702126b2",
+   "privacy.html": "24d287f9a4e59218d69eb38360f674a92ada08860f2b194f71b7be2b9dbbdeff",
+   "review.html": "6a2191f30dc103062e986c7fada8f036f0931bc2247a70ed599c8b7d50b361b4",
+   "shop.html": "56a4d04abc3ca851bc29aff43be027c7f6406aeb0eb90d5dccc39c6088a1e679",
+   "style.css": "7f85da7845e02428fb480f86b8bcc3e32ae491882f27bcf35c10caef88999586",
+   "terms.html": "bd6a5c83a4e786574107a3aa02dc18e5b327624ebc14739fd0ae1785d180c187"
+  },
+  "mustFail": {
+   "review.html": "0fcc81bfb34841552284d06c691824e6e2461e0ec178940dbd6c961d1097946c"
+  }
+ }
+}

package/src/probes/consistent-navigation/probe.js

@@ -0,0 +1,40 @@
+// flow.consistent-navigation · WCAG 3.2.3. Spec in spec.md; falsification pair in pair.json.
+import { normUrl } from '../../util.js';
+import { evalIn } from '../../browser.js';
+
+export default {
+  id: 'flow.consistent-navigation', sc: '3.2.3',
+  async onStep(page, rec, ctx) {
+    const navs = await evalIn(page, '() => navs()');
+    (ctx.navsByStep ||= []).push({ i: rec.i, origin: new URL(rec.url).origin, userReorder: !!ctx.J.steps[rec.i].userReorder, navs });
+    const shots = {}; const els = page.locator('nav, [role="navigation"]'); const n = await els.count();
+    for (let k = 0; k < Math.min(n, navs.length); k++) { const el = els.nth(k); if (await el.isVisible().catch(() => false)) shots[navs[k].key] = await el.screenshot({ timeout: 5000 }).catch(() => null); }
+    (rec.evidence ||= {})['3.2.3'] = shots;
+  },
+  async evaluate(ctx) {
+    const navsByStep = ctx.navsByStep || [];
+    if (ctx.blocked) return { verdict: 'blocked' };
+    if (navsByStep.length < 2) return { verdict: 'unmeasurable', why: 'fewer than two steps loaded' };
+    const origin0 = navsByStep[0].origin; const same = navsByStep.filter(n => n.origin === origin0 && !n.userReorder);
+    const mechanisms = {}; let compared = 0, inversion = null;
+    for (const s of same) for (const n of s.navs) (mechanisms[n.key] ||= []).push({ step: s.i, links: n.links });
+    for (const [key, occ] of Object.entries(mechanisms)) {
+      for (let a = 0; a < occ.length && !inversion; a++) for (let b = a + 1; b < occ.length && !inversion; b++) {
+        const A = occ[a].links, B = occ[b].links;
+        const count = arr => arr.reduce((m, l) => (m[normUrl(l.href)] = (m[normUrl(l.href)] || 0) + 1, m), {});
+        const hA = count(A), hB = count(B);
+        // identity: href when unique within the mechanism on both pages, else text
+        const idOf = l => { const h = normUrl(l.href); if (hA[h] === 1 && hB[h] === 1) return 'h:' + h; return l.text ? 't:' + l.text : null; };
+        const uniq = arr => arr.filter((x, i) => arr.indexOf(x) === i);
+        const seqA = uniq(A.map(idOf).filter(Boolean)), seqB = uniq(B.map(idOf).filter(Boolean));
+        const cA = seqA.filter(x => seqB.includes(x)), cB = seqB.filter(x => cA.includes(x));
+        if (cA.length < 2) continue; compared++;
+        for (let k = 0; k < cA.length; k++) if (cA[k] !== cB[k]) { inversion = { mechanism: key, stepA: occ[a].step, stepB: occ[b].step, expected: cA, got: cB, firstInvertedPair: [cA[k], cB[k]] }; break; }
+      }
+    }
+    const out = { mechanisms: Object.fromEntries(Object.entries(mechanisms).map(([k, v]) => [k, v.map(o => ({ step: o.step, links: o.links.length }))])), comparedPairs: compared };
+    if (navsByStep.some(n => n.origin !== origin0)) out.note = 'steps on another origin excluded';
+    if (inversion) return { ...out, verdict: 'fail', inversion };
+    return { ...out, verdict: compared ? 'pass' : 'not-applicable' };
+  }
+};

package/src/probes/consistent-navigation/spec.md

@@ -0,0 +1,24 @@
+# flow.consistent-navigation · WCAG 3.2.3 · provenance spec
+
+- **why:** SC text: navigational mechanisms repeated across a set of web pages occur in the same relative order unless the user initiated a change. Insertions and removals are allowed (Understanding); only inversions fail (F66).
+- **applies-when:** at least two steps on the same origin (proxy for "set of web pages"); a navigational mechanism = `nav` element or `[role=navigation]`, identified across pages by accessible name (`aria-label` / `aria-labelledby`), or when unnamed, by its index among unnamed navs. Repeated = the same mechanism appears on ≥ 2 steps and shares ≥ 2 links.
+- **correct-when:** for each repeated mechanism, take the links common to two pages. A link's identity is its normalized `href` when that href is unique within the mechanism on both pages; otherwise its normalized text (a logo and Home sharing `/` must not collapse into one link). The common links appear in the same relative order on both pages: the sequence on page B, restricted to common links, is order-identical to the sequence on page A. Any inversion is a failure.
+- **verdict:** `pass`; `fail` listing the mechanism, the two steps, and the first inverted pair; `not-applicable` if no repeated mechanism; `unmeasurable` if a step is on another origin or failed to load.
+- **invalid-if:** the journey marks a step as user-initiated reorder (e.g. sort preference) — skipped for that step; a mechanism with fewer than 2 common links — not compared.
+- **known-infidelity:** same-origin is a proxy for the WCAG "set of web pages"; matching by text may miss links whose text is icon-only (matched by `aria-label` if present, else ignored); a mechanism that changes accessible name between pages is treated as two mechanisms.
+
+## Input: Journey input (the commitment)
+
+A journey is an ordered list of steps in one process. Each step: `url` (or an action that navigates), optional `fill` map, optional `submit` selector. One step may be marked `commit: true`: the action that causes a legal commitment, financial transaction, or modification of user data. The runner records every value the user (or the journey) enters, with the field's identity (`autocomplete`, `name`, `type`, accessible label) and the step index. If no step is marked `commit`, the 3.3.4 probe returns `not-committed`, never `fail`.
+
+
+
+## Shared invalid-if
+
+- Page title matches a bot-challenge pattern → `blocked`.
+- For 3.3.4 and 3.3.7, noise is defined on what they read: if the `textContent` of `main` (or `body` when no `main`) or any input value changes over 600 ms with no interaction → `unmeasurable`. Geometry changes are not noise for these probes. 3.2.3 reads the DOM once and has no noise check.
+- Third-party subtrees (`iframe`, `ins.adsbygoogle`, `.google-auto-placed`, `[id^=aswift]`, `[id^=google_ads]`, `.google-anno*`) are excluded from all three probes. This exclusion is carried from the P0-A finding and is part of the frozen definition.
+
+## Falsification pair
+
+See `pair.json`: one fixture where this probe must return `fail` for the stated operator, one where it must stay silent. `uxcli gate` runs both and checks the hashes. Written from the WCAG 2.2 Understanding text before any fixture or site was opened; revision history is kept outside the package.