Pushing to live

openspec/changes/p17-regression-defects/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-13

openspec/changes/p17-regression-defects/design.md

@@ -0,0 +1,70 @@
+## Context
+
+The project already has API, DB, and contract-style tests, but recent regressions (theme contrast/state accessibility and contact tooltip behavior) exposed a gap in browser-native UI/UX regression detection. Current checks do not consistently validate interaction states across themes, breakpoints, and keyboard/pointer paths using a real rendering engine.
+
+This change introduces a Playwright-centered UI/UX testing design that covers existing product capabilities end-to-end, while staying compatible with current quality-gate flow and OpenSpec requirements.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Establish a deterministic Playwright test architecture for UI/UX regression prevention.
+- Build a capability-to-test coverage matrix mapped to existing OpenSpec specs.
+- Validate all critical interaction states: default, hover, focus-visible, active/pressed, and visited where applicable.
+- Validate key journeys across light, dark, and contrast themes and across mobile/tablet/desktop breakpoints.
+- Integrate Playwright execution into CI quality gates with actionable artifacts (trace, video/screenshot on failure).
+
+**Non-Goals:**
+- Replacing existing API/DB tests.
+- Pixel-perfect visual diff for every component in this phase.
+- Introducing new product behavior unrelated to testing.
+
+## Decisions
+
+### Decision 1: Use capability-driven Playwright test organization
+- **Choice:** Organize tests by capability groups aligned to OpenSpec specs (e.g., `summary-modal-experience`, `share-and-contact-microinteractions`).
+- **Why:** Makes regression ownership and traceability explicit and keeps specs/test synchronization straightforward.
+- **Alternative considered:** Organize by page-only files. Rejected because cross-capability assertions become fragmented and harder to audit.
+
+### Decision 2: Add a reusable test harness with deterministic fixtures
+- **Choice:** Build shared Playwright fixtures for theme selection, viewport profiles, seeded content, and stable selectors.
+- **Why:** Prevents flaky setup differences and reduces duplicated orchestration logic.
+- **Alternative considered:** Per-test custom setup. Rejected due to drift and higher maintenance.
+
+### Decision 3: Use interaction-state assertions, not just presence assertions
+- **Choice:** Assert computed styles and behavior transitions for focus/hover/active/link states on key controls.
+- **Why:** The reported regressions were state-specific and escaped static presence checks.
+- **Alternative considered:** DOM existence-only assertions. Rejected as insufficient for UX quality.
+
+### Decision 4: Add tiered execution profile for CI speed and depth
+- **Choice:** Define smoke profile (PR) and full profile (main/nightly) while both remain gating where required by policy.
+- **Why:** Balances quick feedback with comprehensive coverage.
+- **Alternative considered:** Always run full matrix on every PR. Rejected due to avoidable CI latency.
+
+### Decision 5: Capture failure diagnostics by default
+- **Choice:** Enable trace-on-retry and screenshot/video on failure.
+- **Why:** UI failures are often environment- and timing-sensitive; diagnostics reduce mean time to fix.
+- **Alternative considered:** Logs-only. Rejected for weak debuggability.
+
+## Risks / Trade-offs
+
+- **[Risk] Flaky tests from network/data timing** -> **Mitigation:** deterministic fixtures, route stubbing/controlled seeds for unstable dependencies, explicit wait-for conditions tied to user-visible state.
+- **[Risk] CI runtime increase** -> **Mitigation:** split smoke/full profiles and parallel workers with bounded retries.
+- **[Risk] Selector fragility during UI refinements** -> **Mitigation:** standardize test-id/role-based selectors for critical controls and avoid brittle CSS-path selectors.
+- **[Risk] Theme/breakpoint matrix explosion** -> **Mitigation:** capability-priority matrix (must-cover flows across all themes; lower-risk flows sampled strategically).
+
+## Migration Plan
+
+1. Add Playwright config and shared fixtures with environment-safe defaults.
+2. Implement capability-mapped smoke scenarios first (high-risk UX/accessibility flows).
+3. Expand to complete matrix scenarios for themes and breakpoints.
+4. Wire smoke profile into PR quality gate and full profile into main/nightly gate.
+5. Publish test strategy/coverage mapping documentation and triage rules.
+
+Rollback strategy:
+- If CI instability occurs, temporarily gate on smoke profile while isolating flaky cases; do not remove previously passing coverage without replacement.
+
+## Open Questions
+
+- Which environment should provide canonical seeded data for full-profile runs (local fixture API vs shared staging snapshot)?
+- Should visual snapshots be introduced in this phase for selected high-risk components (hero, modal, footer controls), or deferred?
+- What retry policy threshold should fail fast versus quarantine for flaky-only diagnostics?

openspec/changes/p17-regression-defects/proposal.md

@@ -0,0 +1,31 @@
+## Why
+
+Recent regressions in color accessibility and tooltip behavior show that current automated checks are not broad enough to catch cross-theme, cross-state UI/UX defects before release. We need deterministic browser-level coverage that validates real user journeys and interaction states across the full product surface.
+
+## What Changes
+
+- Add a Playwright-based UI/UX regression suite that runs against the real frontend and API.
+- Define a complete test strategy covering all shipped capabilities, including themes, localization, accessibility, modal flows, permalink deep-links, footer controls, and sharing interactions.
+- Add scenario-driven test cases for all component states (default, hover, focus, active, visited, disabled where applicable) and breakpoint behavior.
+- Add visual and interaction assertions for hero/feed rendering, policy modals, summary modal actions, and tooltip behavior.
+- Integrate the Playwright suite into quality gates with clear pass/fail policy and reporting.
+
+## Capabilities
+
+### New Capabilities
+- `playwright-ui-ux-regression-suite`: Browser-automation test architecture, coverage matrix, and deterministic execution model for full UI/UX regression prevention.
+
+### Modified Capabilities
+- `end-to-end-system-testing`: Expand requirement scope to include browser-native UI/UX scenarios and state coverage.
+- `platform-quality-gates`: Add Playwright execution and failure gating into CI quality stages.
+- `wcag-2-2-aa-accessibility`: Add automated browser assertions for contrast, focus visibility, keyboard navigation, and accessible names/labels in real interactions.
+- `responsive-device-agnostic-layout`: Add breakpoint-aware UI regression scenarios for desktop/tablet/mobile including sticky header/footer and floating controls.
+- `summary-modal-experience`: Add modal interaction regression scenarios (open/close, escape, focus behavior, source CTA/share actions).
+- `share-and-contact-microinteractions`: Add deterministic test coverage for share actions and contact tooltip behavior across pointer and keyboard interactions.
+
+## Impact
+
+- Affected code: test infrastructure, frontend E2E test files, CI workflow definitions, and test documentation.
+- Affected systems: CI quality gate pipeline and release confidence checks.
+- Dependencies: Playwright runtime/browsers and supporting test fixtures.
+- Operational impact: Longer CI runtime offset by significantly improved regression detection for UI/UX defects.

openspec/changes/p17-regression-defects/specs/end-to-end-system-testing/spec.md

@@ -0,0 +1,26 @@
+## MODIFIED Requirements
+
+### Requirement: End-to-end coverage spans UI, API, and DB effects
+The system SHALL provide end-to-end tests that validate full workflows across UI, API, and persisted database outcomes, including browser-native Playwright coverage for user-visible behavior.
+
+#### Scenario: Core user flow E2E
+- **WHEN** a core browsing flow is executed in E2E tests
+- **THEN** UI behavior, API responses, and DB side effects match expected outcomes
+
+#### Scenario: Browser-native interaction E2E
+- **WHEN** a critical journey is executed via Playwright
+- **THEN** rendered UI, network/API behavior, and persisted outcomes remain consistent end-to-end
+- **AND** regressions in interaction behavior are caught before release
+
+### Requirement: Edge-case workflows are covered
+The system SHALL include edge-case E2E tests for critical failure and boundary conditions, including UI-safe handling in browser flows.
+
+#### Scenario: Failure-state E2E
+- **WHEN** an edge case is triggered (empty data, unavailable upstream, invalid permalink, etc.)
+- **THEN** system response remains stable and user-safe
+- **AND** no unhandled runtime errors occur
+
+#### Scenario: UI failure-path resilience
+- **WHEN** edge-case flows are executed through Playwright user actions
+- **THEN** fallback messages and controls remain usable
+- **AND** the session remains navigable without fatal UI breakage

openspec/changes/p17-regression-defects/specs/platform-quality-gates/spec.md

@@ -0,0 +1,27 @@
+## MODIFIED Requirements
+
+### Requirement: Release quality gates are mandatory
+The system SHALL enforce mandatory CI quality gates before release, including Playwright UI/UX regression execution.
+
+#### Scenario: Gate failure blocks release
+- **WHEN** any required gate fails
+- **THEN** release pipeline status is failed
+- **AND** deployment/archive promotion is blocked
+
+#### Scenario: Playwright gate failure blocks release
+- **WHEN** Playwright smoke or required profile checks fail
+- **THEN** CI marks the quality gate as failed
+- **AND** release progression is blocked until failures are resolved
+
+### Requirement: Required gates are explicit and versioned
+The system SHALL define an explicit set of required gates and versions for tooling, including browser-testing tooling for reproducible UI/UX checks.
+
+#### Scenario: Gate manifest exists
+- **WHEN** pipeline configuration is evaluated
+- **THEN** required gates include tests, accessibility, security, performance, and Playwright UI regression checks
+- **AND** tool versions are pinned or documented for reproducibility
+
+#### Scenario: Gate profiles are documented
+- **WHEN** CI quality-gate documentation is reviewed
+- **THEN** smoke and full regression profiles are explicitly described
+- **AND** required profile per pipeline stage is unambiguous

openspec/changes/p17-regression-defects/specs/playwright-ui-ux-regression-suite/spec.md

@@ -0,0 +1,25 @@
+## ADDED Requirements
+
+### Requirement: Playwright regression suite covers core UI/UX capabilities
+The system SHALL provide a Playwright-based regression suite that validates critical UI and UX behavior across all shipped user-facing capabilities.
+
+#### Scenario: Capability-mapped suite execution
+- **WHEN** regression tests are executed
+- **THEN** test cases are organized and traceable to capability-level requirements
+- **AND** failures identify the impacted capability and user journey
+
+### Requirement: Regression suite validates themes, states, and breakpoints
+The system SHALL validate key controls and content for light, dark, and contrast themes, across mobile, tablet, and desktop breakpoints, including interactive states.
+
+#### Scenario: Theme and breakpoint matrix coverage
+- **WHEN** the suite runs in full profile
+- **THEN** high-priority journeys execute across all supported themes and target viewport classes
+- **AND** assertions include default, hover, focus-visible, active, and visited states where applicable
+
+### Requirement: Regression failures produce actionable diagnostics
+The system SHALL emit debugging artifacts for failed browser tests.
+
+#### Scenario: Failure artifact collection
+- **WHEN** a Playwright test fails
+- **THEN** the run stores trace and screenshot evidence
+- **AND** artifacts are linked in CI output for triage

openspec/changes/p17-regression-defects/specs/responsive-device-agnostic-layout/spec.md

@@ -0,0 +1,34 @@
+## MODIFIED Requirements
+
+### Requirement: Core layout is device-agnostic and responsive
+The system SHALL render key surfaces (header, hero, feed, modal, footer, policy modals, and floating controls) responsively across mobile, tablet, and desktop viewports while preserving readability, and SHALL verify these behaviors with browser-based regression tests.
+
+#### Scenario: Mobile layout behavior
+- **WHEN** a user opens the site on a mobile viewport
+- **THEN** content remains readable without horizontal overflow
+- **AND** interactive controls including icon-only copy/back-to-top and policy modals remain reachable and usable
+
+#### Scenario: Desktop and tablet adaptation
+- **WHEN** a user opens the site on tablet or desktop viewports
+- **THEN** layout reflows according to breakpoint design rules
+- **AND** no key content or controls are clipped
+
+#### Scenario: Readability-focused typography and contrast updates
+- **WHEN** content is rendered in core reading surfaces
+- **THEN** typography and color choices improve baseline readability
+- **AND** updates remain compatible with responsive behavior across breakpoints
+
+#### Scenario: Sticky shrinking glass header
+- **WHEN** user scrolls downward
+- **THEN** header remains sticky with slight height reduction, subtle elevation, and glass blur effect
+- **AND** controls remain readable and usable at all breakpoints
+
+#### Scenario: Sticky footer does not overlap core reading zones
+- **WHEN** footer is sticky
+- **THEN** content remains readable and interactive controls are not obscured
+- **AND** mobile/tablet/desktop layouts stay overflow-safe
+
+#### Scenario: Breakpoint regression matrix verification
+- **WHEN** Playwright responsive tests run across defined viewport classes
+- **THEN** no horizontal overflow, clipping, or unreachable controls are detected
+- **AND** sticky/floating controls retain expected behavior at each breakpoint

openspec/changes/p17-regression-defects/specs/share-and-contact-microinteractions/spec.md

@@ -0,0 +1,53 @@
+## MODIFIED Requirements
+
+### Requirement: Modal/footer exposes minimal icon-based share actions
+The system SHALL provide visible, accessible icon-only share actions for article permalinks on supported providers and SHALL verify interaction correctness with browser automation.
+
+#### Scenario: Supported share providers
+- **WHEN** share controls are rendered
+- **THEN** icons for `X`, `WhatsApp`, and `LinkedIn` are displayed
+- **AND** activating an icon opens provider share flow with the article permalink
+
+#### Scenario: Light-theme icon visibility
+- **WHEN** the site is in light mode
+- **THEN** share icons remain visibly distinguishable with accessible contrast
+- **AND** icon controls remain keyboard focusable
+
+#### Scenario: Copy-link share action
+- **WHEN** a user activates the copy-to-clipboard share control
+- **THEN** the article permalink is written to clipboard
+- **AND** action succeeds without navigating away
+
+#### Scenario: Share controls preserve state accessibility
+- **WHEN** interactive-state tests run across supported themes
+- **THEN** default, hover, focus-visible, and active states remain perceivable
+- **AND** accessible labels remain present for icon-only controls
+
+### Requirement: Footer supports env-driven GitHub and contact links
+The system SHALL conditionally render GitHub and contact-email links from environment-backed configuration and keep their interactions stable across pointer and keyboard use.
+
+#### Scenario: Config present
+- **WHEN** GitHub URL and contact email are configured
+- **THEN** footer renders both links as interactive controls
+
+#### Scenario: Config absent
+- **WHEN** either value is missing
+- **THEN** corresponding footer control is hidden without breaking layout
+
+#### Scenario: Contact link visible when configured
+- **WHEN** `CONTACT_EMAIL` is present in frontend config payload
+- **THEN** footer shows the contact email affordance
+- **AND** hover microcopy behavior remains enabled
+
+### Requirement: Contact affordance provides randomized safe microcopy
+The contact link SHALL present randomized, policy-safe helper messages to encourage feedback, including keyboard-triggered visibility for accessibility.
+
+#### Scenario: Randomized helper tooltip
+- **WHEN** user hovers or nears the contact affordance
+- **THEN** a tooltip-style helper message is shown from a predefined safe message pool
+- **AND** message language avoids profanity/offensive/racist/sexist/misogynistic content
+
+#### Scenario: Keyboard-triggered helper tooltip
+- **WHEN** a keyboard user focuses the contact email affordance
+- **THEN** helper tooltip content becomes visible and readable
+- **AND** tooltip dismisses cleanly on blur without trapping focus

openspec/changes/p17-regression-defects/specs/summary-modal-experience/spec.md

@@ -0,0 +1,40 @@
+## MODIFIED Requirements
+
+### Requirement: Summary is rendered in a modal dialog using standard template
+The system SHALL render article summary content in a modal dialog using the required structure and SHALL preserve consistent behavior across entry paths validated by Playwright interaction tests.
+
+#### Scenario: Open summary modal
+- **WHEN** a user triggers summary view for an article
+- **THEN** a modal dialog opens and displays content in this order: relevant image, TL;DR bullets, summary body, source and citation, and "Powered by Perplexity"
+- **AND** modal content corresponds to the selected article
+
+#### Scenario: Close summary modal
+- **WHEN** a user closes the modal via close control or backdrop interaction
+- **THEN** the modal is dismissed cleanly
+- **AND** user returns to previous feed context without page navigation
+
+#### Scenario: Permalink-driven modal open
+- **WHEN** page is loaded with a valid article permalink state
+- **THEN** the modal opens for the linked article without requiring manual click
+
+#### Scenario: Keyboard dismissal and focus continuity
+- **WHEN** the modal is open and the user presses `Escape`
+- **THEN** the modal closes deterministically
+- **AND** focus returns to a stable, previously active control
+
+### Requirement: Modal content preserves source link-out behavior
+The system SHALL provide source link-outs from the summary modal and keep share interactions stable.
+
+#### Scenario: Source link-out from modal
+- **WHEN** a user clicks source/citation link in the modal
+- **THEN** the original source opens in a new tab/window
+- **AND** modal behavior remains stable for continued browsing
+
+#### Scenario: Modal exposes share entry points
+- **WHEN** a summary modal is open for an article
+- **THEN** share controls for the article permalink are available from modal/footer share area
+
+#### Scenario: Modal interaction regression coverage
+- **WHEN** Playwright modal-flow tests execute
+- **THEN** open/close/source/share interactions pass for hero-origin and feed-origin entry paths
+- **AND** regressions in modal ordering or interaction wiring are detected

openspec/changes/p17-regression-defects/specs/wcag-2-2-aa-accessibility/spec.md

@@ -0,0 +1,24 @@
+## MODIFIED Requirements
+
+### Requirement: Core user flows comply with WCAG 2.2 AA baseline
+The system SHALL meet WCAG 2.2 AA accessibility requirements for primary interactions and content presentation, including icon-only controls and policy-disclosure modals, and SHALL verify compliance through automated accessibility checks in CI and browser-driven interaction tests.
+
+#### Scenario: Keyboard-only interaction flow
+- **WHEN** a keyboard-only user navigates policy modals and icon-only controls
+- **THEN** all primary interactive elements are reachable and operable
+- **AND** visible focus indication is present at each step
+
+#### Scenario: Contrast and non-text alternatives
+- **WHEN** users consume text and non-text UI content
+- **THEN** color contrast meets AA thresholds for relevant text and controls
+- **AND** icon-only controls expose meaningful accessible labels
+
+#### Scenario: Accessibility CI gate
+- **WHEN** pull request validation runs
+- **THEN** automated accessibility checks execute against key pages and flows
+- **AND** violations above configured severity fail the gate
+
+#### Scenario: Playwright verifies interactive accessibility states
+- **WHEN** accessibility-focused Playwright tests execute
+- **THEN** focus-visible, keyboard traversal, and accessible-name assertions pass for critical controls
+- **AND** regressions in theme-specific contrast and state visibility are detected

openspec/changes/p17-regression-defects/tasks.md

@@ -0,0 +1,45 @@
+## 1. Playwright Foundation and Harness
+
+- [ ] 1.1 Add Playwright project setup (config, scripts, browser install, test directory layout).
+- [ ] 1.2 Implement shared fixtures for seeded app state, authless startup, and deterministic article data assumptions.
+- [ ] 1.3 Define viewport profiles (mobile/tablet/desktop) and theme profile helpers (light/dark/contrast).
+- [ ] 1.4 Add stable selector strategy for critical controls (role/test-id fallback rules) to reduce locator fragility.
+
+## 2. Capability Coverage Matrix and Strategy
+
+- [ ] 2.1 Create capability-to-test mapping document covering all current OpenSpec UI-facing capabilities.
+- [ ] 2.2 Define scenario taxonomy (journey, accessibility-state, responsive, modal, microinteraction, deep-link).
+- [ ] 2.3 Define smoke vs full regression profiles and execution criteria per CI stage.
+
+## 3. Core Journey and Modal Flows
+
+- [ ] 3.1 Implement Playwright scenarios for hero/feed browsing and summary modal open/close across entry paths.
+- [ ] 3.2 Add deep-link permalink tests validating valid, invalid, and hero-origin modal flows.
+- [ ] 3.3 Add source CTA/share/copy interaction tests in modal and verify non-breaking navigation behavior.
+
+## 4. Accessibility and Interaction State Regression
+
+- [ ] 4.1 Implement keyboard-navigation and focus-visible assertions for primary interactive controls.
+- [ ] 4.2 Implement color-contrast/state assertions for text/link/control states across light/dark/contrast themes.
+- [ ] 4.3 Add icon-only control accessible-name assertions (share, copy, back-to-top, theme controls, modal actions).
+- [ ] 4.4 Add policy modal accessibility tests for open, escape-close, focus-return, and focus containment behavior.
+
+## 5. Responsive and Footer Microinteractions
+
+- [ ] 5.1 Implement responsive regression tests for mobile/tablet/desktop ensuring no overflow/clipping on key surfaces.
+- [ ] 5.2 Add sticky header/footer and floating back-to-top behavior checks across breakpoints.
+- [ ] 5.3 Add footer contact-email tooltip tests for mouse hover/move/leave and keyboard focus/blur interactions.
+- [ ] 5.4 Add env-driven footer link rendering tests for present/absent GitHub/contact config combinations.
+
+## 6. Quality Gate Integration and Reporting
+
+- [ ] 6.1 Integrate Playwright smoke suite into pull-request quality gate with fail-on-regression policy.
+- [ ] 6.2 Integrate full Playwright profile into main/nightly pipeline stage with artifact retention.
+- [ ] 6.3 Enable trace/screenshot/video capture on failure and expose artifact links in CI logs.
+- [ ] 6.4 Document triage workflow and ownership for UI/UX regression failures.
+
+## 7. Validation and Readiness
+
+- [ ] 7.1 Run smoke profile locally and in CI, fixing flakiness until deterministic pass criteria are met.
+- [ ] 7.2 Run full profile and confirm required capability coverage matrix is satisfied.
+- [ ] 7.3 Verify OpenSpec capability requirements in this change are test-mapped and implementation-ready.