Infrastructure/implement e2e tests

.github/instructions/general.instructions.md

@@ -35,7 +35,9 @@ applyTo: "**"
 - JavaScript loading warnings from happy-dom are silenced in vitest.setup.ts for clean test output.
 - A working example test using the Container API is available at /home/kevin/Repos/Webstack Builders/Corporate Website/astro.webstackbuilders.com/src/components/Test/container.spec.ts
 - **NEVER hard-code content slugs in e2e tests** (e.g., `/articles/typescript-best-practices`, `/services/web-development`). Content can be deleted or renamed. Always dynamically fetch the first available item from listing pages (articles, services, case-studies, etc.) and navigate to it. This prevents test breakage when content changes.
-- **Playwright E2E Tests**: Set `DEBUG=1` environment variable to prevent the dev server from being launched by the Playwright test runner. This is useful when you want to run tests against an already running dev server.
+- **Playwright E2E Tests**: ALWAYS run with `DEBUG=1` environment variable (e.g., `DEBUG=1 npx playwright test`). This prevents the Playwright test runner from launching its own dev server. The user maintains a running dev server for development.
+- **NEVER run the full e2e test suite** unless explicitly requested by the user. The full suite is very resource intensive and takes over 10 minutes to run. Only run specific e2e test files when verification is needed (e.g., `DEBUG=1 npx playwright test test/e2e/specific-file.spec.ts`).
+- **NEVER start a dev server yourself**. The user runs their own dev server for development. When you need a dev server running, notify the user instead of starting one.
 
 # Personality
 - Do not apologize

.github/workflows/build-and-test.yml

@@ -3,7 +3,6 @@ name: CI - Build & Test
 
 on:
   push:
-    branches: [main]
   pull_request:
     branches: [main]
 
@@ -25,6 +24,9 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Run TypeScript check
+        run: npm run check
+
       - name: Run lint
         run: npm run lint
 

.github/workflows/type-check.yml

@@ -0,0 +1,31 @@
+# Fast code quality checks (TypeScript + Linting)
+name: Code Quality Check
+
+on:
+  push:
+  pull_request:
+    branches: [main]
+
+jobs:
+  quality-check:
+    name: Code Quality Check
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22.x"
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run TypeScript check
+        run: npm run check
+
+      - name: Run linting
+        run: npm run lint

.husky/pre-commit

@@ -1,7 +1,25 @@
 #!/bin/sh
 
+# Load nvm if available and use appropriate node version
+if [ -f "$HOME/.nvm/nvm.sh" ]; then
+  . "$HOME/.nvm/nvm.sh"
+  # Try different nvm use strategies in order of preference
+  if nvm use 2>/dev/null; then
+    echo "Using current nvm node version"
+  elif nvm use node 2>/dev/null; then
+    echo "Using latest nvm node version"
+  elif nvm use --lts 2>/dev/null; then
+    echo "Using LTS node version"
+  else
+    echo "Using system node version"
+  fi
+fi
+
+# Run TypeScript check (fast feedback on type errors)
+npm run check
+
 # Run unit tests (fast feedback)
-nvm use default && npm run test:unit
+npm run test:unit
 
 # Verify branch naming convention
 .husky/scripts/check-branch-name.sh

.vscode/settings.json

@@ -31,6 +31,7 @@
     "Flink",
     "FNAME",
     "fosstodon",
+    "glidejs",
     "GSAP",
     "hocho",
     "Hudi",
@@ -67,9 +68,12 @@
     "Qualys",
     "repost",
     "reposts",
+    "RGAA",
     "Ryuk",
+    "samp",
     "SCORM",
     "shiki",
+    "shikijs",
     "shipit",
     "SIEM",
     "signup",

README.md

@@ -143,58 +143,7 @@ To add a new theme (e.g., a holiday theme), follow these steps:
 
 #### 1. Add CSS Variables in `src/styles/themes.css`
 
-Add a new CSS rule with your theme's custom properties:
-
-```css
-/* Holiday Theme Example */
-[data-theme="holiday"] {
-  /* Background Colors */
-  --color-bg: #0f172a;
-  --color-bg-offset: #1e293b;
-
-  /* Text Colors */
-  --color-text: #f1f5f9;
-  --color-text-offset: #cbd5e1;
-
-  /* Primary Brand Colors */
-  --color-primary: #dc2626;
-  --color-primary-offset: #991b1b;
-  --color-primary-bg: #7f1d1d;
-  --color-primary-bg-hover: #991b1b;
-  --color-primary-hover: #b91c1c;
-
-  /* Secondary Colors */
-  --color-secondary: #16a34a;
-  --color-secondary-offset: #15803d;
-  --color-secondary-bg: #052e16;
-
-  /* Status Colors */
-  --color-success: #16a34a;
-  --color-success-offset: #22c55e;
-  --color-success-bg: #052e16;
-
-  --color-info: #0891b2;
-  --color-info-bg: #164e63;
-
-  --color-warning: #a16207;
-  --color-warning-offset: #ca8a04;
-  --color-warning-bg: #451a03;
-
-  --color-danger: #dc2626;
-  --color-danger-bg: #7f1d1d;
-
-  /* Special Colors */
-  --color-twitter: #1da1f2;
-  --color-modal-background: #0f172a;
-
-  /* Accent Colors */
-  --color-accent: #fbbf24;
-  --color-accent-bg: #451a03;
-
-  /* Syntax Highlighting */
-  --shiki-theme: 'github-dark';
-}
-```
+Add a new CSS rule with the theme's custom colors following the pattern of existing themes in this file.
 
 #### 2. Register Theme in `src/lib/themes.ts`
 

THEME_SYSTEM_WIP.md

@@ -0,0 +1,127 @@
+# Theme System - Work in Progress
+
+## Current Status
+
+### What's Working
+- ✅ Theme picker tests: 9/10 @ready (63 tests passing across 7 browsers)
+- ✅ Manual theme selection and persistence works correctly
+- ✅ Theme switching via theme picker UI works
+- ✅ View Transitions correctly maintain theme across page navigations
+- ✅ CSS architecture refactored: `@theme inline` uses `var()` references instead of hard-coded values
+
+### What's Broken
+- ❌ **System preference (prefers-color-scheme) not respected on first visit in real browser**
+  - Test passes but real usage fails
+  - Opening site in new incognito window with dark mode preference shows light theme
+  - Google.com correctly shows dark, but our site doesn't
+
+- ❌ **Theme picker buttons should show their own theme's colors**
+  - Dark theme button should use `--dark-color-*` variables
+  - Default theme button should use `--light-color-*` variables
+  - Currently all buttons use light theme colors (partially fixed but needs completion)
+
+## Root Cause Analysis
+
+### System Preference Issue
+
+The problem is a **race condition** between:
+1. HEAD inline script (synchronous) - correctly sets `data-theme="dark"` based on `prefers-color-scheme`
+2. `persistentAtom` restore (asynchronous) - overwrites theme back to 'default'
+
+**Sequence of events:**
+```
+1. HEAD script runs → checks localStorage (empty) → checks prefersDark=true → sets data-theme="dark" ✓
+2. persistentAtom initializes with default value 'default'
+3. Our init code runs with setTimeout(100ms)
+4. persistentAtom's restore() completes (async) → fires .listen() → overwrites to 'default' ✗
+```
+
+**Current fix attempt:**
+- Using `isInitialized` flag to prevent `.listen()` from applying themes until init completes
+- Using `setTimeout(100ms)` to delay init until after `persistentAtom.restore()` completes
+- **Problem:** The timing is unreliable - 100ms might not be enough on slower devices
+
+**Test vs Reality:**
+- Playwright test passes because it's using `emulateMedia({ colorScheme: 'dark' })`
+- Real browser behavior is different - the race condition manifests differently
+- Test needs to be improved to catch this real-world bug
+
+## Files Modified
+
+### Theme Initialization
+- `src/components/Scripts/state/store/themes.ts` (lines 127-180)
+  - Changed from `.subscribe()` to `.listen()` to avoid immediate firing
+  - Added `isInitialized` flag to gate theme applications
+  - Added `setTimeout(100)` to wait for `persistentAtom.restore()`
+  - **HAS DEBUG LOGGING** - needs to be removed before commit
+
+### Theme Picker UI
+- `src/components/ThemePicker/Themes.astro` (lines 97-120)
+  - **NOT YET FIXED** - still needs to map theme.id to color prefix
+  - Should use `--${colorPrefix}-color-*` variables per button
+
+### HEAD Script
+- `src/components/Head/index.astro` (lines 56-63)
+  - Correctly checks `prefers-color-scheme` and sets `data-theme`
+  - Logic: stored theme (if not 'default') > system preference > 'default'
+
+### CSS Architecture
+- `src/styles/themes.css`
+  - ✅ Lines 65-105: `@theme inline` refactored to use `var()` references
+  - ✅ All theme-specific colors defined at `:root` level
+  - Has `--light-color-*`, `--dark-color-*`, and base `--color-*` variables
+
+## Next Steps
+
+### High Priority
+1. **Fix system preference detection**
+   - Option A: Find more reliable way to detect when `persistentAtom.restore()` completes
+   - Option B: Use `MutationObserver` to watch for theme changes from restore
+   - Option C: Initialize theme BEFORE importing `persistentAtom`
+   - Option D: Use regular `atom` for store, manually sync to localStorage after restore completes
+   - Option E: Don't rely on setTimeout - use `requestIdleCallback` or similar
+
+2. **Fix theme picker button colors**
+   - Complete the Themes.astro fix to show each theme's own colors
+   - Map `theme.id` to color variable prefix: 'default' → 'light', 'dark' → 'dark'
+   - Update color swatches to use theme-specific variables
+
+3. **Remove debug logging**
+   - `src/components/Scripts/state/store/themes.ts` has console.log statements
+   - Clean these up before final commit
+
+### Test Improvements
+4. **Make test match real browser behavior**
+   - Current test uses `emulateMedia()` which might not trigger same race condition
+   - Consider testing with actual localStorage clearing and page reload
+   - Add test that validates theme immediately on page load (before JS runs)
+
+## Technical Constraints
+
+- **MUST use `persistentAtom`** - required for View Transitions to maintain theme across navigations
+- **CANNOT use regular `atom`** - will lose persistence across page navigations
+- HEAD script must run synchronously to prevent FOUC (Flash of Unstyled Content)
+- Theme must be applied before page renders (critical for UX)
+
+## Code Locations
+
+- Theme store: `src/components/Scripts/state/store/themes.ts`
+- Theme picker UI: `src/components/ThemePicker/Themes.astro`
+- Theme picker element: `src/components/ThemePicker/theme-picker-element.ts`
+- HEAD script: `src/components/Head/index.astro` (lines 56-63)
+- CSS themes: `src/styles/themes.css`
+- E2E tests: `test/e2e/specs/04-components/theme-picker.spec.ts` (line 134 is failing test)
+
+## Questions to Answer
+
+1. When exactly does `persistentAtom.restore()` complete?
+2. Is there an event or promise we can wait for?
+3. Should we implement our own localStorage persistence instead of using `persistentAtom`?
+4. Can we leverage the `@media (prefers-color-scheme: dark)` CSS to avoid needing JS for system preference?
+
+## Useful Context
+
+- The `@media (prefers-color-scheme: dark)` CSS rule at lines 337-373 in themes.css correctly applies dark theme
+- This CSS works WITHOUT JavaScript
+- The issue is the JS is overriding this CSS by setting `data-theme="default"`
+- Maybe we should NOT set `data-theme` at all when using system preference?

TODO.md

@@ -1,13 +1,75 @@
 # TODO
 
-From the error output, the article page has:
-
-<h1 id="article-title"> - the actual article title (correct)
-<h1 id="create-custom-font-sets-use-font-forge"> - from markdown content (wrong!)
-<h1>No islands detected.</h1> - from some debug/dev tool
-<h1>Audit</h1> - from some debug/dev tool
-<h1>No accessibility or performance issues detected.</h1> - from debug/dev tool
-<h1>Settings</h1> - from debug/dev tool
+Files with Skipped Tests:
+
+social-shares.spec.ts - 12 @wip
+gdpr-consent.spec.ts - 10 @wip
+
+Blocked Categories (44 tests):
+
+Visual regression testing (18) - Needs Percy/Chromatic
+PWA functionality (12) - Service workers not implemented
+Lighthouse audits (6) - Integration pending
+Newsletter double opt-in (6) - Email testing infrastructure
+Axe accessibility (2) - axe-core integration
+
+\[color:var\(--color-(.*?)\)\]
+
+## Axe tags
+
+cat.aria: Rules related to Accessible Rich Internet Applications (ARIA) attributes and roles.
+cat.color: Rules related to color contrast and meaning conveyed by color.
+cat.controls: Rules for interactive controls, such as form elements and links.
+cat.forms: Rules specifically for forms, form fields, and their labels.
+cat.keyboard: Rules related to keyboard operability.
+cat.links: Rules for links, including their names and destinations.
+cat.name-role-value: Rules that check if an element has a name, role, and value that can be correctly interpreted by assistive technologies.
+cat.semantics: Rules related to the semantic structure of a document, such as headings and landmarks.
+cat.sensory-and-visual-cues: Rules that deal with information conveyed by sensory or visual characteristics.
+cat.structure: Rules related to the document's overall structure, like the proper nesting of elements.
+cat.tables: Rules for data tables, including headers and associations.
+cat.text-alternatives: Rules for ensuring that text alternatives are provided for non-text content, such as images.
+
+## Social Media Preview Cards
+
+Looking at the social-card endpoint implementation, it's designed to work with third-party screenshot services, not the social networks themselves.
+
+Here's how it works:
+
+The Two Formats
+HTML format (format=html or default): Returns a full HTML page with inline CSS styled as a 1200x630px card - the standard Open Graph image dimensions.
+
+OG format (format=og): Returns JSON with Open Graph meta tags, where the og:image URL points back to the HTML version of the card.
+
+How Social Networks Actually Work
+Social networks like Twitter, Facebook, LinkedIn, etc. don't screenshot HTML pages. They expect:
+
+- Direct image URLs (PNG, JPEG, etc.)
+- Standard dimensions (1200x630px for most platforms)
+
+The Intended Workflow
+
+This endpoint is designed to integrate with screenshot services like:
+
+- Puppeteer or Playwright - Run your own screenshot service
+- Vercel OG Image Generation - Vercel's built-in service
+- Cloudinary - Can fetch and screenshot URLs
+- ScreenshotOne or ApiFlash - Dedicated screenshot APIs
+- Satori - Convert HTML/CSS to SVG/PNG
+
+Current Limitation
+
+As implemented, this endpoint would need an additional step to be useful for social sharing:
+
+Your endpoint → Screenshot service → Image file → Social networks
+
+Better Approaches
+
+For a production Astro site, you'd typically:
+
+- Use @vercel/og or Satori to generate actual images server-side
+- Pre-generate images at build time for static content
+- Use a screenshot service that can be called from your endpoint to return actual images
 
 ## @TODO: Use Confetti on CTA forms