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

@wcag-checkr/ci 1.0.0-rc.13

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 (50) hide show

package/README.md +135 -0
package/dist/assets/ErrorBoundary-BPz4qckm.js +524 -0
package/dist/assets/_commonjsHelpers-Cpj98o6Y.js +1 -0
package/dist/assets/ai-usage-log-DFkwAfmW.js +1 -0
package/dist/assets/content-script.ts-D7yXcBUr.js +181 -0
package/dist/assets/content-script.ts-loader-Cn8Y9Xod.js +13 -0
package/dist/assets/crash-reporter-wxu43qbG.js +4 -0
package/dist/assets/devtools-panel-D2fL4guz.js +1 -0
package/dist/assets/devtools.html-DQBohI9U.js +1 -0
package/dist/assets/diff-D4sCAdXf.js +1 -0
package/dist/assets/forensic-log-B3iX62mE.js +129 -0
package/dist/assets/main-CqDdt0Iq.js +6 -0
package/dist/assets/main-DyQfCbPM.js +1 -0
package/dist/assets/modulepreload-polyfill-B5Qt9EMX.js +1 -0
package/dist/assets/options.html-jfjpxZBp.js +1 -0
package/dist/assets/preload-helper-D7HrI6pR.js +1 -0
package/dist/assets/reflow-analyzer-DNgBX8N_.js +1 -0
package/dist/assets/service-worker.ts-DaHvU8nE.js +715 -0
package/dist/assets/side-panel.html-DW1tssqQ.js +1 -0
package/dist/assets/site-report-renderer-JH44v2hK.js +147 -0
package/dist/assets/state-DnzwwNxZ.js +1 -0
package/dist/assets/styles-DP9v_aMy.css +1 -0
package/dist/assets/styles-kHMb1Lda.js +84 -0
package/dist/devtools/devtools.html +11 -0
package/dist/devtools/panel.html +20 -0
package/dist/fonts/mona-sans-variable.woff2 +0 -0
package/dist/icons/icon-128.png +0 -0
package/dist/icons/icon-16.png +0 -0
package/dist/icons/icon-32.png +0 -0
package/dist/icons/icon-48.png +0 -0
package/dist/manifest.json +70 -0
package/dist/options/options.html +19 -0
package/dist/service-worker-loader.js +1 -0
package/dist/side-panel/App.tsx +174 -0
package/dist/side-panel/README.md +57 -0
package/dist/side-panel/audit-launcher.test.ts +56 -0
package/dist/side-panel/audit-launcher.ts +65 -0
package/dist/side-panel/format-component-id.test.ts +89 -0
package/dist/side-panel/format-component-id.ts +40 -0
package/dist/side-panel/github-issue.test.ts +102 -0
package/dist/side-panel/github-issue.ts +66 -0
package/dist/side-panel/jira-issue.ts +64 -0
package/dist/side-panel/main.tsx +19 -0
package/dist/side-panel/side-panel.html +21 -0
package/dist/side-panel/store.ts +264 -0
package/dist/side-panel/styles.css +16 -0
package/dist/side-panel/wire-messaging.test.ts +202 -0
package/dist/side-panel/wire-messaging.ts +285 -0
package/package.json +39 -0
package/wcagcheckr-ci.mjs +559 -0

package/dist/devtools/devtools.html ADDED Viewed

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>wcagcheckr — DevTools</title>
+    <script type="module" crossorigin src="/assets/devtools.html-DQBohI9U.js"></script>
+    <link rel="modulepreload" crossorigin href="/assets/modulepreload-polyfill-B5Qt9EMX.js">
+  </head>
+  <body>
+  </body>
+</html>

package/dist/devtools/panel.html ADDED Viewed

@@ -0,0 +1,20 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>wcagcheckr</title>
+    <script type="module" crossorigin src="/assets/devtools-panel-D2fL4guz.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-wxu43qbG.js">
+    <link rel="modulepreload" crossorigin href="/assets/state-DnzwwNxZ.js">
+    <link rel="modulepreload" crossorigin href="/assets/styles-kHMb1Lda.js">
+    <link rel="modulepreload" crossorigin href="/assets/preload-helper-D7HrI6pR.js">
+    <link rel="modulepreload" crossorigin href="/assets/forensic-log-B3iX62mE.js">
+    <link rel="modulepreload" crossorigin href="/assets/ErrorBoundary-BPz4qckm.js">
+    <link rel="stylesheet" crossorigin href="/assets/styles-DP9v_aMy.css">
+  </head>
+  <body class="bg-slate-50">
+    <div id="root"></div>
+  </body>
+</html>

package/dist/fonts/mona-sans-variable.woff2 ADDED Viewed

Binary file

package/dist/icons/icon-128.png ADDED Viewed

Binary file

package/dist/icons/icon-16.png ADDED Viewed

Binary file

package/dist/icons/icon-32.png ADDED Viewed

Binary file

package/dist/icons/icon-48.png ADDED Viewed

Binary file

package/dist/manifest.json ADDED Viewed

@@ -0,0 +1,70 @@
+{
+  "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.13",
+  "version_name": "1.0.0-rc.13",
+  "author": "Locustware",
+  "homepage_url": "https://wcagcheckr.com",
+  "icons": {
+    "16": "icons/icon-16.png",
+    "32": "icons/icon-32.png",
+    "48": "icons/icon-48.png",
+    "128": "icons/icon-128.png"
+  },
+  "permissions": [
+    "debugger",
+    "storage",
+    "sidePanel",
+    "scripting",
+    "tabs",
+    "alarms"
+  ],
+  "host_permissions": [
+    "<all_urls>"
+  ],
+  "background": {
+    "service_worker": "service-worker-loader.js",
+    "type": "module"
+  },
+  "side_panel": {
+    "default_path": "side-panel/side-panel.html"
+  },
+  "options_page": "options/options.html",
+  "devtools_page": "devtools/devtools.html",
+  "content_scripts": [
+    {
+      "js": [
+        "assets/content-script.ts-loader-Cn8Y9Xod.js"
+      ],
+      "matches": [
+        "<all_urls>"
+      ],
+      "all_frames": true,
+      "run_at": "document_idle"
+    }
+  ],
+  "action": {
+    "default_title": "wcagcheckr"
+  },
+  "web_accessible_resources": [
+    {
+      "matches": [
+        "<all_urls>"
+      ],
+      "resources": [
+        "side-panel/side-panel.html",
+        "side-panel/*",
+        "assets/*",
+        "fonts/*",
+        "assets/preload-helper-D7HrI6pR.js",
+        "assets/crash-reporter-wxu43qbG.js",
+        "assets/diff-D4sCAdXf.js",
+        "assets/_commonjsHelpers-Cpj98o6Y.js",
+        "assets/reflow-analyzer-DNgBX8N_.js",
+        "assets/content-script.ts-D7yXcBUr.js"
+      ],
+      "use_dynamic_url": false
+    }
+  ]
+}

package/dist/options/options.html ADDED Viewed

@@ -0,0 +1,19 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <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/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/ai-usage-log-DFkwAfmW.js"></script>
+    <script type="module" crossorigin src="/assets/main-CqDdt0Iq.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/styles-DP9v_aMy.css">
+  </head>
+  <body class="m-0 p-0 bg-slate-50">
+    <div id="root"></div>
+  </body>
+</html>

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

	@@ -0,0 +1 @@
1	+ import './assets/service-worker.ts-DaHvU8nE.js';

package/dist/side-panel/App.tsx ADDED Viewed

@@ -0,0 +1,174 @@
+import { useEffect } from 'react';
+import { useStore } from './store';
+import {
+  wireMessaging,
+  refreshBaselineList,
+  refreshLicenseTier,
+  refreshUserMode,
+  startKeepalive,
+  loadLastAudit,
+} from './wire-messaging';
+import { primeAuditLauncher } from './audit-launcher';
+import { sendToTab } from '../shared/messaging';
+import { getAuditTargetTabId } from '../shared/active-tab';
+import { Header } from './components/Header';
+import { AuditControls } from './components/AuditControls';
+import { VisualizerTools } from './components/VisualizerTools';
+import { ProgressBar } from './components/ProgressBar';
+import { MatrixView } from './views/MatrixView';
+import { DeltaView } from './views/DeltaView';
+import { ActivityView } from './views/ActivityView';
+import { GuidedView } from './views/GuidedView';
+import { FlowsView } from './views/FlowsView';
+import { ScorecardView } from './views/ScorecardView';
+import { SiteCrawlPanel } from './components/SiteCrawlPanel';
+import { OnboardingModal } from './components/OnboardingModal';
+import { ErrorBanner } from './components/ErrorBanner';
+import { AiFailureBanner } from './components/AiFailureBanner';
+import { DebuggerBusyModal } from './components/DebuggerBusyModal';
+import { ResumeAuditBanner } from './components/ResumeAuditBanner';
+import { StorybookHint } from './components/StorybookHint';
+import { AuditFooter } from './components/AuditFooter';
+import { ComplianceDisclaimer } from './components/ComplianceDisclaimer';
+import { Announcer } from '../shared/announcer';
+import { UserModeWizard } from './components/UserModeWizard';
+import { OwnerView } from './views/OwnerView';
+import { ForensicLogView } from './views/ForensicLogView';
+import { WcagEmView } from './views/WcagEmView';
+import { UpgradeCard } from './components/UpgradeCard';
+import { CriticalBanner } from './components/MessagesBell';
+export function App() {
+  const view = useStore((s) => s.view);
+  const userMode = useStore((s) => s.userMode);
+  useEffect(() => {
+    const port = startKeepalive();
+    // Detect runtime context: iframe-overlay vs chrome.sidePanel.
+    //   ?context=overlay → loaded by modules/sidebar-handle.ts inside the page
+    //   no query param   → loaded by chrome.sidePanel (the fallback during audits)
+    // Only the chrome.sidePanel instance opens the tracker port — its disconnect
+    // is the SW's signal that the fallback UI just closed, time to restore the
+    // in-page overlay.
+    const isOverlayContext =
+      new URLSearchParams(window.location.search).get('context') === 'overlay';
+    const trackerPort = isOverlayContext
+      ? null
+      : chrome.runtime.connect({ name: 'sidepanel-tracker' });
+    const off = wireMessaging();
+    // Defensive .catch — these are bootstrapping side effects; failures should not
+    // surface as uncaught promise rejections in the console.
+    // First load: bypass the 24h license cache so the UpgradeCard reads
+    // any newly-added server fields (seats counts, cancel-at-period-end,
+    // single-month plan code, etc.). Subsequent LICENSE_CHANGED_EVENT
+    // refreshes use the cache normally — the SW already invalidates it
+    // on every LICENSE_SET_REQUEST.
+    refreshLicenseTier({ forceRefresh: true }).catch(() => {});
+    refreshBaselineList().catch(() => {});
+    refreshUserMode().catch(() => {});
+    // Pre-cache windowId so audit-start click handlers can open
+    // chrome.sidePanel synchronously (preserves user-gesture context).
+    primeAuditLauncher().catch(() => {});
+    // Load any persisted audit. Results stay until the user clicks Clear —
+    // switching tabs or navigating the audited page no longer wipes them.
+    // The Header shows the audited domain so the user always knows which
+    // page the displayed results belong to.
+    loadLastAudit().catch(() => {});
+    // Esc inside the side panel clears the highlight pin. The page's own keydown
+    // handler (in element-highlighter) only fires when the page has focus.
+    const onEsc = (e: KeyboardEvent) => {
+      if (e.key !== 'Escape') return;
+      const { pinnedMatchKey, setPinned, results } = useStore.getState();
+      if (!pinnedMatchKey) return;
+      setPinned(null);
+      void getAuditTargetTabId().then((tabId) => {
+        if (!tabId) return;
+        sendToTab(
+          tabId,
+          { type: 'HIGHLIGHT_CLEAR_REQUEST', tabId },
+          results[0]?.frameId
+        ).catch(() => {});
+      });
+    };
+    window.addEventListener('keydown', onEsc);
+    return () => {
+      off();
+      port.disconnect();
+      trackerPort?.disconnect();
+      window.removeEventListener('keydown', onEsc);
+    };
+  }, []);
+  // First launch — show the persona picker. Once chosen it persists in
+  // chrome.storage.local; subsequent loads bypass the wizard.
+  if (userMode === null) {
+    return (
+      <>
+        <UserModeWizard />
+        <Announcer />
+      </>
+    );
+  }
+  // Owner mode — simplified surface. No view tabs, no visualizers, no IGT.
+  // OwnerView holds its own header + footer for the simplified flow.
+  if (userMode === 'owner') {
+    return (
+      <>
+        <OwnerView />
+        <DebuggerBusyModal />
+        <Announcer />
+      </>
+    );
+  }
+  // Dev mode — full feature surface (everything that existed before).
+  return (
+    <div className="flex flex-col h-screen bg-slate-50 text-slate-900 text-sm">
+      {/* Skip link — visually hidden by default; revealed on focus so keyboard
+          users can jump past the header/UpgradeCard chrome straight to the
+          audit results. Required for WCAG 2.4.1 (Bypass Blocks) when there
+          are many tab stops before the main content. */}
+      <a
+        href="#main-content"
+        className="sr-only focus:not-sr-only focus:fixed focus:top-2 focus:left-2 focus:z-50 focus:bg-white focus:text-slate-900 focus:px-3 focus:py-1.5 focus:rounded focus:shadow focus:outline focus:outline-2 focus:outline-brand-500"
+      >
+        Skip to main content
+      </a>
+      <UpgradeCard />
+      <CriticalBanner />
+      <Header />
+      <main
+        id="main-content"
+        className="flex-1 flex flex-col overflow-hidden"
+        aria-label="wcagcheckr"
+      >
+        <AuditControls />
+        <VisualizerTools />
+        <StorybookHint />
+        <ResumeAuditBanner />
+        <ProgressBar />
+        <ErrorBanner />
+        <AiFailureBanner />
+        <div className="flex-1 overflow-y-auto" role="region" aria-label={`${view} view`}>
+          {view === 'matrix' && <MatrixView />}
+          {view === 'delta' && <DeltaView />}
+          {view === 'activity' && <ActivityView />}
+          {view === 'guided' && <GuidedView />}
+          {view === 'flows' && <FlowsView />}
+          {view === 'scorecard' && <ScorecardView />}
+          {view === 'crawl' && <SiteCrawlPanel />}
+          {view === 'forensic' && <ForensicLogView />}
+          {view === 'compliance' && <WcagEmView />}
+        </div>
+      </main>
+      <ComplianceDisclaimer />
+      <AuditFooter />
+      <OnboardingModal />
+      <DebuggerBusyModal />
+      <Announcer />
+    </div>
+  );
+}

package/dist/side-panel/README.md ADDED Viewed

@@ -0,0 +1,57 @@
+# side-panel/
+The user-facing UI surface. Spec: `phase-1-specs.md` §9 (Zustand) + §11 (panel structure).
+## Component map
+```
+App.tsx
+├── Header                    (title + version + tier badge + Upgrade/License/Settings/Support buttons + view tabs)
+├── AuditControls             (mode select, Pick/Audit-all button, Stop button, upgrade-modal trigger)
+├── StorybookHint             (banner: shown if active tab is a Storybook page on first open)
+├── ResumeAuditBanner         (banner: shown if a previous audit was interrupted)
+├── ProgressBar               (shown only while status === 'running')
+├── ErrorBanner               (shown only while status === 'failed')
+├── <view>                    (matrix | delta | scorecard, picked by store.view)
+├── AuditFooter               (always-visible: tracked count + last-audit relative time)
+├── OnboardingModal           (first-run, explains chrome.debugger banner)
+└── DebuggerBusyModal         (DEBUGGER_BUSY events open this)
+```
+## State
+`store.ts` defines a single Zustand store. Slices: `auditState`, `progress`, `results`, `delta`, `componentId`, `errorMessage`, `baselineList`, `tier`, `view`. Setters are flat methods on the store.
+`wire-messaging.ts` subscribes the store to messaging events:
+- `AUDIT_PROGRESS_EVENT` → `setProgress` + `setStatus('running')`
+- `AUDIT_COMPLETE_EVENT` → `setResults` + persist to `chrome.storage.local` for next-open hydrate
+- `AUDIT_FAILED_EVENT` → `setError`
+- `LICENSE_CHANGED_EVENT` → re-fetch tier
+- `SCORECARD_UPDATED_EVENT` → re-fetch baseline list
+`loadLastAudit()` runs on App mount to restore previous results.
+## ErrorBoundary
+Wraps the App root in `main.tsx`. Catches React render errors so a single broken view doesn't blank the whole panel. Shows a Reload button that calls `location.reload()`.
+## Keepalive
+`startKeepalive()` opens a `chrome.runtime.connect({ name: 'audit-keepalive' })` port on App mount. While this port is open, Chrome won't suspend the service worker — keeps in-flight audits alive.
+## Reusable bits
+- `IconButton` — consistent text-button styling for icon-only triggers (settings ⚙, support ?). Required `ariaLabel`.
+- `Modal` — Radix Dialog wrapper with consistent overlay + sizing.
+- `ViolationCard` — used by both Matrix and Delta views.
+- `UpgradePrompt` — used by Header upgrade modal + AuditControls upgrade modal.
+- `format-component-id.ts` — pretty-display of canonical IDs (e.g., `::story:atoms-button--primary` → "Atoms Button / Primary").
+## Tier gating in the UI
+Performed locally against `TIER_RULES` from `shared/tier-rules` once `tier` is in the store. No round-trip per gate check.
+- `AuditControls` blocks "All stories" mode when `!isFeatureAllowed(tier, 'storybookAutoIterate')`
+- `DeltaView` blocks "Accept as baseline" when free + already has 1 baseline; blocks Export when below paid tier
+- `ScorecardView` shows a banner when free user is at the baseline limit
+- `Header` shows the Upgrade CTA when tier is `trial` or `free`

package/dist/side-panel/audit-launcher.test.ts ADDED Viewed

@@ -0,0 +1,56 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { openFallbackPanel, primeAuditLauncher } from './audit-launcher';
+// chrome.sidePanel.open requires a live user-gesture and silently no-ops
+// without one. The contract this test guards: openFallbackPanel runs
+// SYNCHRONOUSLY relative to its caller — it does not await — so when
+// invoked from a click handler the user-gesture is still alive at call
+// time. Any future refactor that awaits inside this function silently
+// breaks the bug fix it backs (Load state on narrow-breakpoint violations
+// must open chrome.sidePanel as fallback before the viewport shrinks the
+// overlay out of existence).
+describe('openFallbackPanel', () => {
+  const openSpy = vi.fn();
+  beforeEach(() => {
+    openSpy.mockReset();
+    (globalThis as unknown as { chrome: unknown }).chrome = {
+      sidePanel: { open: openSpy.mockResolvedValue(undefined) },
+      windows: { getCurrent: vi.fn().mockResolvedValue({ id: 42 }) },
+    };
+  });
+  it('does nothing when not primed (no cached windowId)', () => {
+    // primeAuditLauncher hasn't run yet → no cached windowId → fallback
+    // open should silently no-op rather than throw.
+    openFallbackPanel();
+    expect(openSpy).not.toHaveBeenCalled();
+  });
+  it('opens chrome.sidePanel with the cached windowId after priming', async () => {
+    await primeAuditLauncher();
+    openFallbackPanel();
+    expect(openSpy).toHaveBeenCalledOnce();
+    expect(openSpy).toHaveBeenCalledWith({ windowId: 42 });
+  });
+  it('does not throw when chrome.sidePanel is missing (ui-preview / test contexts)', async () => {
+    (globalThis as unknown as { chrome: unknown }).chrome = {
+      windows: { getCurrent: vi.fn().mockResolvedValue({ id: 7 }) },
+    };
+    await primeAuditLauncher();
+    expect(() => openFallbackPanel()).not.toThrow();
+  });
+  it('the call is synchronous — returns before chrome.sidePanel.open resolves', async () => {
+    // Promise that never resolves, simulating Chrome holding the open()
+    // promise pending. If openFallbackPanel awaited it, the caller would
+    // hang forever — the test would time out.
+    const neverResolves = new Promise<void>(() => {});
+    openSpy.mockReturnValue(neverResolves);
+    await primeAuditLauncher();
+    // No await — must return immediately even though open() never settles.
+    openFallbackPanel();
+    expect(openSpy).toHaveBeenCalled();
+  });
+});

package/dist/side-panel/audit-launcher.ts ADDED Viewed

@@ -0,0 +1,65 @@
+// Audit launcher — wraps every START_AUDIT / START_SITE_CRAWL dispatch with
+// an opening of chrome.sidePanel as the fallback UI.
+//
+// Why this exists: chrome.debugger viewport emulation during an audit affects
+// everything in the audited tab — including our in-page sidebar overlay
+// (which then gets squished into the emulated viewport and visually trapped).
+// The in-page overlay therefore HIDES during audits (service-worker broadcasts
+// SIDEBAR_HIDE_REQUEST). chrome.sidePanel is the only UI surface that renders
+// OUTSIDE the tab's render tree, so we open it as the fallback so users still
+// see progress + stop controls.
+//
+// Why this can't live in the SW: chrome.sidePanel.open() requires a user-
+// gesture context. User gestures DO propagate through chrome.runtime.send-
+// Message into the SW, but Chrome consumes the gesture as soon as the SW
+// awaits anything (chrome.tabs.query, etc.). Calling chrome.sidePanel.open
+// synchronously from the original click handler — before any await — is the
+// only reliable path. To do that we need the windowId synchronously, so we
+// pre-cache it on side-panel mount.
+import { send } from '../shared/messaging';
+import type { StartAuditAction, StartSiteCrawl } from '../shared/messages';
+let cachedWindowId: number | null = null;
+/** Pre-fetch the side-panel's window id so audit launches can open
+ *  chrome.sidePanel synchronously without burning user-gesture context on
+ *  an await. Call once on side-panel mount. Idempotent. */
+export async function primeAuditLauncher(): Promise<void> {
+  if (cachedWindowId !== null) return;
+  try {
+    const w = await chrome.windows.getCurrent();
+    if (typeof w.id === 'number') cachedWindowId = w.id;
+  } catch {
+    // chrome.windows is unavailable in some contexts (ui-preview shim) —
+    // launcher gracefully degrades; user just loses the fallback panel.
+  }
+}
+/** Open chrome.sidePanel synchronously while the click-handler user-gesture
+ *  is still live. Returns immediately; the open() promise resolves later but
+ *  the gesture is consumed at call time, which is what matters.
+ *
+ *  Exported so call sites OTHER than audit-launch (e.g. ViolationCard's
+ *  Load state link, which drives the page through a narrow-breakpoint
+ *  state) can pre-open the fallback before issuing their async work. */
+export function openFallbackPanel(): void {
+  if (cachedWindowId === null) return;
+  // Guard chrome.sidePanel access — the API isn't present in non-extension
+  // contexts (tests, ui-preview).
+  const api = chrome.sidePanel;
+  if (!api || typeof api.open !== 'function') return;
+  api.open({ windowId: cachedWindowId }).catch(() => {
+    // best-effort — failures here just mean the user won't see the fallback
+    // panel, which is acceptable. The audit still runs.
+  });
+}
+/** Drop-in replacement for `send(startAuditMessage)` at audit-start sites.
+ *  Opens chrome.sidePanel first (preserving user-gesture), then dispatches
+ *  the audit start to the service worker. Use for both START_AUDIT and
+ *  START_SITE_CRAWL — both run the state-matrix audit pipeline. */
+export function launchAudit(msg: StartAuditAction | StartSiteCrawl): void {
+  openFallbackPanel();
+  void send(msg);
+}

package/dist/side-panel/format-component-id.test.ts ADDED Viewed

@@ -0,0 +1,89 @@
+import { describe, it, expect } from 'vitest';
+import { displayComponentId } from './format-component-id';
+describe('displayComponentId', () => {
+  it('formats Storybook story id', () => {
+    const r = displayComponentId('::story:atoms-button--primary');
+    expect(r.primary).toBe('Atoms Button / Primary');
+    expect(r.secondary).toBe('storybook');
+  });
+  it('formats testid with URL scope', () => {
+    const r = displayComponentId('https://example.com/login::testid:email-input');
+    expect(r.primary).toBe('email-input');
+    expect(r.secondary).toBe('https://example.com/login');
+  });
+  it('formats explicit data-componentid', () => {
+    const r = displayComponentId('https://example.com::explicit:my-card');
+    expect(r.primary).toBe('my-card');
+    expect(r.secondary).toBe('https://example.com');
+  });
+  it('formats custom element', () => {
+    const r = displayComponentId('https://example.com::customelement:my-button');
+    expect(r.primary).toBe('my-button');
+    expect(r.secondary).toBe('https://example.com');
+  });
+  it('formats aria id with role:name', () => {
+    const r = displayComponentId('https://example.com::aria:button:Submit form');
+    // value contains a colon; we keep everything after the first colon as the value
+    expect(r.primary).toBe('button:Submit form');
+    expect(r.secondary).toBe('https://example.com');
+  });
+  it('falls back gracefully when no separator', () => {
+    const r = displayComponentId('weird-id');
+    expect(r.primary).toBe('weird-id');
+  });
+  it('handles aria value with multiple colons (kept verbatim after first colon)', () => {
+    const r = displayComponentId('https://example.com::aria:button:Foo: bar: baz');
+    // Strategy is "aria"; value is "button:Foo: bar: baz" (preserves colons after the first).
+    expect(r.primary).toBe('button:Foo: bar: baz');
+    expect(r.secondary).toBe('https://example.com');
+  });
+  it('handles unicode story names', () => {
+    const r = displayComponentId('::story:atoms-bütton--primary');
+    expect(r.primary).toBe('Atoms Bütton / Primary');
+  });
+  it('handles emoji in story names', () => {
+    const r = displayComponentId('::story:atoms-button--🚀-primary');
+    expect(r.primary).toContain('🚀');
+  });
+  it('handles very long story id without crashing', () => {
+    const longSegment = 'a'.repeat(200);
+    const r = displayComponentId(`::story:${longSegment}--variant`);
+    expect(r.primary.length).toBeGreaterThan(0);
+    expect(r.primary).toContain('Variant');
+  });
+  it('handles single-segment story id without "--" separator', () => {
+    const r = displayComponentId('::story:single-segment-only');
+    // No "--" separator → entire value is one segment, gets capitalized.
+    expect(r.primary).toBe('Single Segment Only');
+  });
+  it('handles testid with special characters', () => {
+    const r = displayComponentId('https://example.com::testid:btn-#$@-special');
+    expect(r.primary).toBe('btn-#$@-special');
+    expect(r.secondary).toBe('https://example.com');
+  });
+  it('handles empty url scope (storybook-style separator with no URL)', () => {
+    const r = displayComponentId('::testid:button-x');
+    expect(r.primary).toBe('button-x');
+    // Empty URL scope falls back to strategy as the secondary label.
+    expect(r.secondary).toBe('testid');
+  });
+  it('handles trailing :: with empty rest', () => {
+    const r = displayComponentId('https://example.com::');
+    // No strategy:value content after the separator; should not crash.
+    expect(r.primary).toBe('');
+  });
+});

package/dist/side-panel/format-component-id.ts ADDED Viewed

@@ -0,0 +1,40 @@
+// Pretty-print a canonical componentId for display in the UI.
+// Spec: phase-1-specs.md §2 (componentId format).
+export type ComponentIdDisplay = {
+  primary: string;          // Headline label
+  secondary?: string;       // Smaller subtext (URL or strategy)
+};
+export function displayComponentId(id: string): ComponentIdDisplay {
+  // Format: {urlScope}::{strategy}:{value}    (urlScope may be empty for storybook)
+  const sepIdx = id.indexOf('::');
+  if (sepIdx === -1) {
+    return { primary: id };
+  }
+  const url = id.slice(0, sepIdx);
+  const rest = id.slice(sepIdx + 2);
+  // rest is "{strategy}:{value}". Strategy is the first segment up to the FIRST colon.
+  const colonIdx = rest.indexOf(':');
+  if (colonIdx === -1) {
+    return { primary: rest };
+  }
+  const strategy = rest.slice(0, colonIdx);
+  const value = rest.slice(colonIdx + 1);
+  if (strategy === 'story') {
+    // storyId like "atoms-button--primary" → "Atoms / Button / Primary"
+    const niceStory = value
+      .split('--')
+      .map((seg) => seg.split('-').map(cap).join(' '))
+      .join(' / ');
+    return { primary: niceStory, secondary: 'storybook' };
+  }
+  return { primary: value, secondary: url || strategy };
+}
+function cap(word: string): string {
+  return word.length === 0 ? word : word[0]!.toUpperCase() + word.slice(1);
+}