Merge branch 'upstream/main' into feat/issue-972-sqlite-support

Author: knoxiboy

.DS_Store

@@ -0,0 +1,47 @@
+name: Playwright E2E Tests
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    timeout-minutes: 15
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: 20
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.12"
+
+    - name: Install dependencies
+      run: |
+        cd web-app
+        npm ci
+
+    - name: Install Playwright Browsers
+      run: |
+        cd web-app
+        npx playwright install --with-deps
+
+    - name: Run Playwright tests
+      run: |
+        cd web-app
+        npx playwright test
+
+    - name: Upload Playwright Report
+      uses: actions/upload-artifact@v4
+      if: always()
+      with:
+        name: playwright-report
+        path: web-app/playwright-report/
+        retention-days: 30

.github/workflows/playwright.yml

@@ -33,4 +33,4 @@ jobs:
         
     - name: Run automated tests
       run: |
-        python -m unittest discover -s tests -v
+        pytest tests/ -v --tb=short

.github/workflows/python-ci.yml

@@ -66,8 +66,76 @@ Then open `http://localhost:8000` in your browser.
 - Works on mobile, tablet, and desktop
 - No console errors
 
+## 🎯 Modal Requirements
+
+For modals to work correctly in the web app, the following IDs are required:
+
+| ID | Purpose |
+|----|---------|
+| `projectModal` | Main modal container |
+| `modalBody` | Container for project content |
+| `modalClose` | Button to close modal |
+
+**Example HTML structure:**
+
+```html
+<div class="modal" id="projectModal">
+  <div class="modal-content">
+    <div class="modal-header">
+      <button class="modal-close" id="modalClose">&times;</button>
+    </div>
+    <div id="modalBody"></div>
+  </div>
+</div>
+```
+
+## 📦 Adding a Project Card
+
+To add a new project card to the homepage, add this HTML inside `projectsTemplate`:
+
+```html
+<div class="project-card" data-category="games" data-project="your-project-name" data-tags="tag1,tag2,tag3">
+    <img class="card-banner" src="assets/banners/your-project.webp" alt="Project Name" loading="lazy">
+    <div class="card-actions">
+        <button class="btn-play">Try It</button>
+    </div>
+    <h3>Project Name</h3>
+    <p>Brief description of your project</p>
+</div>
+```
+
+**Required attributes:**
+
+- `data-category`: `games`, `math`, or `utilities`
+- `data-project`: Unique project identifier
+- `data-tags`: Search keywords (comma separated)
+
+## ✅ Web PR Testing Checklist
+
+Before submitting a web-related PR, test the following:
+
+- Project modal opens when clicking "Try It"
+- Theme toggle switches between dark/light mode
+- Search bar filters projects correctly
+- No console errors (`F12` → Console)
+- Mobile view works (320px width)
+- Keyboard navigation (Tab, Enter, Escape)
+- Project closes properly with ✕ button and Escape key
+
+## 🚫 What NOT to Do
+
+Avoid these common mistakes:
+
+| Mistake | Why It's Bad |
+|---------|--------------|
+| Duplicate element IDs | Breaks JavaScript functionality |
+| Opening `index.html` directly | Use `python -m http.server 8000` |
+| Forgetting to register in `projects.js` | Project won't load |
+| Hardcoding colors | Use CSS variables instead |
+| Breaking template structure | Causes project cards to disappear |
+
 ## Notes
 
 - Use the worker for any long-running Python execution.
 - Stop execution by terminating the worker and creating a fresh one.
-- Keep changes small and consistent with the existing UI.
+- Keep changes small and consistent with the existing UI.

.gitignore

@@ -104,7 +104,7 @@ def load_high_score(self):
     def save_high_score(self):
         try:
             HIGH_SCORE_PATH.write_text(str(self.high_score))
-        except Exception as e:
+        except OSError as e:
             print(f"Warning: Could not save high score: {e}")
 
     def create_grid(self):
@@ -330,7 +330,10 @@ def restart_game(self):
         self.root.bind("<Key>", self.handle_keypress)
 
 
-if __name__ == "__main__":
+def main():
     root = tk.Tk()
     game = Game2048(root)
-    root.mainloop()
+    root.mainloop()
+
+if __name__ == "__main__":
+    main()