npm - @wcag-checkr/ci - Versions diffs - 1.0.0-rc.99 → 1.0.0 - Mend

@wcag-checkr/ci 1.0.0-rc.99 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (117) hide show

package/dist/assets/tier-config-client-85XOCE5d.js ADDED Viewed

@@ -0,0 +1 @@

+ import{x as c,C as f,E as h,F as l,G as d,H as p}from"./ai-usage-log-CYyG5MT2.js";import{q as i,c as u,T as s}from"./crash-reporter-KD5f4utB.js";const o=u("tier-config-client"),w="wcagcheckr",T=`https://api.wcagcheckr.com/v1/products/${w}/tier-config`,m=1e4,n="tier-config-refresh",C=60,E=["free","solo","team"];function g(e){const t={};for(const r of E){const a=d(r,e);t[r]=a?p(s[r],a):{...s[r]}}return t}async function _(){const e=await c();if(!e){i(null);return}if(f(e)==="expired"){o.warn("cached tier-config is expired (>7d); using hardcoded defaults"),i(null);return}i(g(e.config))}async function I(){const e=await c();return!!e&&f(e)!=="expired"}async function R(){try{const e=await fetch(T,{signal:AbortSignal.timeout(m),headers:{accept:"application/json"}});if(!e.ok)throw new Error(`http ${e.status}`);const t=await e.json();await h({fetchedAt:Date.now(),config:t}),i(g(t));const r=t.wcagTargetVersion;if(r==="2.1"||r==="2.2")try{await chrome.storage.local.set({wcagTargetVersion:r}),l(r)}catch(a){o.warn("failed to persist wcagTargetVersion",a)}o.info("tier-config refreshed from server")}catch(e){o.warn("tier-config refresh failed; keeping prior cache",e)}}function A(){chrome.alarms.create(n,{periodInMinutes:C}),chrome.alarms.onAlarm.addListener(e=>{e.name===n&&R()})}export{A as a,I as h,R as r,_ as w};

package/dist/assets/zip-encoder-CtULHXx_.js ADDED Viewed

@@ -0,0 +1 @@

+ const A=new Uint32Array(256);for(let t=0;t<256;t++){let n=t;for(let o=0;o<8;o++)n=n&1?3988292384^n>>>1:n>>>1;A[t]=n>>>0}function M(t){let n=4294967295;for(let o=0;o<t.length;o++)n=A[(n^t[o])&255]^n>>>8;return(n^4294967295)>>>0}function w(t){return new TextEncoder().encode(t)}function e(t){return new Uint8Array([t&255,t>>>8&255])}function c(t){return new Uint8Array([t&255,t>>>8&255,t>>>16&255,t>>>24&255])}function p(t){let n=0;for(const l of t)n+=l.length;const o=new Uint8Array(n);let s=0;for(const l of t)o.set(l,s),s+=l.length;return o}function T(t){const o=Math.max(1980,t.getFullYear())-1980<<9|t.getMonth()+1<<5|t.getDate(),s=t.getHours()<<11|t.getMinutes()<<5|Math.floor(t.getSeconds()/2);return{date:o,time:s}}function b(t,n=new Date){const{date:o,time:s}=T(n),l=[],i=[];let h=0;for(const r of t){const f=w(r.name),g=r.bytes??w(r.content??""),d=M(g),u=g.length,m=p([c(67324752),e(20),e(2048),e(0),e(s),e(o),c(d),c(u),c(u),e(f.length),e(0),f,g]);l.push(m);const D=p([c(33639248),e(798),e(20),e(2048),e(0),e(s),e(o),c(d),c(u),c(u),e(f.length),e(0),e(0),e(0),e(0),c(0),c(h),f]);i.push(D),h+=m.length}const U=h;let y=0;for(const r of i)y+=r.length;const B=p([c(101010256),e(0),e(0),e(t.length),e(t.length),c(y),c(U),e(0)]),a=[];for(const r of l)a.push(r);for(const r of i)a.push(r);return a.push(B),new Blob(a,{type:"application/zip"})}export{b as createZip};

package/dist/devtools/panel.html CHANGED Viewed

@@ -3,16 +3,18 @@
   <head>
     <meta charset="UTF-8" />
     <title>wcagcheckr</title>
-    <script type="module" crossorigin src="/assets/devtools-panel-DCeWrjIb.js"></script>
+    <script type="module" crossorigin src="/assets/devtools-panel-BmQF2Qi9.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/modulepreload-polyfill-B5Qt9EMX.js">
     <link rel="modulepreload" crossorigin href="/assets/_commonjsHelpers-Cpj98o6Y.js">
-    <link rel="modulepreload" crossorigin href="/assets/crash-reporter-Dc5lvxvY.js">
-    <link rel="modulepreload" crossorigin href="/assets/state-BIsozXtc.js">
-    <link rel="modulepreload" crossorigin href="/assets/styles-DhnON7zr.js">
+    <link rel="modulepreload" crossorigin href="/assets/crash-reporter-KD5f4utB.js">
+    <link rel="modulepreload" crossorigin href="/assets/ai-usage-log-CYyG5MT2.js">
+    <link rel="modulepreload" crossorigin href="/assets/styles-B_kTykZT.js">
     <link rel="modulepreload" crossorigin href="/assets/preload-helper-D7HrI6pR.js">
-    <link rel="modulepreload" crossorigin href="/assets/forensic-log-z_FcTaq6.js">
-    <link rel="modulepreload" crossorigin href="/assets/ErrorBoundary-DRi97B4x.js">
-    <link rel="stylesheet" crossorigin href="/assets/styles-Bh3rgVbO.css">
+    <link rel="modulepreload" crossorigin href="/assets/diff-RnwNJg4F.js">
+    <link rel="modulepreload" crossorigin href="/assets/scheduled-audit-runner-ZCuDk8-r.js">
+    <link rel="modulepreload" crossorigin href="/assets/design-system-audit-DpxJrxnb.js">
+    <link rel="modulepreload" crossorigin href="/assets/ErrorBoundary-C_dGDDCo.js">
+    <link rel="stylesheet" crossorigin href="/assets/styles-BJICDw6s.css">
   </head>
   <body class="bg-slate-50">
     <div id="root"></div>

package/dist/manifest.json CHANGED Viewed

@@ -1,9 +1,8 @@
 {
   "manifest_version": 3,
   "name": "wcagcheckr",
-  "description": "Audit components across hover, focus, dark mode, forced colors, RTL — every state your users actually encounter. Per-component baselines surface only NEW violations.",
-  "version": "1.0.0.99",
-  "version_name": "1.0.0-rc.99",
+  "description": "Audit your real site for WCAG issues across hover, focus, dark mode & RTL states — baselines surface only NEW violations.",
+  "version": "1.0.0",
   "author": "Locustware",
   "homepage_url": "https://wcagcheckr.com",
   "icons": {
@@ -15,12 +14,12 @@
   "permissions": [
     "debugger",
     "storage",
+    "unlimitedStorage",
     "sidePanel",
     "scripting",
     "tabs",
     "alarms",
-    "nativeMessaging",
-    "declarativeNetRequestWithHostAccess",
+    "downloads",
     "offscreen"
   ],
   "host_permissions": [
@@ -38,7 +37,7 @@
   "content_scripts": [
     {
       "js": [
-        "assets/content-script.ts-loader-BjJqq5Xq.js"
+        "assets/content-script.ts-loader-BhZWdOHh.js"
       ],
       "matches": [
         "<all_urls>"
@@ -57,18 +56,18 @@
       ],
       "resources": [
         "side-panel/side-panel.html",
-        "side-panel/*",
         "assets/*",
         "fonts/*",
         "axe.min.js",
         "assets/preload-helper-D7HrI6pR.js",
-        "assets/crash-reporter-Dc5lvxvY.js",
-        "assets/diff-DIBMr3fQ.js",
+        "assets/crash-reporter-KD5f4utB.js",
+        "assets/diff-RnwNJg4F.js",
         "assets/_commonjsHelpers-Cpj98o6Y.js",
         "assets/custom-rules-CAe0nbES.js",
+        "assets/design-system-audit-DpxJrxnb.js",
         "assets/reflow-analyzer-DNgBX8N_.js",
-        "assets/dom-criterion-analyzers-C2gMp3xS.js",
-        "assets/content-script.ts-vGsvD70K.js"
+        "assets/dom-criterion-analyzers-DoUaJV5C.js",
+        "assets/content-script.ts-DUFtdkRn.js"
       ],
       "use_dynamic_url": false
     }

package/dist/offscreen/offscreen.html ADDED Viewed

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>wcagcheckr offscreen worker</title>
+    <script type="module" crossorigin src="/assets/offscreen-BAvM-6sh.js"></script>
+    <link rel="modulepreload" crossorigin href="/assets/modulepreload-polyfill-B5Qt9EMX.js">
+    <link rel="modulepreload" crossorigin href="/assets/preload-helper-D7HrI6pR.js">
+  </head>
+  <body>
+  </body>
+</html>

package/dist/options/options.html CHANGED Viewed

@@ -4,15 +4,15 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>wcagcheckr — Settings</title>
-    <script type="module" crossorigin src="/assets/options-Byz5A0JD.js"></script>
+    <script type="module" crossorigin src="/assets/options-D_6nRFjj.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/modulepreload-polyfill-B5Qt9EMX.js">
     <link rel="modulepreload" crossorigin href="/assets/_commonjsHelpers-Cpj98o6Y.js">
-    <link rel="modulepreload" crossorigin href="/assets/crash-reporter-Dc5lvxvY.js">
-    <link rel="modulepreload" crossorigin href="/assets/state-BIsozXtc.js">
-    <link rel="modulepreload" crossorigin href="/assets/styles-DhnON7zr.js">
-    <link rel="modulepreload" crossorigin href="/assets/ai-usage-log-Dj9Ub_DT.js">
+    <link rel="modulepreload" crossorigin href="/assets/crash-reporter-KD5f4utB.js">
+    <link rel="modulepreload" crossorigin href="/assets/ai-usage-log-CYyG5MT2.js">
+    <link rel="modulepreload" crossorigin href="/assets/styles-B_kTykZT.js">
+    <link rel="modulepreload" crossorigin href="/assets/tier-config-client-85XOCE5d.js">
     <link rel="modulepreload" crossorigin href="/assets/custom-rules-CAe0nbES.js">
-    <link rel="stylesheet" crossorigin href="/assets/styles-Bh3rgVbO.css">
+    <link rel="stylesheet" crossorigin href="/assets/styles-BJICDw6s.css">
   </head>
   <body class="m-0 p-0 bg-slate-50">
     <div id="root"></div>

package/dist/service-worker-loader.js CHANGED Viewed

	@@ -1 +1 @@
1	- import './assets/service-worker.ts-~~BeULiNbt~~.js';
1	+ import './assets/service-worker.ts-CvO1EqpM.js';

package/dist/side-panel/side-panel.html CHANGED Viewed

@@ -4,16 +4,22 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>WCAG Component Auditor</title>
-    <script type="module" crossorigin src="/assets/side-panel-C-Jo4m74.js"></script>
+    <script type="module" crossorigin src="/assets/side-panel-DaVp_XgU.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/modulepreload-polyfill-B5Qt9EMX.js">
     <link rel="modulepreload" crossorigin href="/assets/_commonjsHelpers-Cpj98o6Y.js">
-    <link rel="modulepreload" crossorigin href="/assets/crash-reporter-Dc5lvxvY.js">
-    <link rel="modulepreload" crossorigin href="/assets/state-BIsozXtc.js">
-    <link rel="modulepreload" crossorigin href="/assets/styles-DhnON7zr.js">
+    <link rel="modulepreload" crossorigin href="/assets/crash-reporter-KD5f4utB.js">
+    <link rel="modulepreload" crossorigin href="/assets/ai-usage-log-CYyG5MT2.js">
+    <link rel="modulepreload" crossorigin href="/assets/styles-B_kTykZT.js">
     <link rel="modulepreload" crossorigin href="/assets/preload-helper-D7HrI6pR.js">
-    <link rel="modulepreload" crossorigin href="/assets/forensic-log-z_FcTaq6.js">
-    <link rel="modulepreload" crossorigin href="/assets/ErrorBoundary-DRi97B4x.js">
-    <link rel="stylesheet" crossorigin href="/assets/styles-Bh3rgVbO.css">
+    <link rel="modulepreload" crossorigin href="/assets/diff-RnwNJg4F.js">
+    <link rel="modulepreload" crossorigin href="/assets/scheduled-audit-runner-ZCuDk8-r.js">
+    <link rel="modulepreload" crossorigin href="/assets/design-system-audit-DpxJrxnb.js">
+    <link rel="modulepreload" crossorigin href="/assets/ErrorBoundary-C_dGDDCo.js">
+    <link rel="modulepreload" crossorigin href="/assets/copy-ai-fixer-prompt-B-MMXqXA.js">
+    <link rel="modulepreload" crossorigin href="/assets/tier-config-client-85XOCE5d.js">
+    <link rel="modulepreload" crossorigin href="/assets/rubric-config-client-DvjbA4nG.js">
+    <link rel="stylesheet" crossorigin href="/assets/styles-BJICDw6s.css">
+    <link rel="stylesheet" crossorigin href="/assets/side-panel-Cq-w2yTn.css">
   </head>
   <body class="m-0 p-0">
     <div id="root"></div>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@wcag-checkr/ci",
-  "version": "1.0.0-rc.99",
+  "version": "1.0.0",
   "private": false,
   "description": "Headless wcagcheckr accessibility audit runner for CI/CD pipelines. Drives the wcagcheckr Chrome extension via Playwright, runs full-page audits across the state matrix (108 combinations: hover, focus, dark mode, RTL, breakpoints), outputs JSON / SARIF / JUnit, exits with severity-aware codes.",
   "license": "UNLICENSED",
@@ -21,6 +21,7 @@
     "node": ">=20.18"
   },
   "dependencies": {
+    "pdfjs-dist": "^4.10.38",
     "playwright": "^1.59.1"
   },
   "repository": {

package/wcagcheckr-ci.mjs CHANGED Viewed

@@ -68,6 +68,10 @@ function parseArgs(argv) {
       args.inputFile = a;
       continue;
     }
+    if (args.command === 'pdf' && !args.pdfTarget && !a.startsWith('--')) {
+      args.pdfTarget = a;
+      continue;
+    }
     if (a === '--format') args.format = argv[++i];
     else if (a === '--output') args.output = argv[++i];
     else if (a === '--threshold') args.threshold = argv[++i];
@@ -76,6 +80,9 @@ function parseArgs(argv) {
     else if (a === '--quiet') args.quiet = true;
     else if (a === '--license') args.license = argv[++i];
     else if (a === '--public-key-url') args.publicKeyUrl = argv[++i];
+    else if (a === '--watch') args.watch = true;
+    else if (a === '--watch-dir') args.watchDir = argv[++i];
+    else if (a === '--watch-debounce') args.watchDebounce = parseInt(argv[++i], 10);
     else if (a === '--help' || a === '-h') args.help = true;
   }
   return args;
@@ -87,6 +94,13 @@ function printUsage() {
 Usage:
   wcagcheckr-ci audit <url> [options]
   wcagcheckr-ci verify <forensic-log.json> [options]
+  wcagcheckr-ci pdf <path-or-url> [options]
+pdf options:
+  --output <file>                 Write JSON report to file
+  --threshold <none|critical|serious|moderate|minor>
+                                  Severity gate for non-zero exit
+  --quiet                         Suppress progress output
 audit options:
   --format <json|sarif|junit>     Output format (default: json)
@@ -97,6 +111,12 @@ audit options:
   --timeout <ms>                  Audit timeout (default: 120000)
   --license <token>               Activate this license token before auditing
                                   (gates paid features like forensic anchoring)
+  --watch                         Stay open after the initial audit and re-run
+                                  whenever a file under --watch-dir changes
+  --watch-dir <path>              Directory to watch when --watch is on
+                                  (default: current working directory)
+  --watch-debounce <ms>           Debounce window after a change before
+                                  re-auditing (default: 1500)
   --quiet                         Suppress progress output
 verify options:
@@ -137,6 +157,52 @@ if (args.command === 'verify') {
   // runVerify exits the process itself.
 }
+// ─── pdf subcommand (rc.153, G3) ────────────────────────────────────────────
+//
+// Metadata-level PDF accessibility audit. No page rendering — checks
+// the document Catalog for tagged status, document language, title,
+// structure-tree root. The #1 PDF accessibility failure (untagged) is
+// catchable at this level.
+if (args.command === 'pdf') {
+  if (!args.pdfTarget) {
+    console.error('✗ pdf: missing PDF path or URL.\n');
+    printUsage();
+    process.exit(2);
+  }
+  const { auditPdfFile, auditPdfUrl } = await import('./pdf-audit.mjs');
+  const isUrl = /^https?:\/\//.test(args.pdfTarget);
+  log(`auditing PDF metadata for ${args.pdfTarget}`);
+  const result = isUrl
+    ? await auditPdfUrl(args.pdfTarget)
+    : await auditPdfFile(args.pdfTarget);
+  if (!result.ok) {
+    console.error(`✗ ${result.fatalError ?? 'PDF audit failed.'}`);
+    process.exit(2);
+  }
+  if (args.output) {
+    const { writeFileSync } = await import('node:fs');
+    writeFileSync(args.output, JSON.stringify(result, null, 2), 'utf8');
+    log(`output written to ${args.output}`);
+  } else {
+    process.stdout.write(JSON.stringify(result, null, 2));
+    process.stdout.write('\n');
+  }
+  const exceeds = args.threshold === 'none'
+    ? false
+    : result.findings.some((f) => {
+        const rank = SEVERITY_RANK[f.impact];
+        const cap = SEVERITY_RANK[args.threshold];
+        return rank <= cap;
+      });
+  log(
+    `${result.findings.length} finding${result.findings.length === 1 ? '' : 's'} ` +
+    `(version ${result.version ?? '?'}, tagged=${result.metadata?.tagged ?? '?'}, ` +
+    `lang=${result.metadata?.lang ?? '?'}, title=${result.metadata?.title ? 'yes' : 'no'})`,
+  );
+  process.exit(exceeds ? 1 : 0);
+}
 if (args.command !== 'audit' || !args.url) {
   console.error(`✗ Unknown command or missing URL.\n`);
   printUsage();
@@ -162,6 +228,9 @@ if (!['none', 'critical', 'serious', 'moderate', 'minor'].includes(args.threshol
 log(`Loading extension from ${EXT_DIR}`);
 log(`Auditing ${args.url} (threshold: ${args.threshold}, format: ${args.format})`);
+if (args.watch) {
+  log(`watch mode ON — re-audits on file changes under ${args.watchDir ?? process.cwd()}`);
+}
 // Chrome extensions cannot load in legacy `headless: true` mode, so we
 // pass `--headless=new` as a Chromium arg (the modern headless mode that
@@ -179,8 +248,10 @@ const context = await chromium.launchPersistentContext('', {
 });
 let exitCode = 0;
+let targetPage;
+let sidePanel;
 try {
-  const [targetPage] = context.pages();
+  [targetPage] = context.pages();
   await targetPage.goto(args.url, { waitUntil: 'domcontentloaded', timeout: 30_000 });
   log('target page loaded');
@@ -193,38 +264,69 @@ try {
   if (!extId) throw new Error('extension SW did not register within 10s');
   log(`extension loaded (id: ${extId.slice(0, 8)}…)`);
-  const sidePanel = await context.newPage();
+  sidePanel = await context.newPage();
   await sidePanel.goto(`chrome-extension://${extId}/side-panel/side-panel.html`);
-  // Headless persona — pick dev mode if wizard appears.
-  const devButton = sidePanel.getByRole('button', { name: /developer or agency/i });
-  if (await devButton.isVisible({ timeout: 5_000 }).catch(() => false)) {
-    await devButton.click();
-    await sidePanel.waitForTimeout(500);
+  // rc.380 — Set dev mode explicitly. The persona wizard was removed in rc.333;
+  // the default persona is owner, which has no audit controls. Set userMode in
+  // storage and reload so the dev surface renders, then wait for the audit-mode
+  // select (the reliable dev-ready signal; the old "wcagcheckr" h1 moved).
+  await sidePanel.evaluate(() => chrome.storage.local.set({ userMode: 'dev', v2UiEnabled: false }));
+  await sidePanel.reload({ waitUntil: 'load' });
+  await sidePanel.waitForTimeout(500);
+  for (let i = 0; i < 5; i++) {
+    const gotIt = sidePanel.getByRole('button', { name: 'Got it' });
+    const next = sidePanel.getByRole('button', { name: 'Next' });
+    if (await gotIt.isVisible({ timeout: 400 }).catch(() => false)) { await gotIt.click(); break; }
+    if (await next.isVisible({ timeout: 400 }).catch(() => false)) { await next.click(); await sidePanel.waitForTimeout(120); continue; }
+    break;
   }
-  await sidePanel.waitForSelector('h1:has-text("wcagcheckr")', { timeout: 10_000 });
-  // Activate license token, if provided. Gated paid features (forensic
-  // anchoring, AI-summary, etc.) need an active license at audit time.
-  if (args.license) {
-    log('activating license token');
-    const activated = await sidePanel.evaluate(
-      async (token) =>
-        await new Promise((resolve) => {
-          chrome.runtime.sendMessage(
-            { type: 'LICENSE_SET_REQUEST', token },
-            (response) => resolve(response ?? null),
-          );
-        }),
-      args.license,
+  await sidePanel.waitForSelector('select[aria-label="Audit mode"]', { timeout: 10_000 });
+  // rc.124 — Headless-build lockdown gate. A team license is required to
+  // run audits during the private build phase. If --license is omitted
+  // OR validates to a non-team tier, refuse before doing any audit work.
+  if (!args.license) {
+    throw new Error(
+      'wcagcheckr is in private build phase. A team license is required to use the CLI. ' +
+      'Pass --license <token>. Email cliff@locustware.com for beta access.',
+    );
+  }
+  log('activating license token');
+  const activated = await sidePanel.evaluate(
+    async (token) =>
+      await new Promise((resolve) => {
+        chrome.runtime.sendMessage(
+          { type: 'LICENSE_SET_REQUEST', token },
+          (response) => resolve(response ?? null),
+        );
+      }),
+    args.license,
+  );
+  if (!activated || !activated.validated) {
+    throw new Error(
+      `license activation failed — got ${JSON.stringify(activated)}`,
+    );
+  }
+  // Per the headless-build strategy, only team-tier licenses can use the CLI.
+  // At launch this constraint relaxes per per-feature tier mapping.
+  if (activated.tier !== 'team') {
+    throw new Error(
+      `wcagcheckr CLI requires a team-tier license during private build (got tier='${activated.tier}'). ` +
+      'Email cliff@locustware.com for beta access.',
+    );
+  }
+  // rc.342 — Per-feature tier gate. The lockdown above is the launch-flip
+  // kill-switch; this is the canonical per-feature gate post-launch.
+  // `features.cliRunner === false` blocks; undefined falls through as
+  // "permissive default" (matches the extension's behavior).
+  if (activated.features && activated.features.cliRunner === false) {
+    throw new Error(
+      `wcagcheckr CLI is not available on your current plan (tier='${activated.tier}'). ` +
+      'Upgrade your plan at https://wcagcheckr.com/pricing.',
     );
-    if (!activated || activated.tier === 'free') {
-      throw new Error(
-        `license activation did not yield a paid tier — got ${JSON.stringify(activated)}`,
-      );
-    }
-    log(`license active — tier: ${activated.tier}`);
   }
+  log(`license active — tier: ${activated.tier}`);
   // Skip onboarding tour
   for (let i = 0; i < 5; i++) {
@@ -242,21 +344,63 @@ try {
     break;
   }
-  await sidePanel.getByLabel('Audit mode').selectOption('full-page');
-  await targetPage.bringToFront();
-  await targetPage.waitForTimeout(500);
-  await sidePanel.bringToFront();
-  await sidePanel.waitForTimeout(300);
-  await sidePanel.getByRole('button', { name: /Scan page|Auditing/ }).click();
-  log('audit started');
+  // The per-audit work: navigate target (re-load on subsequent runs to
+  // pick up code changes), kick off the scan, wait for completion, export,
+  // print, threshold-check. Returns the exit code that THIS audit pass
+  // should produce — the watch loop overall stays at 0 until Ctrl+C.
+  async function runOneAudit() {
+    // On re-runs, navigate the target page again so it picks up source
+    // changes (assumes the dev server hot-reloads or the URL serves fresh
+    // content).
+    await targetPage.bringToFront();
+    await targetPage.reload({ waitUntil: 'domcontentloaded', timeout: 30_000 });
+    await targetPage.waitForTimeout(500);
+    await sidePanel.bringToFront();
+    await sidePanel.waitForTimeout(300);
+    await sidePanel.getByLabel('Audit mode').selectOption('full-page');
+    // rc.380 — Arm the completion listener BEFORE clicking. The post-audit
+    // summary text the CLI used to poll for ("N states · M unique violations")
+    // was removed in the rc.313–320 UI rebuild; AUDIT_COMPLETE_EVENT is the
+    // UI-independent signal the side panel itself listens for.
+    await sidePanel.evaluate(() => {
+      globalThis.__cliAuditOutcome = new Promise((res) => {
+        const l = (m) => {
+          if (m?.type === 'AUDIT_COMPLETE_EVENT') { chrome.runtime.onMessage.removeListener(l); res('completed'); }
+          else if (m?.type === 'AUDIT_FAILED_EVENT') { chrome.runtime.onMessage.removeListener(l); res('failed'); }
+        };
+        chrome.runtime.onMessage.addListener(l);
+      });
+    });
+    await sidePanel.getByRole('button', { name: /Scan page|Auditing/ }).click();
+    log('audit started');
+    const outcome = await sidePanel.evaluate(
+      (ms) => Promise.race([
+        globalThis.__cliAuditOutcome,
+        new Promise((r) => setTimeout(() => r('timeout'), ms)),
+      ]),
+      args.timeout,
+    );
+    if (outcome !== 'completed') {
+      throw new Error(`audit did not complete (${outcome}) within ${args.timeout}ms`);
+    }
+    log('audit completed');
-  await sidePanel
-    .getByText(/\d+\s+states?\s+·\s+\d+\s+unique\s+violations?/, { exact: false })
-    .waitFor({ timeout: args.timeout });
-  log('audit completed');
+    return await collectResults();
+  }
+  // Result-export + threshold-check, extracted so runOneAudit returns the
+  // exit code suggestion. Closure over `args`, `sidePanel`, etc.
+  async function collectResults() {
+    return await doExportAndThresholdCheck();
+  }
+  await runOneAudit();
   // Trigger the existing export pipeline. The SW handles EXPORT_REQUEST and
   // returns the formatted content for the requested format.
+  async function doExportAndThresholdCheck() {
   const formatMap = { json: 'json', sarif: 'sarif', junit: 'junit' };
   const exportFormat = formatMap[args.format];
@@ -340,6 +484,61 @@ try {
       log(`✓ threshold not exceeded (--threshold=${args.threshold})`);
     }
   }
+  } // end doExportAndThresholdCheck
+  // Watch mode: keep the browser open, watch the directory tree, re-audit
+  // on change (debounced). Ctrl+C exits.
+  if (args.watch) {
+    const watchDir = args.watchDir ?? process.cwd();
+    const debounceMs = args.watchDebounce ?? 1500;
+    const { watch } = await import('node:fs');
+    log(`watching ${watchDir} (debounce ${debounceMs}ms) — Ctrl+C to exit`);
+    let pending = false;
+    let inFlight = false;
+    let runCount = 1;
+    function trigger() {
+      if (inFlight) {
+        pending = true;
+        return;
+      }
+      inFlight = true;
+      setTimeout(async () => {
+        try {
+          runCount++;
+          log(`\n── Re-audit #${runCount} ──`);
+          await runOneAudit();
+          if (pending) {
+            pending = false;
+            inFlight = false;
+            trigger();
+          } else {
+            inFlight = false;
+          }
+        } catch (err) {
+          log(`re-audit failed: ${err.message}`);
+          inFlight = false;
+        }
+      }, debounceMs);
+    }
+    try {
+      watch(watchDir, { recursive: true }, (eventType, filename) => {
+        // Skip noise: node_modules, dist artifacts, .git, dotfiles other
+        // than the typical source files.
+        if (!filename) return;
+        const f = String(filename);
+        if (f.includes('node_modules')) return;
+        if (f.includes('.git')) return;
+        if (f.includes('/dist/') || f.startsWith('dist/') || f.includes('\\dist\\') || f.startsWith('dist\\')) return;
+        log(`change: ${f}`);
+        trigger();
+      });
+    } catch (err) {
+      log(`fs.watch failed (recursive may not be supported on this platform): ${err.message}`);
+      log('watch mode disabled; exiting after this audit.');
+    }
+    // Block forever until the user kills the process.
+    await new Promise(() => {});
+  }
 } catch (err) {
   console.error(`✗ ${err.message}`);
   if (err.stack && !args.quiet) console.error(err.stack);