feat: configure CI for validation, axe, browser smoke and supported matrix (closes #40)

.github/workflows/ci.yml

@@ -8,6 +8,7 @@ permissions:
 jobs:
   unit:
     runs-on: ubuntu-24.04
+    timeout-minutes: 15
     strategy:
       matrix:
         node: [22, 24]
@@ -24,6 +25,7 @@ jobs:
       - run: npm audit --omit=dev
   consumers:
     runs-on: ubuntu-24.04
+    timeout-minutes: 30
     steps:
       - uses: actions/checkout@v7.0.1
       - uses: actions/setup-node@v7.1.0
@@ -37,5 +39,8 @@ jobs:
       - uses: actions/upload-artifact@v7.0.2
         if: failure()
         with:
-          name: browser-failures
-          path: test-results
+          name: browser-failures-${{ github.sha }}
+          path: |
+            test-results
+            playwright-report
+          if-no-files-found: ignore

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 2.3.2 — 2026-10-23
+
+- Harden GitHub Actions CI workflow (`ci.yml`) with job timeouts and comprehensive artifact capture for test results and Playwright HTML reports on failure (closes #40).
+- Add fast developer browser smoke command (`npm run test:browser:smoke`) targeting the Chromium consumer.
+- Document local consumer server ports (`7311`, `7312`, `7313`), browser execution commands, environment failure modes, and automated Axe audit boundaries in `docs/DEVELOPMENT.md`.
+- Conclude Milestone 1 (`[M1] Safe core, accessible widget UI and stable state`).
+
 ## 2.3.1 — 2026-10-23
 
 - Provide runnable Next.js App Router consumer example in `examples/next-app/` with Server Component layout, client boundaries, and route transitions (closes #39).

docs/BUILD_AND_RELEASE_PLAN.md

@@ -78,7 +78,7 @@ completed. Closing a child issue does not replace the milestone exit review.
 - [x] [A11Y-106 — Position, oversized controls, statement link and help #37](https://github.com/prabothcharith/accessibility-react/issues/37) — Implement position and non-drag movement, oversized controls, safe-area actions, conditional statement link and help while reconciling existing positioning work.
 - [x] [A11Y-107 — Base locale infrastructure and English strings #38](https://github.com/prabothcharith/accessibility-react/issues/38) — Add typed English locale strings, configured/html-language fallback, BCP 47 and RTL handling, announcements and safe missing-key behavior.
 - [x] [A11Y-108 — Vite and Next.js App Router consumer integrations #39](https://github.com/prabothcharith/accessibility-react/issues/39) — Provide Vite and Next.js App Router consumers and verify hydration, portals, React peer versions, CSS, declarations, themes and CSP guidance.
-- [ ] [A11Y-109 — CI for typecheck, lint, unit, axe and browser smoke #40](https://github.com/prabothcharith/accessibility-react/issues/40) — Establish CI for typecheck, lint, unit/integration, relevant axe checks, packed browser smoke and supported browser jobs without publication credentials.
+- [x] [A11Y-109 — CI for typecheck, lint, unit, axe and browser smoke #40](https://github.com/prabothcharith/accessibility-react/issues/40) — Establish CI for typecheck, lint, unit/integration, relevant axe checks, packed browser smoke and supported browser jobs without publication credentials.
 
 ### M2 — Stable visual and typographic features
 

docs/DEVELOPMENT.md

@@ -18,9 +18,25 @@ npm run test:browser
 
 For a PR under review, check out its head branch instead and record the tested commit. Main contains the merged stabilization and Clean light foundation; PR #17 adds movement and fixed actions.
 
-`validate` runs typecheck, lint, unit tests and JS/declaration/CSS build. `test:consumers` builds, packs and installs the archive in `.consumers/react18`, `.consumers/react19` and `.consumers/next`, checks ESM/CJS and declarations/SSR, and produces application production builds. Consumers use explicitly selected framework versions; generated install locks reside in disposable `.consumers`. Network access is required for installation, not widget runtime. Browser tests start local ports 7311/7312/7313 and close their servers afterward. Avoid using these ports for unrelated processes. `CI` disables server reuse and is a test-runner environment flag, not a library setting.
+`validate` runs typecheck, lint, unit tests and JS/declaration/CSS build. `test:consumers` builds, packs and installs the archive in `.consumers/react18`, `.consumers/react19` and `.consumers/next`, checks ESM/CJS and declarations/SSR, and produces application production builds. Consumers use explicitly selected framework versions; generated install locks reside in disposable `.consumers`. Network access is required for installation, not widget runtime.
 
-`npm run example` serves the two built-package examples through Vite after `npm run build`. `npm run dev` watches the library JS bundle; run build:css after editing CSS. `npm run test:watch` is useful locally. `npm pack` produces the actual package archive. Never validate only source imports and call it release-ready.
+### Local Ports and Consumer Servers
+
+Browser integration tests use local test servers started by Playwright:
+
+- **Port `7311`**: React 18.3.1 consumer application (Vite).
+- **Port `7312`**: React 19.2.0 consumer application with Tailwind CSS 3 (Vite).
+- **Port `7313`**: Next.js 16.2.10 production server (`next start`) testing App Router, Pages Router, and Server Component boundaries.
+
+Avoid using these ports for unrelated background processes. If an `EADDRINUSE` error occurs due to an interrupted run, terminate existing node processes holding these ports.
+
+### Browser Test Commands
+
+- `npm run test:browser`: Executes the full 6-project browser test matrix (React 18 Chromium, React 19 Tailwind Chromium, Next.js App Router Chromium, Firefox, WebKit, and Mobile WebKit emulation).
+- `npm run test:browser:smoke`: Rapid Chromium-only smoke test on the React 18 consumer for fast developer iteration.
+- `CI=1 npm run test:browser`: Disables server reuse in Playwright and forces fresh server lifecycle per run.
+
+`npm run example` serves the built-package examples through Vite after `npm run build`. `npm run dev` watches the library JS bundle; run build:css after editing CSS. `npm run test:watch` is useful locally. `npm pack` produces the actual package archive. Never validate only source imports and call it release-ready.
 
 ## Directory map
 
@@ -77,7 +93,18 @@ These checks require a human/tester; mark results and platform/version in PROJEC
 6. Host integration: sticky/fixed overlays, complex forms, embedded media, route navigation, dynamically inserted content and font loading. Confirm each selected setting improves intended content without concealing important controls. Video hiding does not stop playback.
 7. Inspect reset/unmount restoration, rapid reload storage, blocked storage and corrupted saved data. Test a custom feature's restored and removed-control effects.
 
-Automated axe results cover the tested widget DOM and criteria tags; they neither certify the host nor cover all assistive-technology behavior.
+### Automated Axe Audits and Human Acceptance
+
+Automated `@axe-core/playwright` checks are executed as part of `tests/browser/widget.spec.ts` against the widget DOM (`[data-arap-ui]`) using WCAG 2.0 A/AA, 2.1 AA, and 2.2 AA rule sets in both light and dark host themes.
+
+- **Scope:** Automated axe results verify that rendered markup, color contrast within the widget panel, native form controls, and ARIA attributes do not produce detectable programmatic violations.
+- **Non-Certification:** Automated test suites do not establish official WCAG conformance or substitute for human accessibility acceptance. Real screen-reader navigation (VoiceOver, NVDA), physical touch devices, browser zoom (200%/400%), and keyboard reviews are mandatory components of accessibility validation.
+
+### Platform and Environment Failure Modes
+
+- **macOS Local Firefox Launch:** Firefox on macOS may fail during Playwright launch with `Could not find profile folder`. The complete Firefox test suite passes in Ubuntu Linux CI.
+- **Port Conflicts:** Ensure ports `7311`, `7312`, and `7313` are free before running `npm run test:browser`. If interrupted, kill existing node processes.
+- **Missing Browser Binaries:** If browser engines are missing, execute `npx playwright install --with-deps chromium firefox webkit`.
 
 ## Release procedure (manual, owner-authorized)
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "accessibility-plugin-react",
-  "version": "2.3.1",
+  "version": "2.3.2",
   "description": "A composable React display-preference widget with a clean light design, persistent settings and movable accessible controls.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -36,6 +36,7 @@
     "validate": "npm run typecheck && npm run lint && npm test && npm run build",
     "pack:check": "node scripts/check-package.mjs",
     "test:browser": "playwright test",
+    "test:browser:smoke": "playwright test --project=react18-chromium",
     "test:consumers": "npm run build && npm run pack:check && node scripts/prepare-consumers.mjs",
     "example": "vite examples",
     "example:next": "npm --prefix examples/next-app run dev",