@wcag-checkr/ci 1.0.0-rc.13

package/dist/side-panel/github-issue.test.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect } from 'vitest';
+import { buildGithubIssueUrl } from './github-issue';
+import { DEFAULT_BREAKPOINT_PRESETS } from '../types/state';
+import type { Violation } from '../types/audit';
+
+const desktop = DEFAULT_BREAKPOINT_PRESETS.find((p) => p.id === 'desktop')!;
+
+function v(overrides: Partial<Violation> = {}): Violation {
+  return {
+    ruleId: 'color-contrast',
+    wcagCriterion: 'wcag143',
+    wcagLevel: 'AA',
+    impact: 'serious',
+    description: 'Insufficient contrast',
+    helpUrl: 'https://example.com/r',
+    target: {
+      selector: '#btn',
+      outerHTML: '<button id="btn">Go</button>',
+      failureSummary: '',
+      tagName: 'BUTTON',
+      role: null,
+      accessibleName: 'Go',
+      textSnippet: 'Go',
+      attrId: 'btn',
+      attrTestid: null,
+    },
+    componentId: '::cmp::btn',
+    currentState: {
+      pseudoState: 'default',
+      ariaVariation: null,
+      theme: 'light',
+      direction: 'ltr',
+      breakpoint: desktop,
+    },
+    axeVersion: '4.11.4',
+    detectedAt: '2026-05-04T00:00:00Z',
+    matchKey: 'mk-1',
+    ...overrides,
+  };
+}
+
+describe('buildGithubIssueUrl', () => {
+  it('produces a /issues/new URL pointing at the configured repo', () => {
+    const r = buildGithubIssueUrl('https://github.com/foo/bar', '::cmp::x', [v()]);
+    expect(r.url.startsWith('https://github.com/foo/bar/issues/new?')).toBe(true);
+  });
+
+  it('strips trailing slash from repo URL', () => {
+    const r = buildGithubIssueUrl('https://github.com/foo/bar/', '::x', [v()]);
+    expect(r.url.startsWith('https://github.com/foo/bar/issues/new?')).toBe(true);
+  });
+
+  it('puts violation count in the title', () => {
+    const r = buildGithubIssueUrl('https://github.com/foo/bar', '::x', [
+      v({ matchKey: 'm1' }),
+      v({ matchKey: 'm2', ruleId: 'image-alt' }),
+    ]);
+    expect(r.title).toMatch(/2 new violations/);
+  });
+
+  it('singular vs plural in title', () => {
+    const r = buildGithubIssueUrl('https://github.com/foo/bar', '::x', [v()]);
+    expect(r.title).toMatch(/1 new violation in/);
+    expect(r.title).not.toMatch(/violations/);
+  });
+
+  it('dedupes violations sharing the same logical key (rule + selector)', () => {
+    const a = v({ matchKey: 'm1', currentState: { ...v().currentState, pseudoState: 'hover' } });
+    const b = v({ matchKey: 'm2', currentState: { ...v().currentState, pseudoState: 'focus' } });
+    const r = buildGithubIssueUrl('https://github.com/foo/bar', '::x', [a, b]);
+    // Title says 1 violation (deduped), body lists both states.
+    expect(r.title).toMatch(/1 new violation/);
+    expect(r.body).toMatch(/:hover/);
+    expect(r.body).toMatch(/:focus/);
+  });
+
+  it('includes selector, helpUrl, and outerHTML in the body', () => {
+    const r = buildGithubIssueUrl('https://github.com/foo/bar', '::x', [
+      v({
+        target: {
+          ...v().target,
+          selector: '.my-thing',
+          outerHTML: '<button class="my-thing">x</button>',
+        },
+        helpUrl: 'https://example.com/help-link',
+      }),
+    ]);
+    expect(r.body).toContain('.my-thing');
+    expect(r.body).toContain('https://example.com/help-link');
+    expect(r.body).toContain('<button class="my-thing">x</button>');
+  });
+
+  it('truncates the URL when it gets absurdly long', () => {
+    const huge = 'x'.repeat(20000);
+    const r = buildGithubIssueUrl('https://github.com/foo/bar', '::x', [
+      v({
+        target: { ...v().target, outerHTML: huge },
+      }),
+    ]);
+    expect(r.url.length).toBeLessThanOrEqual(7800);
+  });
+});

package/dist/side-panel/github-issue.ts

@@ -0,0 +1,66 @@
+// Builds a pre-filled GitHub new-issue URL from a set of NEW violations.
+// Pure function — extracted from DeltaView so the URL/body shape is testable.
+
+import type { Violation } from '../types/audit';
+
+export type IssueBuild = { url: string; title: string; body: string };
+
+const URL_LIMIT = 7800;
+
+export function buildGithubIssueUrl(
+  repoUrl: string,
+  componentId: string | null,
+  newViolations: Violation[]
+): IssueBuild {
+  const cleaned = repoUrl.replace(/\/$/, '');
+
+  // Dedup violations by logical key (rule + selector); aggregate states.
+  const groups: Array<Violation & { _states: string[] }> = [];
+  for (const v of newViolations) {
+    const key = `${v.ruleId}::${v.target.selector}`;
+    const stateLabel = `:${v.currentState.pseudoState} · ${v.currentState.theme} · ${v.currentState.direction}`;
+    const existing = groups.find((g) => `${g.ruleId}::${g.target.selector}` === key);
+    if (existing) {
+      if (!existing._states.includes(stateLabel)) existing._states.push(stateLabel);
+      continue;
+    }
+    groups.push({ ...v, _states: [stateLabel] });
+  }
+
+  const title = `a11y: ${groups.length} new violation${groups.length === 1 ? '' : 's'} in ${componentId ?? 'audited component'}`;
+
+  const lines: string[] = [];
+  lines.push(`**Component:** \`${componentId ?? 'unknown'}\``);
+  lines.push('');
+  lines.push(
+    `Detected by WCAG Component Auditor as **new** vs the saved baseline — these are violations introduced since the last accepted baseline.`
+  );
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+  for (const v of groups) {
+    lines.push(`### \`${v.ruleId}\` — ${v.impact}`);
+    lines.push('');
+    lines.push(v.description);
+    lines.push('');
+    lines.push(`- **WCAG:** ${v.wcagCriterion} (${v.wcagLevel})`);
+    lines.push(`- **Selector:** \`${v.target.selector}\``);
+    lines.push(`- **Found in state(s):** ${v._states.join(', ')}`);
+    if (v.helpUrl) lines.push(`- **More info:** ${v.helpUrl}`);
+    lines.push('');
+    lines.push('```html');
+    lines.push(v.target.outerHTML);
+    lines.push('```');
+    lines.push('');
+  }
+  lines.push('---');
+  lines.push('');
+  lines.push('_Filed via WCAG Component Auditor (delta-only — inherited debt not included)._');
+
+  const body = lines.join('\n');
+  const params = new URLSearchParams({ title, body });
+  let url = `${cleaned}/issues/new?${params.toString()}`;
+  if (url.length > URL_LIMIT) url = url.slice(0, URL_LIMIT);
+
+  return { url, title, body };
+}

package/dist/side-panel/jira-issue.ts

@@ -0,0 +1,64 @@
+// Builds a pre-filled Jira create-issue URL from a set of NEW violations.
+// Mirrors the GitHub flow but targets Jira Cloud's CreateIssue URL params.
+// Description field is plain text; we keep formatting minimal so it reads
+// cleanly in Jira's default text view (markdown won't render natively).
+
+import type { Violation } from '../types/audit';
+
+export type JiraIssueBuild = { url: string; summary: string; description: string };
+
+const URL_LIMIT = 7800;
+
+export function buildJiraIssueUrl(
+  instanceUrl: string,
+  componentId: string | null,
+  newViolations: Violation[]
+): JiraIssueBuild {
+  const cleaned = instanceUrl.replace(/\/$/, '');
+
+  // Dedup violations by logical key (rule + selector); aggregate states.
+  const groups: Array<Violation & { _states: string[] }> = [];
+  for (const v of newViolations) {
+    const key = `${v.ruleId}::${v.target.selector}`;
+    const stateLabel = `:${v.currentState.pseudoState} · ${v.currentState.theme} · ${v.currentState.direction}`;
+    const existing = groups.find((g) => `${g.ruleId}::${g.target.selector}` === key);
+    if (existing) {
+      if (!existing._states.includes(stateLabel)) existing._states.push(stateLabel);
+      continue;
+    }
+    groups.push({ ...v, _states: [stateLabel] });
+  }
+
+  const summary = `a11y: ${groups.length} new violation${groups.length === 1 ? '' : 's'} in ${componentId ?? 'audited component'}`;
+
+  const lines: string[] = [];
+  lines.push(`Component: ${componentId ?? 'unknown'}`);
+  lines.push('');
+  lines.push(
+    `Detected by WCAG Component Auditor as NEW vs the saved baseline — these are violations introduced since the last accepted baseline.`
+  );
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+  for (const v of groups) {
+    lines.push(`Rule: ${v.ruleId} (${v.impact})`);
+    lines.push(`WCAG: ${v.wcagCriterion} ${v.wcagLevel}`);
+    lines.push(`Description: ${v.description}`);
+    lines.push(`Selector: ${v.target.selector}`);
+    lines.push(`Found in state(s): ${v._states.join(', ')}`);
+    if (v.helpUrl) lines.push(`More info: ${v.helpUrl}`);
+    lines.push('');
+    lines.push(`HTML: ${v.target.outerHTML}`);
+    lines.push('');
+    lines.push('---');
+    lines.push('');
+  }
+  lines.push('Filed via WCAG Component Auditor (delta-only — inherited debt not included).');
+
+  const description = lines.join('\n');
+  const params = new URLSearchParams({ summary, description });
+  let url = `${cleaned}/secure/CreateIssue!default.jspa?${params.toString()}`;
+  if (url.length > URL_LIMIT) url = url.slice(0, URL_LIMIT);
+
+  return { url, summary, description };
+}

package/dist/side-panel/main.tsx

@@ -0,0 +1,19 @@
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import { App } from './App';
+import { ErrorBoundary } from './components/ErrorBoundary';
+import { installCrashReporter } from '../modules/crash-reporter';
+import './styles.css';
+
+installCrashReporter('side-panel');
+
+const root = document.getElementById('root');
+if (!root) throw new Error('side-panel: #root not found');
+
+createRoot(root).render(
+  <React.StrictMode>
+    <ErrorBoundary>
+      <App />
+    </ErrorBoundary>
+  </React.StrictMode>
+);

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

@@ -0,0 +1,21 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <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/modulepreload-polyfill-B5Qt9EMX.js"></script>
+    <script type="module" crossorigin src="/assets/_commonjsHelpers-Cpj98o6Y.js"></script>
+    <script type="module" crossorigin src="/assets/crash-reporter-wxu43qbG.js"></script>
+    <script type="module" crossorigin src="/assets/state-DnzwwNxZ.js"></script>
+    <script type="module" crossorigin src="/assets/styles-kHMb1Lda.js"></script>
+    <script type="module" crossorigin src="/assets/preload-helper-D7HrI6pR.js"></script>
+    <script type="module" crossorigin src="/assets/forensic-log-B3iX62mE.js"></script>
+    <script type="module" crossorigin src="/assets/ErrorBoundary-BPz4qckm.js"></script>
+    <script type="module" crossorigin src="/assets/main-DyQfCbPM.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/styles-DP9v_aMy.css">
+  </head>
+  <body class="m-0 p-0">
+    <div id="root"></div>
+  </body>
+</html>

package/dist/side-panel/store.ts

@@ -0,0 +1,264 @@
+// Zustand store for side panel state.
+// Spec: phase-1-specs.md §9.
+
+import { create } from 'zustand';
+import type { AuditResult, DeltaResult } from '../types/audit';
+import type { StateConfig } from '../types/state';
+import type { LicenseTier } from '../shared/messages';
+import type { InAppMessage } from '../modules/messages-client';
+import type { SiteCrawlReport } from '../shared/site-aggregator';
+
+export type AuditStatus = 'idle' | 'running' | 'complete' | 'failed' | 'interrupted';
+export type View = 'matrix' | 'delta' | 'activity' | 'guided' | 'flows' | 'scorecard' | 'crawl' | 'forensic' | 'compliance';
+/** Two distinct personas: site owners (mom-and-pop, no code) vs developers
+ * (full feature surface, CLI-friendly outputs, baselines, exports). */
+export type UserMode = 'owner' | 'dev';
+
+type Store = {
+  // audit
+  status: AuditStatus;
+  progress: { current: number; total: number; currentState?: StateConfig } | null;
+  results: AuditResult[];
+  delta: DeltaResult | null;
+  componentId: string | null;
+  errorMessage: string | null;
+  /** True only when results came from a scan that completed during this side-panel
+   * session. False when results were rehydrated from `loadLastAudit` — in that case
+   * the score UI should mark the grade as "stale, re-scan to refresh" rather than
+   * imply it reflects the page's current state. */
+  freshThisSession: boolean;
+
+  // baselines
+  baselineList: Array<{
+    componentId: string;
+    violationCount: number;
+    lastUpdated: string;
+    seenOnUrlsCount?: number;
+    metrics?: import('../shared/messages').BaselineSummaryMetrics;
+  }>;
+
+  // license
+  tier: LicenseTier;
+  /** Trial-tier countdown. null = unknown / not on trial. */
+  trialDaysRemaining: number | null;
+  /** Team-tier seat consumption. null = server hasn't emitted seat info. */
+  seatsUsed: number | null;
+  seatsTotal: number | null;
+  /** Server's actual plan code for the active license — `solo`, `solo-yearly`,
+   *  `solo-single-month`, `team`, `team-15`. Lets the UpgradeCard tell apart
+   *  the recurring SKUs from the one-time single-month pass even though they
+   *  all map to tier='solo' or tier='team' for capability gating. */
+  planCode: string | null;
+  /** Days until the active one-time license (e.g. solo-single-month) expires.
+   *  null for recurring subscriptions. */
+  licenseDaysRemaining: number | null;
+  /** True when Stripe reported the most recent invoice payment as failed.
+   *  License stays valid during the grace period but UI surfaces the
+   *  failure prominently so the user updates their card before access cuts. */
+  pastDue: boolean;
+
+  // in-app messages
+  messages: InAppMessage[];
+  unreadMessageCount: number;
+  criticalUnacked: boolean;
+
+  // ui
+  view: View;
+  /** Persona-driven UI mode. `null` = first-launch (wizard not yet answered). */
+  userMode: UserMode | null;
+
+  // site crawl
+  siteCrawlStatus: 'idle' | 'running' | 'complete' | 'failed';
+  siteCrawlProgress: { current: number; total: number; url: string; lastViolations?: number } | null;
+  siteCrawlReport: SiteCrawlReport | null;
+  siteCrawlError: string | null;
+
+  // highlight pin: which violation row is currently showing its overlay on the page,
+  // and whether its selector resolved (false → render "not in current state" hint).
+  pinnedMatchKey: string | null;
+  pinnedFound: boolean;
+
+  // AI augmentation failure surface — shown as a dismissible banner above the
+  // results area when an audit's AI portion errored despite a configured key.
+  // Cleared whenever a new audit starts or completes cleanly.
+  aiFailure: {
+    severity: 'total' | 'partial';
+    reason: string;
+    checksAttempted: number;
+    checksSucceeded: number;
+    checksErrored: number;
+    errorDetails: string[];
+  } | null;
+
+  // AI augmentation in-flight progress. Drives the post-matrix progress line:
+  // matrix loop owns 1..N states, then AI augmentation takes over and the bar
+  // shows e.g. "AI: 3/8 — Verifying alt text…". Cleared when AUDIT_COMPLETE
+  // fires or a new scan starts.
+  aiProgress: {
+    currentCheckLabel: string;
+    current: number;
+    total: number;
+  } | null;
+
+  // actions
+  setStatus: (s: AuditStatus) => void;
+  /** Begin a new scan: flips status to 'running' AND clears prior results,
+   * delta, error, and progress so the panel doesn't show stale data from the
+   * previous site under the new "Scanning…" indicator. Use this from every
+   * START_AUDIT dispatch site instead of setStatus('running') alone. */
+  startNewScan: () => void;
+  setProgress: (p: Store['progress']) => void;
+  setResults: (results: AuditResult[], delta: DeltaResult | null, componentId: string) => void;
+  setDelta: (delta: DeltaResult | null) => void;
+  setError: (message: string) => void;
+  setBaselineList: (list: Store['baselineList']) => void;
+  /** Wipe the current audit (results, delta, componentId, error, progress).
+   *  Used by the user-triggered Clear button and by auto-clear when the user
+   *  navigates the audit target to a different URL. Baselines + forensic
+   *  history are NOT touched — those are persistent records. */
+  clearResults: () => void;
+  setTier: (
+    tier: LicenseTier,
+    extras?: {
+      trialDaysRemaining?: number;
+      seatsUsed?: number;
+      seatsTotal?: number;
+      planCode?: string | null;
+      licenseDaysRemaining?: number;
+      pastDue?: boolean;
+    }
+  ) => void;
+  setView: (v: View) => void;
+  setUserMode: (m: UserMode | null) => void;
+  setSiteCrawlStatus: (s: Store['siteCrawlStatus']) => void;
+  setSiteCrawlProgress: (p: Store['siteCrawlProgress']) => void;
+  setSiteCrawlReport: (r: SiteCrawlReport | null) => void;
+  setSiteCrawlError: (e: string | null) => void;
+  setPinned: (matchKey: string | null, found?: boolean) => void;
+  setAiFailure: (failure: Store['aiFailure']) => void;
+  clearAiFailure: () => void;
+  setAiProgress: (progress: Store['aiProgress']) => void;
+  /** Replace the in-app messages list + counters. Called by wire-messaging
+   *  after a refresh from the server. */
+  setMessages: (messages: InAppMessage[], unreadCount: number, criticalUnacked: boolean) => void;
+  /** Mark a message as locally seen/dismissed/acknowledged so the UI updates
+   *  immediately without waiting for the next server refresh. */
+  applyMessageAck: (messageId: number, action: 'seen' | 'dismissed' | 'acknowledged' | 'clicked') => void;
+};
+
+export const useStore = create<Store>((set) => ({
+  status: 'idle',
+  progress: null,
+  results: [],
+  delta: null,
+  componentId: null,
+  errorMessage: null,
+  freshThisSession: false,
+  baselineList: [],
+  tier: 'trial',
+  trialDaysRemaining: null,
+  seatsUsed: null,
+  seatsTotal: null,
+  planCode: null,
+  licenseDaysRemaining: null,
+  pastDue: false,
+  messages: [],
+  unreadMessageCount: 0,
+  criticalUnacked: false,
+  view: 'matrix',
+  userMode: null,
+  siteCrawlStatus: 'idle',
+  siteCrawlProgress: null,
+  siteCrawlReport: null,
+  siteCrawlError: null,
+  pinnedMatchKey: null,
+  pinnedFound: true,
+  aiFailure: null,
+  aiProgress: null,
+
+  setStatus: (status) => set({ status }),
+  startNewScan: () =>
+    set({
+      status: 'running',
+      results: [],
+      delta: null,
+      errorMessage: null,
+      progress: null,
+      componentId: null,
+      pinnedMatchKey: null,
+      pinnedFound: true,
+      aiFailure: null,
+      aiProgress: null,
+      // freshThisSession stays false until setResults fires.
+    }),
+  setProgress: (progress) => set({ progress }),
+  setResults: (results, delta, componentId) =>
+    set({
+      results,
+      delta,
+      componentId,
+      status: 'complete',
+      errorMessage: null,
+      freshThisSession: true,
+      aiProgress: null,
+      // New audit invalidates any prior pin.
+      pinnedMatchKey: null,
+      pinnedFound: true,
+    }),
+  setDelta: (delta) => set({ delta }),
+  setError: (errorMessage) => set({ errorMessage, status: 'failed' }),
+  setBaselineList: (baselineList) => set({ baselineList }),
+  clearResults: () =>
+    set({
+      results: [],
+      delta: null,
+      componentId: null,
+      errorMessage: null,
+      progress: null,
+      status: 'idle',
+      freshThisSession: false,
+      pinnedMatchKey: null,
+      pinnedFound: true,
+      aiFailure: null,
+      aiProgress: null,
+    }),
+  setTier: (tier, extras) =>
+    set({
+      tier,
+      trialDaysRemaining: extras?.trialDaysRemaining ?? null,
+      seatsUsed: extras?.seatsUsed ?? null,
+      seatsTotal: extras?.seatsTotal ?? null,
+      planCode: extras?.planCode ?? null,
+      licenseDaysRemaining: extras?.licenseDaysRemaining ?? null,
+      pastDue: extras?.pastDue ?? false,
+    }),
+  setView: (view) => set({ view }),
+  setUserMode: (userMode) => set({ userMode }),
+  setSiteCrawlStatus: (siteCrawlStatus) => set({ siteCrawlStatus }),
+  setSiteCrawlProgress: (siteCrawlProgress) => set({ siteCrawlProgress }),
+  setSiteCrawlReport: (siteCrawlReport) => set({ siteCrawlReport }),
+  setSiteCrawlError: (siteCrawlError) => set({ siteCrawlError }),
+  setPinned: (matchKey, found = true) => set({ pinnedMatchKey: matchKey, pinnedFound: found }),
+  setAiFailure: (aiFailure) => set({ aiFailure }),
+  clearAiFailure: () => set({ aiFailure: null }),
+  setAiProgress: (aiProgress) => set({ aiProgress }),
+  setMessages: (messages, unreadMessageCount, criticalUnacked) =>
+    set({ messages, unreadMessageCount, criticalUnacked }),
+  applyMessageAck: (messageId, action) =>
+    set((s) => {
+      const next = s.messages
+        .map((m) => {
+          if (m.id !== messageId) return m;
+          if (action === 'seen') return { ...m, seen: true };
+          if (action === 'dismissed') return { ...m, dismissed: true };
+          if (action === 'acknowledged') return { ...m, acknowledged: true };
+          if (action === 'clicked') return { ...m, clicked: true };
+          return m;
+        })
+        // Drop fully-handled non-critical messages (mirrors server visibility).
+        .filter((m) => (m.severity === 'critical' ? !m.acknowledged : !m.dismissed));
+      const unread = next.filter((m) => !m.seen).length;
+      const critUnacked = next.some((m) => m.severity === 'critical' && !m.acknowledged);
+      return { messages: next, unreadMessageCount: unread, criticalUnacked: critUnacked };
+    }),
+}));

package/dist/side-panel/styles.css

@@ -0,0 +1,16 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+html, body, #root {
+  height: 100%;
+}
+
+/* Tailwind's preflight resets the UA focus ring. Restore a high-contrast
+   ring for keyboard users (only :focus-visible — pointer focus stays clean).
+   Brand-700 #3730a3 over white = 9.6:1 contrast; same ring shows fine on
+   bg-brand-500 buttons too. */
+:focus-visible {
+  outline: 2px solid #3730a3;
+  outline-offset: 2px;
+}