Card Forge - Nova Lab

Card Forge Overview

Card Forge is a modular system for creating and managing digital identity cards—avatars, stats, and badges—for the AmbientPixels/Nova ecosystem. It is designed for easy extension, theming, and integration with Nova's mood-driven UI.

🚀 Quick Start

1. Prerequisites: Node.js 18+, VS Code, Azure account (for blob storage).
2. Clone & Install: git clone ..., npm install in project root.
3. Run Dev Server: npx serve lab/card-forge/ or use VS Code Live Server.
4. Test Blob Storage: Ensure AZURE_STORAGE_CONNECTION_STRING is set (see project-card-forge.me for details).
5. Edit & Preview: Open lab/card-forge/index.html and start editing cards.
6. Reference: See Session Log & Reference Sheet for troubleshooting and config tips.

🔄 Session Restart / Handoff Checklist

Check project-card-forge.me for the latest blockers, TODOs, and breakthroughs.
Review the "Reference Sheet" and "Next Steps" in this doc and the .me log.
Resume work in lab/card-forge/index.html and card-forge.js (or as noted in the log).
Test blob save/load via the UI; check Azure logs if errors occur.
Document any changes or issues in both this HTML doc and the .me log.

🛠️ Troubleshooting & FAQ

Blob upload fails: Check AZURE_STORAGE_CONNECTION_STRING in Azure portal; must be full connection string.
500 error + blank response: Usually missing dependency or module type mismatch in /api/package.json.
405 error: Ensure api_location: "api" is set in GitHub workflow YAML.
404/MIME errors: Use absolute asset paths for all JS/CSS/images.
UI not updating: Make sure you’re editing the correct files and that browser cache is cleared.
See more common issues and fixes in the "Reference Sheet" in project-card-forge.me.

🤝 Contribution & Style Guide

Reuse existing Nova/AmbientPixels CSS classes (see components.css, nova.css, nova-mood.css).
No inline styles; all new styles go in card-forge.css and must be scoped.
JS: Modularize logic, no global leaks; main logic in card-forge.js and card-forge-editor.js.
Document all changes here and in project-card-forge.me.
Follow Windsurf dev protocols: no duplicate blocks, always replace with precision.
Reference Documentation Template for new feature docs.

Dev/Test Environment

Isolated dev sandbox: /lab/card-forge/
Live test page: lab/card-forge/index.html
All assets (JS, CSS, JSON) are local and hot-reloadable
Safe for rapid prototyping and CI/CD

File Structure

lab/card-forge/index.html — Dev/test harness for Card Forge
lab/card-forge/card-forge.js — Main rendering logic (exports window.renderRpgAvatarCards)
lab/card-forge/card-forge.css — All card-specific styles
lab/card-forge/card-forge.json — Card data (avatars, stats, badges, etc.)
docs/project-card-forge.html — This documentation page
docs/logs/project-card-forge.me — Markdown changelog/spec

Features

Avatar card rendering with flip animation
Stats, badges, achievements, and links
Theming (legendary, epic, rare, etc.)
Role-based badge logic
Responsive grid layout
Isolated dev/test mode with devMode flag
Integrated with Nova's crystalline aesthetic

Technical Architecture

Frontend: HTML + CSS + JS (modular, no inline styles)
Rendering: CSS Grid, card-forge.js, future export support
Data: JSON-driven (card-forge.json)
Dev Agent: Cascade (Windsurf AI) for code logic
Deployment: GitHub + Azure CI/CD

How to Extend

Add or edit cards in card-forge.json
Customize rendering in card-forge.js (see renderRpgAvatarCards)
Update or extend styles in card-forge.css
Use devMode for test features and debugging
Document changes in project-card-forge.me

Next Steps: Card Forge Card Editor UI

Current Status (as of 2025-06-26)

✅ 3-column grid layout complete: Sidebar, live preview, and tabbed forms are fully aligned and responsive.
✅ Azure Function Save Integration: Card Forge now saves card data to Azure Blob Storage via /api/saveCardData.
✅ Asset Loading Fixed: All Card Forge assets use absolute paths, resolving 404/MIME errors on custom domains.
✅ Backend Debugging: 500 error resolved by setting api_location in workflow, fixing package.json, and adding error logging.
⚠️ Most interactive features non-functional: Add/Remove Card, Import/Export, Save/Reset, and tab switching currently do not work. Card style selector and live preview update are functional.
🛠️ JavaScript event handling and state logic pending: UI is ready for JS wiring and further UX polish.

Next Steps

Debug and restore all button and form event handlers (Add, Remove, Import, Export, Save, Reset, Flip, etc.)
Fix tab switching logic for Front/Back panels
Ensure all form inputs update the live preview and card data
Restore card list interactivity and persistent storage
Add user feedback and error handling
Update documentation, logs, and project JSON as features are restored

Reference Sheet (Persistent)

Frontend: /lab/card-forge/index.html, card-forge.js, card-forge.css, card-forge-editor.js
Data: /lab/card-forge/card-forge.json (card data), /data/rpg-avatar-cards.json (main deck)
Backend: /api/saveCardData/index.js (Azure Function, CommonJS, saves JSON to Blob Storage)
API Config: /api/package.json (must have @azure/storage-blob dep, no type: module)
CI/CD: .github/workflows/azure-static-web-apps-*.yml (must set api_location: "api")
Logs/Docs: /docs/logs/project-card-forge.me (log), /docs/project-card-forge.html (feature/tech doc)
Azure: Set AZURE_STORAGE_CONNECTION_STRING in Azure portal (full string, not just key). Function creates cardforge container if missing.
Error Logging: Stack traces included in dev, remove for production.
Common Issues: 500 error + blank response: usually missing dep or module type mismatch. 405 error: missing api_location in workflow. 404/MIME errors: use absolute asset paths.
Dev Protocols: No inline styles; reuse Nova/AmbientPixels CSS classes. All JS modularized, no global leaks. Document all changes here and in /docs/project-card-forge.me.
Use this sheet as your persistent reference if memory is lost—summarize blockers, breakthroughs, and key config.

Core Features

-----------------------------------------------------
|  Sidebar/List      |  Card Editor Form   | Preview |
|--------------------|--------------------|---------|
| [Card 1]           | Name: [______]     | [Card]  |
| [Card 2]           | Avatar: [url/up]   |         |
| [+ Add Card]       | ...                |         |
| [Import/Export]    | [Save] [Reset]     |         |
-----------------------------------------------------

On mobile, sidebar collapses to dropdown or modal.

Technical Approach

Reuse existing CSS: Nova/AmbientPixels classes, no new color/badge styles.
No inline styles: All styles in card-forge.css or existing CSS.
Componentized JS: Editor logic in card-forge-editor.js, rendering in card-forge.js.
Data: Edits operate on a JS object mirroring card-forge.json.
Persistence: Save to localStorage and/or allow download/upload of JSON.

Steps to Implement

Design UI skeleton in /lab/card-forge/index.html.
Create card-forge-editor.js for editor logic and events.
Wire up live preview using renderCardForge.
Implement add/edit/remove/reorder logic for card data.
Add import/export functionality (JSON validation, error handling).
Polish accessibility and mobile layout.
Update documentation to include editor usage and extension points.
(Optional) Add test cases for schema validation and UI interactions.

Stretch Goals

Image upload/preview with drag-and-drop support.
Undo/redo for edits.
Multi-user collaboration (future backend).
Theme preview switcher for instant card restyling.

References & Links

Half-width Section (6 columns)

Combine grid-col-6 for side-by-side layouts.

Another Half-width Section

Place next to the previous for a two-column layout.