Add Classroom browser E2E and accessibility coverage

.github/workflows/browser-e2e.yml

@@ -0,0 +1,48 @@
+name: Browser E2E (manual)
+
+on:
+  workflow_dispatch:
+
+concurrency:
+  group: browser-e2e-manual-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  browser:
+    timeout-minutes: 20
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Chromium
+        run: npx playwright install --with-deps chromium
+
+      - name: Run browser tests
+        run: npm run test:browser
+
+      - name: Upload browser failure artifacts
+        if: failure()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: browser-e2e-artifacts
+          path: |
+            playwright-report/
+            test-results/
+          if-no-files-found: ignore
+          retention-days: 7

.github/workflows/ci.yml

@@ -18,7 +18,7 @@ permissions:
 
 jobs:
   tests:
-    timeout-minutes: 15
+    timeout-minutes: 25
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
@@ -42,12 +42,19 @@ jobs:
         timeout-minutes: 10
         run: npm run quality
 
+      - name: Install Chromium for required browser gate
+        run: npx playwright install --with-deps chromium
+
+      - name: Run required browser regression suite
+        run: npm run test:browser
+
       - name: Upload test artifacts
         if: failure()
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: node-test-results
           path: |
             test-results/
+            playwright-report/
             npm-debug.log*
           if-no-files-found: ignore

.gitignore

@@ -2,3 +2,5 @@ node_modules/
 dist/
 data/
 .DS_Store
+playwright-report/
+test-results/

README.md

@@ -219,6 +219,7 @@ Need to know which module owns a given storage field? Jump to the [Storage-to-Mo
 [![CodeQL security scan status](../../actions/workflows/codeql.yml/badge.svg)](../../actions/workflows/codeql.yml)
 
 - **Automated coverage is mandatory:** Every feature pull request must add or update tests that assert the behaviours introduced or modified.
+- **Required real-browser regression:** The branch-protected `tests` CI status runs `npm run quality` and then the Playwright/axe suite via `npm run test:browser`. Browser failures therefore block the existing required check. The deterministic browser server does not depend on Vercel previews or production credentials; the separate Browser E2E workflow is manual-only for focused reruns.
 - **Security scanning is automatic:** GitHub CodeQL runs on every push to `main`, pull request, and a weekly schedule to flag JavaScript/TypeScript issues without manual setup.
 - **Dependency review gate:** A GitHub dependency review workflow now blocks merges when a pull request introduces new high or critical advisories, so expect PRs to fail even if unit tests succeed until vulnerable dependencies are replaced or patched.
 - **Run the coverage guard:** Execute `npm run verify:tests` after staging runtime changes. The guard ensures any updates under `src/` or `components/` are paired with refreshed suites in `tests/**/*.test.mjs`.
@@ -234,7 +235,7 @@ Need to know which module owns a given storage field? Jump to the [Storage-to-Mo
 - **Manual regression:** Open `index.html`, fill representative data, click **Generate Summary**, then refresh to ensure state persistence.
 - **Storage changes:** Run `npm run update:storage-docs` after altering persisted fields. CI can enforce freshness with `npm run check:storage-docs`.
 
-Continuous integration runs automatically on pull requests and pushes to `main`, using the repository's Node.js version via `actions/setup-node` with npm caching for faster installs. The workflow executes `npm ci`, `npm test` (emitting JUnit results for artifact upload on failure), and `npm run check:storage-docs` so Codex-driven contributions keep tests and storage docs in sync.
+Continuous integration runs automatically on pull requests and pushes to `main`, using the repository's Node.js version via `actions/setup-node` with npm caching. The required `tests` job executes `npm ci`, the canonical `npm run quality` gate, installs Chromium, and then runs `npm run test:browser`. Node/browser failure artifacts are retained only on failure; the focused Browser E2E workflow remains available through manual dispatch.
 
 ## Additional Documentation
 - See `AGENTS.md` for global UI principles, module isolation rules, and contribution contracts.

docs/AI-ONBOARDING.md

@@ -136,6 +136,10 @@ function boot() {
 ```
 
 ## Testing & QA Notes
+- The real-browser layer is required in CI. The protected `tests` status runs the canonical `npm run quality` gate and then `npm run test:browser`; do not treat Playwright as optional advisory evidence for merge.
+- Browser specs live under `tests/e2e/`, use `playwright.config.mjs`, and target the deterministic HTTP/API fixture in `scripts/serve-browser-tests.mjs`. Normal PR validation must not depend on Vercel preview availability.
+- Keep stateful Classroom browser fixtures unique by spec/project/retry so fully-parallel tests cannot share mutable workspace/coaching state accidentally.
+- `.github/workflows/browser-e2e.yml` is manual-only for focused diagnostics; failure traces/screenshots are retained only when a browser run fails.
 - Always run a manual smoke test by opening `index.html` in a modern browser, entering sample data, generating a summary, and refreshing to confirm persistence.
 - Automated suites should rely on `collectAppState()` / `applyAppState()` for deterministic state setup and on `generateSummary()` for output verification.
 - Core local intake workflows can still run browser-first, but collaboration uses Vercel Functions under `api/` and Neon persistence. Use a deployed/HTTP environment with the required database variable when testing shared sessions; do not infer collaboration health from a `file://` smoke test.

docs/classroom-roadmap.md

@@ -164,7 +164,7 @@ Primary deliverables:
 
 **Issue:** #295
 
-**Implementation:** draft PR #307 on `feature/classroom-protected-cases`; implementation, repository validation, and documentation are complete. Final deployed `dist/` verification remains blocked only by Vercel build capacity / preview-auth tooling.
+**Implementation:** PR #307 merged to `main` as `09f034f1f1776a3aaf92be7dec86b902549c8eb9`; protected delivery, minimal `dist/` public output, deployment controls, and production verification are complete.
 
 Requires #290 semantics and #291 authorization; both prerequisites are merged.
 
@@ -190,18 +190,38 @@ Validation evidence:
 - canonical CI built 45 public `dist/` files with no internal docs or protected Case Study identifiers;
 - prior deliberate READY preview returned HTTP 404 for the formerly public Microcomputer Cabinets authored JSON path.
 
-Remaining before merge:
+## Slice 8 — Browser/E2E and required CI
 
-- obtain one deliberate `verify/**` preview of the latest `dist/` head when Vercel build capacity permits;
-- confirm app root loads and internal `/docs/*`, `/scripts/*`, and protected `/templates/*.json` paths return 404;
-- execute the deployed protected-API matrix only if an approved Preview Authentication bypass path is available; do not weaken preview protection to manufacture this evidence;
-- explicit merge authorization.
+**Issue:** #296, using #279  
+**Implementation:** draft PR #308 on `feature/classroom-browser-e2e`
 
-## Slice 8 — Browser/E2E and required CI
+Implemented browser foundation / critical paths:
+
+- Playwright 1.63 + axe 4.13 with desktop Chromium and Pixel 7 projects;
+- deterministic local HTTP/API fixture; no Vercel preview dependency;
+- first-run role chooser, Standalone summary/persistence/resources, mobile smoke;
+- real Save-to-File / Load-from-File round trip and Intake-mode restoration;
+- Student join/resume and shared collaboration persistence;
+- same-team multi-browser synchronization plus cross-workspace isolation;
+- Instructor roster / workspace switching / read-only observation / resume;
+- Instructor coaching → Student feedback → changed-since-review;
+- protected Case Study unauthorized/authorized catalog/payload journey;
+- invalid authority, expired Student resume, and Student non-enumeration;
+- serious/critical axe scans and uncaught-page-error assertions on covered journeys;
+- deterministic fixture isolation by test/project/retry.
+
+CI decision: the browser suite is now part of the already-required `tests` status. The required job runs `npm run quality` and then `npm run test:browser`. The separate Browser E2E workflow is manual-only for focused diagnostics.
+
+Latest functional suite checkpoint before final docs: **22 passed, 6 intentionally project-scoped skips, 0 failed**.
+
+## Post-foundation Classroom direction
+
+The eight-slice #288 program establishes the secure Classroom foundation; it does not represent the final facilitated teaching product.
 
-**Issue:** #296, using #279
+- **#312 — Instructor-run live class, roster, and dynamic team management:** Instructor-created classes, one human-friendly Student join path, waiting/late roster, accessible team formation, live reassignment, automatic Student workspace switching, and high-signal team monitoring.
+- **#313 — Instructor-orchestrated case simulation and staged debrief:** staged protected Case Study release, case reference beside Intake, Instructor pause/debrief/advance controls, progressive disclosure, team progress, and server-gated future-stage / Instructor-only material.
 
-Do not wait until the end to write all browser tests. Add tests with the slice that owns behavior, then finish the program by promoting stable critical journeys to required CI as appropriate.
+#312 is the next product slice after #308 closes; #313 should build on #312 rather than bypassing the live-class/team-management substrate.
 
 ## Stacked PR rules