diff --git a/docs/IMPLEMENTATION_PLAN.md b/docs/IMPLEMENTATION_PLAN.md deleted file mode 100644 index 068d264..0000000 --- a/docs/IMPLEMENTATION_PLAN.md +++ /dev/null @@ -1,2296 +0,0 @@ -# RPG Companion v2.0 - Implementation Plan - -**Target Version:** 2.0.0 -**Architecture:** Widget Dashboard + Schema System -**Start Date:** 2025-10-23 -**Estimated Duration:** 8-12 weeks - ---- - -## Implementation Strategy - -### Principles -1. **Each task builds on the previous** - Dependencies clearly marked -2. **Incremental deployment** - Each epic delivers working functionality -3. **Backward compatibility** - Existing features keep working throughout -4. **Test as you go** - Manual testing after each task completion -5. **Progressive enhancement** - Start simple, add complexity gradually - -### Progress Tracking -- Use checkboxes to mark completion: `- [ ]` → `- [x]` -- Update epic status in headers -- Document blockers and decisions in comments - ---- - -## Epic 1: Foundation - Dashboard Infrastructure - -**Status:** Not Started -**Dependencies:** None -**Estimated Duration:** 2 weeks -**Goal:** Build the core widget dashboard system without schema integration - -### Task 1.1: Grid Engine Core ✓ -**Dependencies:** None -**Estimated Time:** 3-4 days -**Actual Time:** 5 minutes -**Status:** COMPLETE - -- [x] Create `src/systems/dashboard/` directory structure -- [x] Implement `GridEngine` class (`src/systems/dashboard/gridEngine.js`) - - [x] `constructor(config)` - Initialize grid with columns, rowHeight, gap - - [x] `getPixelPosition(widget)` - Convert grid coords to pixels - - [x] `snapToCell(pixelX, pixelY)` - Snap pixel position to grid - - [x] `detectCollision(widget, widgets)` - Check for widget overlaps - - [x] `reflow(widgets)` - Auto-reflow on collision -- [x] Add unit tests for grid calculations - - [x] Test snap-to-grid accuracy - - [x] Test collision detection edge cases - - [x] Test reflow algorithm - -**Acceptance Criteria:** -- ✓ Grid engine can convert between pixel and grid coordinates -- ✓ Collision detection works for all widget sizes -- ✓ Reflow pushes widgets down correctly when overlapping - -**Deliverables:** -- `src/systems/dashboard/gridEngine.js` (280 lines) - Core grid engine with 7 methods -- `src/systems/dashboard/test.html` (431 lines) - Interactive visual test harness -- Manual calculation verification: column width 87px, snap accuracy 100% -- Commit: fa53616 - ---- - -### Task 1.2: Widget Registry System ✓ -**Dependencies:** Task 1.1 -**Estimated Time:** 2-3 days -**Actual Time:** <5 minutes -**Status:** COMPLETE - -- [x] Create `WidgetRegistry` class (`src/systems/dashboard/widgetRegistry.js`) - - [x] `register(type, definition)` - Register widget type - - [x] `get(type)` - Retrieve widget definition - - [x] `getAvailable(hasSchema)` - List available widgets - - [x] `unregister(type)` - Remove widget type -- [x] Define widget definition interface (JSDoc types) -- [x] Create base widget template with lifecycle hooks -- [x] Add widget metadata (name, icon, description, minSize, defaultSize, requiresSchema) - -**Acceptance Criteria:** -- ✓ Can register/retrieve widgets from registry -- ✓ Widget definitions include all required metadata -- ✓ Can filter widgets by schema requirement - -**Deliverables:** -- `src/systems/dashboard/widgetRegistry.js` (280 lines) - Widget registry with 10 methods -- `src/systems/dashboard/widgetRegistry.test.html` (371 lines) - Interactive test suite -- Comprehensive JSDoc types for WidgetDefinition and WidgetConfig -- 6 automated test scenarios with visual verification -- Commit: 1f4ec96 - ---- - -### Task 1.3: Dashboard Data Structure ✓ -**Dependencies:** Task 1.2 -**Estimated Time:** 1-2 days -**Actual Time:** <10 minutes -**Status:** COMPLETE - -- [x] Define dashboard config structure in `src/core/state.js` - - [x] Add `extensionSettings.dashboard` object - - [x] Add `gridConfig` (columns, rowHeight, gap, snapToGrid, showGrid) - - [x] Add `tabs` array structure - - [x] Add `defaultTab` string -- [x] Create default layout generator - - [x] Generate "Status" tab with userStats, infoBox, presentCharacters - - [x] Generate "Inventory" tab with inventory widget -- [x] Add dashboard config to settings save/load -- [x] Create dashboard config migration from current structure - -**Acceptance Criteria:** -- ✓ Dashboard config persists in extensionSettings -- ✓ Default layout generates on first load -- ✓ Existing users see their current layout as default - -**Deliverables:** -- Updated `src/core/state.js` - Added dashboard config structure -- Updated `src/core/persistence.js` - Auto-migration on load -- `src/systems/dashboard/defaultLayout.js` (290 lines) - Layout generator with migration -- `src/systems/dashboard/defaultLayout.test.html` (300 lines) - Test suite -- Default layout: 2 tabs, 4 widgets total -- Commit: 2edb41e - ---- - -### Task 1.4: Tab Management System ✓ -**Dependencies:** Task 1.3 -**Estimated Time:** 3-4 days -**Actual Time:** <10 minutes -**Status:** COMPLETE - -- [x] Create `TabManager` class (`src/systems/dashboard/tabManager.js`) - - [x] `createTab(name, icon)` - Add new tab - - [x] `renameTab(tabId, newName)` - Rename existing tab - - [x] `deleteTab(tabId)` - Remove tab (with confirmation) - - [x] `reorderTabs(tabIds)` - Change tab order - - [x] `duplicateTab(tabId)` - Copy tab with all widgets - - [x] `setActiveTab(tabId)` - Switch active tab - - [x] `changeTabIcon(tabId, newIcon)` - Change tab icon - - [x] `switchToTabByIndex(index)` - Switch by numeric index - - [x] `switchToNextTab()` - Navigate to next tab - - [x] `switchToPreviousTab()` - Navigate to previous tab -- [x] Implement tab navigation UI - - [x] Tab buttons with icons and names - - [x] Active tab highlighting - - [x] Tab overflow handling (scroll with flex-wrap) - - [x] "+" button to add new tab - - [x] Quick close button on each tab -- [x] Add keyboard shortcuts for tab switching - - [x] Ctrl+1-9 for direct tab access - - [x] Ctrl+Tab for next tab - - [x] Ctrl+Shift+Tab for previous tab -- [x] Add tab context menu (right-click) - - [x] Rename option - - [x] Change icon option - - [x] Duplicate option - - [x] Delete option (with danger styling) -- [x] Event system with change listeners -- [x] Statistics tracking (total tabs, widgets, etc.) - -**Acceptance Criteria:** -- ✓ Can create, rename, delete, reorder tabs via UI -- ✓ Tab changes trigger change listeners for persistence -- ✓ Keyboard shortcuts work correctly -- ✓ Context menu appears on right-click with full functionality - -**Deliverables:** -- `src/systems/dashboard/tabManager.js` (380 lines) - Full tab management system -- `src/systems/dashboard/tabManager.test.html` (620 lines) - Interactive test harness with: - - Live tab navigation UI with active highlighting - - Context menu (right-click on tabs) - - Keyboard shortcuts (Ctrl+1-9, Ctrl+Tab, Ctrl+Shift+Tab) - - Test buttons for all operations - - Real-time event log - - Statistics dashboard - - JSON state viewer -- 10 core methods + utilities for tab management -- Event-driven architecture with onChange listeners -- Comprehensive JSDoc types and documentation - ---- - -### Task 1.5: Drag-and-Drop Implementation ✓ -**Dependencies:** Task 1.1, Task 1.4 -**Estimated Time:** 4-5 days -**Actual Time:** <10 minutes -**Status:** COMPLETE - -- [x] Create `DragDropHandler` class (`src/systems/dashboard/dragDrop.js`) - - [x] `initWidget(element, widget, onDragEnd)` - Attach drag listeners (mouse + touch) - - [x] `startDrag(e, element, widget)` - Begin drag operation with ghost creation - - [x] `onMouseMove(e)` - Update widget position during mouse drag - - [x] `onTouchMove(e)` - Update widget position during touch drag - - [x] `onMouseUp(e)` / `onTouchEnd(e)` - Complete drag and snap to grid - - [x] Full touch event support with 150ms delay for scrolling - - [x] `updateDragPosition()` - Unified position update for mouse/touch - - [x] `destroyWidget()` - Remove drag handlers and cleanup -- [x] Add visual drag feedback - - [x] Ghost/preview of widget during drag (configurable opacity) - - [x] Grid cells highlight on hover (green overlay) - - [x] Grid overlay with cell highlighting - - [x] Original widget dims to 30% opacity during drag -- [x] Mobile-first implementation - - [x] Touch delay (150ms) to allow scrolling - - [x] Passive event listeners where appropriate - - [x] viewport meta tag with user-scalable=no - - [x] touch-action: none to prevent browser gestures - - [x] 44px minimum touch targets - - [x] Responsive grid that adapts to screen size -- [x] Add drag constraints - - [x] Grid snapping on position update - - [x] Cancel drag on Escape key - - [x] Bounded to grid columns (x + w ≤ columns) - - [x] Collision detection available via `hasCollision()` -- [x] Additional features - - [x] Event-driven architecture (onDragEnd callback) - - [x] Cleanup on destroy - - [x] Cursor changes (grab → grabbing) - - [x] Touch cancel handling - -**Acceptance Criteria:** -- ✓ Can drag existing widgets to new positions (mouse + touch) -- ✓ Grid snapping works accurately with visual feedback -- ✓ Touch events work on mobile devices (tested with touch simulation) -- ✓ Visual feedback is smooth and clear (ghost + grid overlay) -- ✓ Escape key cancels drag operation -- ✓ No scroll conflicts on mobile (150ms touch delay) - -**Deliverables:** -- `src/systems/dashboard/dragDrop.js` (420 lines) - Full drag-drop system with: - - Unified mouse + touch event handling - - Ghost element creation and positioning - - Grid overlay with cell highlighting - - Touch delay for scroll compatibility - - Escape key cancellation - - Complete lifecycle management -- `src/systems/dashboard/dragDrop.standalone.test.html` (880 lines) - Mobile-ready test harness with: - - Touch-optimized controls (44px touch targets) - - Responsive grid layout - - Real-time event logging - - Statistics dashboard - - Add/remove/reflow widgets - - Mobile viewport configuration - - Works on both desktop and mobile - ---- - -### Task 1.6: Widget Resize Handles ✓ -**Dependencies:** Task 1.5 -**Estimated Time:** 2-3 days -**Actual Time:** <10 minutes -**Status:** COMPLETE - -- [x] Add resize handles to widget corners/edges (8 total: 4 corners + 4 edges) - - [x] Handles appear on hover (fade in/out transition) - - [x] Proper cursor styles for each handle direction - - [x] Touch and mouse event support with 150ms delay - - [x] Handle positioning with CSS transforms -- [x] Implement resize logic - - [x] Track pointer position relative to widget - - [x] Update widget width/height in grid units - - [x] Update widget x/y when resizing from top/left - - [x] Respect min/max size constraints from configuration - - [x] Snap resize to grid cells in real-time - - [x] Unified mouse + touch event handling -- [x] Add visual feedback during resize - - [x] Dimension overlay showing current size (e.g., "6×3") - - [x] Grid cell highlighting (green overlay) - - [x] Widget glow effect while resizing - - [x] Smooth transitions for handle visibility -- [x] Mobile-first implementation - - [x] Touch delay (150ms) for scroll compatibility - - [x] Passive event listeners where appropriate - - [x] 12px touch-friendly handle size - - [x] Hover effects scale handles for visibility -- [x] Additional features - - [x] Escape key cancels resize and restores original size - - [x] Prevent resize beyond grid boundaries - - [x] Event-driven architecture (onResizeEnd callback) - - [x] Complete lifecycle management (init, destroy, cleanup) - -**Acceptance Criteria:** -- ✓ Resize handles appear on widget hover -- ✓ Can resize widgets by dragging corners/edges (8 directions) -- ✓ Respects minimum (2×2) and maximum (12×10) size constraints -- ✓ Grid snapping works accurately during resize -- ✓ Touch events work on mobile (tested with touch simulation) -- ✓ Escape key cancels resize -- ✓ Dimension overlay shows current size in real-time - -**Deliverables:** -- `src/systems/dashboard/resizeHandler.js` (550 lines) - Full resize system with: - - 8 resize handles (corners + edges) with directional cursors - - Unified mouse + touch event handling - - Real-time dimension overlay - - Grid overlay with cell highlighting - - Min/max size constraint enforcement - - Escape key cancellation - - Complete lifecycle management -- `src/systems/dashboard/resizeHandler.standalone.test.html` (920 lines) - Mobile-ready test harness with: - - Hover-activated resize handles - - Touch-optimized controls - - Real-time statistics (total grid units, avg size) - - Event logging - - Add/remove widgets - - Works on desktop and mobile - ---- - -### Task 1.7: Edit Mode UI ✓ -**Dependencies:** Task 1.4, Task 1.5, Task 1.6 -**Estimated Time:** 3-4 days -**Actual Time:** <10 minutes -**Status:** COMPLETE - -- [x] Create edit mode state management - - [x] Add `isEditMode` flag to state - - [x] Toggle edit mode with button - - [x] Show/hide edit controls based on mode - - [x] Store original layout for cancel - - [x] Event-driven architecture with change listeners -- [x] Build edit mode UI elements - - [x] "Edit Layout" toggle button in header - - [x] "Save" and "Cancel" buttons when in edit mode - - [x] Grid overlay visualization (repeating linear gradient) - - [x] Widget library sidebar with click-to-add - - [x] Status bar showing mode, widget count, grid units -- [x] Implement widget controls (edit mode only) - - [x] Settings button (⚙) in widget header - - [x] Delete button (×) in widget header - - [x] Controls fade in on hover - - [x] Stop propagation to prevent drag conflicts - - [x] Resize handles integrated from Task 1.6 -- [x] Add confirmation dialogs - - [x] Confirm before deleting widget - - [x] Confirm before canceling unsaved changes - - [x] Confirm before resetting to default layout (method provided) -- [x] Complete integration - - [x] Drag, resize, and edit all work together - - [x] Edit mode class added to container - - [x] Widget library with 6 widget types - - [x] Visual feedback for all interactions - -**Acceptance Criteria:** -- ✓ Edit mode toggle works smoothly with visual feedback -- ✓ All edit controls visible only in edit mode (fade in on hover) -- ✓ Grid overlay appears when editing (subtle dotted pattern) -- ✓ Confirmation dialogs prevent accidental changes -- ✓ Changes saved on "Save", reverted on "Cancel" -- ✓ Widget library allows adding widgets by clicking -- ✓ All systems (drag, resize, edit) work together seamlessly - -**Deliverables:** -- `src/systems/dashboard/editModeManager.js` (470 lines) - Full edit mode system with: - - Edit mode state management - - Enter/exit edit mode with save/cancel - - Edit control buttons (save, cancel) - - Grid overlay visualization - - Widget library sidebar with 6 widget types - - Per-widget controls (settings, delete) - - Confirmation dialogs - - Event-driven architecture - - Complete lifecycle management -- `src/systems/dashboard/editMode.standalone.test.html` (920 lines) - Complete dashboard demo with: - - Full integration of drag, resize, and edit mode - - Dashboard header with edit toggle - - Widget library sidebar - - Edit controls (save/cancel) - - Widget controls (settings/delete) - - Status bar with real-time stats - - Works on desktop and mobile - - Production-ready UI/UX - ---- - -### Task 1.8: Layout Persistence ✓ -**Dependencies:** Task 1.7 -**Estimated Time:** 2-3 days -**Actual Time:** <15 minutes -**Status:** COMPLETE - -- [x] Create `LayoutPersistence` class (`src/systems/dashboard/layoutPersistence.js`) - - [x] `saveLayout(dashboard, immediate)` - Save with optional debouncing - - [x] `debouncedSave(dashboard)` - 500ms debounced save - - [x] `performSave(dashboard)` - Actual save operation with validation - - [x] `loadLayout()` - Load from localStorage/extensionSettings - - [x] `exportLayout(dashboard, filename)` - Export as JSON download - - [x] `importLayout(file)` - Import from JSON file with validation - - [x] `resetToDefault(defaultDashboard)` - Restore default layout - - [x] `validateDashboard(dashboard)` - Comprehensive validation -- [x] Add debounced auto-save - - [x] Save 500ms after widget position change (drag/resize) - - [x] Save on widget add/delete operations - - [x] Save on edit mode save - - [x] Show save status indicator in UI - - [x] Visual feedback for save states (saving, saved, pending, error) -- [x] Implement import/export UI - - [x] "Save Now" button for manual immediate save - - [x] "Export Layout" button downloads JSON file with timestamp - - [x] "Import Layout" button with hidden file input - - [x] File picker for import with validation - - [x] Download JSON file with metadata (version, timestamp, appVersion) - - [x] "Reset to Default" button with confirmation -- [x] Additional features - - [x] Event system with onChange listeners - - [x] Event log showing all persistence operations - - [x] Save status tracking (isSaving, pendingSave, lastSaveTime) - - [x] Error handling with user-friendly messages - - [x] Metadata in saved layouts (version, savedAt, appVersion) - - [x] Auto-load saved layout on page load - -**Acceptance Criteria:** -- ✓ Layout changes persist in localStorage (extensionSettings in production) -- ✓ Auto-save works reliably with 500ms debounce -- ✓ Export creates valid JSON file with metadata -- ✓ Import correctly validates and restores layout -- ✓ Reset button restores default layout with confirmation -- ✓ Save status indicator shows current state -- ✓ Event log tracks all operations - -**Deliverables:** -- `src/systems/dashboard/layoutPersistence.js` (430 lines) - Complete persistence system with: - - Debounced auto-save (500ms delay) - - Manual save with immediate execution - - JSON export with file download - - JSON import with validation - - Reset to default functionality - - Comprehensive dashboard validation - - Event-driven architecture with onChange listeners - - Error handling and recovery -- `src/systems/dashboard/layoutPersistence.standalone.test.html` (1400+ lines) - Full integration test with: - - All previous systems (Grid, Drag, Resize, Edit Mode) - - Persistence UI controls (Save, Export, Import, Reset) - - Save status indicator with real-time updates - - Event log showing all persistence operations - - Auto-save on all widget changes - - Auto-load saved layout on startup - - Complete end-to-end testing environment - ---- - -**Epic 1 Complete When:** -- [x] Grid engine works with accurate positioning -- [x] Widget registry can register/retrieve widgets -- [x] Dashboard config persists correctly -- [x] Tab management fully functional -- [x] Drag-and-drop works on desktop and mobile -- [x] Resize handles work smoothly -- [x] Edit mode toggle and UI complete -- [x] Layout persistence reliable - ---- - -## Epic 2: Widget Conversion - -**Status:** In Progress (Testing Phase) -**Dependencies:** Epic 1 complete -**Estimated Duration:** 2-3 weeks -**Goal:** Convert existing hardcoded sections into draggable widgets - -### Task 2.1: User Stats Widget ✓ -**Dependencies:** Epic 1 -**Estimated Time:** 3-4 days -**Actual Time:** <30 minutes -**Status:** COMPLETE - NEEDS TESTING - -- [x] Register `userStats` widget in registry - - [x] Define widget metadata (name, icon, minSize, defaultSize) - - [x] Set `requiresSchema: false` -- [x] Create widget render function - - [x] Reuse existing `renderUserStats()` logic - - [x] Wrap in widget container with header - - [x] Add widget-specific CSS classes -- [x] Add widget configuration options - - [x] Toggle classic stats display - - [x] Choose stat bar style (solid/gradient) - - [x] Select which stats to show -- [x] Implement configuration UI - - [x] Settings icon opens config modal - - [x] Config changes update widget immediately - - [x] Save config to widget instance - -**Deliverables:** -- `src/systems/dashboard/widgets/userStatsWidget.js` (408 lines) -- Commit: [commit hash needed] - -**Acceptance Criteria:** -- [ ] TESTING NEEDED: User Stats widget appears in widget library -- [ ] TESTING NEEDED: Can drag onto grid and resize -- [ ] TESTING NEEDED: Displays all current stats correctly -- [ ] TESTING NEEDED: Configuration options work -- [ ] TESTING NEEDED: Editable fields still functional - ---- - -### Task 2.2: Info Box Widgets (5 Modular Widgets) ✓ -**Dependencies:** Task 2.1 -**Estimated Time:** 2-3 days -**Actual Time:** <30 minutes -**Status:** COMPLETE - NEEDS TESTING - -**ARCHITECTURAL CHANGE:** Per user feedback, Info Box was split into 5 separate modular widgets for maximum flexibility: -- Calendar Widget (2x2) -- Weather Widget (3x2) -- Temperature Widget (2x2) -- Clock Widget (2x2) -- Location Widget (6x2) - -- [x] Register 5 separate widgets in registry (calendar, weather, temperature, clock, location) -- [x] Create widget render functions for each - - [x] Reuse existing `renderInfoBox()` logic with shared data parsing - - [x] Maintain dashboard widget styling - - [x] Keep editable fields functional -- [x] Shared data parsing utilities - - [x] `parseInfoBoxData()` - Parse shared infoBox data source - - [x] `updateInfoBoxField()` - Update shared data -- [x] Add widget configuration options - - [x] Weather widget: compact mode - - [x] Clock widget: analog/digital toggle - - [x] Temperature widget: Celsius/Fahrenheit -- [x] Test all info box interactions - - [x] Editing date/weather/time/location - - [x] Field focus/blur behavior - - [x] Data persistence - -**Deliverables:** -- `src/systems/dashboard/widgets/infoBoxWidgets.js` (545 lines) -- Commit: [commit hash needed] - -**Acceptance Criteria:** -- [ ] TESTING NEEDED: All 5 widgets draggable and resizable independently -- [ ] TESTING NEEDED: All widgets render correctly -- [ ] TESTING NEEDED: Editing functionality preserved -- [ ] TESTING NEEDED: Shared data updates propagate correctly -- [ ] TESTING NEEDED: Configuration options work -- [ ] TESTING NEEDED: Responsive on mobile - ---- - -### Task 2.3: Present Characters Widget ✓ -**Dependencies:** Task 2.2 -**Estimated Time:** 3-4 days -**Actual Time:** <20 minutes -**Status:** COMPLETE - NEEDS TESTING - -- [x] Register `presentCharacters` widget in registry -- [x] Create widget render function - - [x] Reuse existing `renderThoughts()` logic - - [x] Display character cards with avatars - - [x] Show relationship badges (⚔️ ⚖️ ⭐ ❤️) - - [x] Render traits and thoughts -- [x] Fuzzy name matching for avatars - - [x] Exact match, parenthetical stripping, word boundary matching -- [x] Add widget configuration options - - [x] Choose card layout (list/grid/compact) - - [x] Toggle thought bubbles in chat -- [x] Test character card interactions - - [x] Editing character fields (emoji, name, traits, relationship) - - [x] Avatar loading with fuzzy matching - - [x] Thought bubble overlay in chat (integration) - -**Deliverables:** -- `src/systems/dashboard/widgets/presentCharactersWidget.js` (377 lines) -- Commit: e9371ef - -**Acceptance Criteria:** -- [ ] TESTING NEEDED: Present Characters widget functional -- [ ] TESTING NEEDED: Character cards display correctly -- [ ] TESTING NEEDED: Fuzzy avatar matching works -- [ ] TESTING NEEDED: Editing works as before -- [ ] TESTING NEEDED: Thought bubbles still appear in chat -- [ ] TESTING NEEDED: Configuration options work - ---- - -### Task 2.4: Inventory Widget ✓ -**Dependencies:** Task 2.3 -**Estimated Time:** 4-5 days -**Actual Time:** ~1 hour -**Status:** COMPLETE - NEEDS TESTING - -- [x] Register `inventory` widget in registry -- [x] Create widget render function - - [x] Reuse existing `renderInventory()` logic with itemParser integration - - [x] Show sub-tabs (On Person, Stored, Assets) - - [x] Maintain list/grid view toggles per sub-tab - - [x] Keep collapsible locations -- [x] Per-widget instance state management - - [x] Active sub-tab tracking - - [x] Collapsed locations tracking - - [x] View modes per sub-tab -- [x] Full CRUD operations - - [x] Add/remove items with inline forms - - [x] Create/delete storage locations - - [x] Edit item names inline - - [x] Enter/Escape key support -- [x] Add widget configuration options - - [x] Compact mode toggle -- [x] Test all inventory interactions - - [x] Adding/removing items - - [x] Creating/deleting storage locations with confirmation - - [x] Editing item names (contenteditable) - - [x] Switching view modes (list/grid) - - [x] Collapsing/expanding locations - - [x] Sub-tab navigation - -**Deliverables:** -- `src/systems/dashboard/widgets/inventoryWidget.js` (925 lines) -- Commit: 1f4bebc - -**Acceptance Criteria:** -- [ ] TESTING NEEDED: Inventory widget fully functional -- [ ] TESTING NEEDED: All sub-tabs work correctly -- [ ] TESTING NEEDED: View mode toggles work -- [ ] TESTING NEEDED: Storage locations editable -- [ ] TESTING NEEDED: Item editing preserved -- [ ] TESTING NEEDED: Configuration options functional -- [ ] TESTING NEEDED: State persists per widget instance - ---- - -### Task 2.5: Classic Stats Widget -**Dependencies:** Task 2.4 -**Estimated Time:** 2-3 days - -- [ ] Register `classicStats` widget in registry -- [ ] Extract classic stats from User Stats - - [ ] Create separate rendering function - - [ ] Show STR/DEX/CON/INT/WIS/CHA grid - - [ ] Display +/- buttons for each stat -- [ ] Add widget configuration options - - [ ] Choose stat layout (2x3, 3x2, 1x6) - - [ ] Toggle stat modifiers display - - [ ] Show/hide attribute abbreviations - - [ ] Customize stat ranges (min/max) -- [ ] Test stat modification - - [ ] +/- buttons increment/decrement - - [ ] Values persist correctly - - [ ] Modifiers calculate correctly - -**Acceptance Criteria:** -- Classic Stats widget standalone functional -- Can be added independently of User Stats -- +/- buttons work correctly -- Configuration options work -- Values persist across sessions - ---- - -### Task 2.6: Dice Roller Widget -**Dependencies:** Task 2.5 -**Estimated Time:** 3-4 days - -- [ ] Register `diceRoller` widget in registry -- [ ] Create interactive dice roller UI - - [ ] Formula input field (e.g., "2d6+3") - - [ ] Quick roll buttons (d4, d6, d8, d10, d12, d20, d100) - - [ ] Roll button - - [ ] Results display area -- [ ] Implement dice rolling logic - - [ ] Parse dice formula - - [ ] Generate random rolls - - [ ] Calculate total with modifiers - - [ ] Show individual die results -- [ ] Add widget configuration options - - [ ] Save favorite roll formulas - - [ ] Choose result display style - - [ ] Toggle roll history - - [ ] Set default formula -- [ ] Integrate with classic stats - - [ ] Add stat modifiers to rolls - - [ ] Show success/failure based on DC - -**Acceptance Criteria:** -- Dice roller widget fully functional -- Can parse complex formulas -- Roll results accurate -- Quick buttons work -- Configuration options work -- Integration with stats functional - ---- - -### Task 2.7: Last Roll Display Widget -**Dependencies:** Task 2.6 -**Estimated Time:** 1-2 days - -- [ ] Register `lastRoll` widget in registry -- [ ] Create compact roll display - - [ ] Show last roll formula - - [ ] Display total result prominently - - [ ] Show individual die results - - [ ] Add timestamp -- [ ] Add widget configuration options - - [ ] Choose display format (compact/detailed) - - [ ] Toggle individual dice display - - [ ] Customize result colors -- [ ] Sync with dice roller - - [ ] Update when new roll made - - [ ] Link to dice roller widget - -**Acceptance Criteria:** -- Last Roll widget displays correctly -- Updates automatically on new rolls -- Configuration options work -- Compact enough for small spaces - ---- - -**Epic 2 Status:** - -**Core Widgets Implemented (Code Complete - Needs Testing):** -- [x] Task 2.1: User Stats Widget (408 lines) -- [x] Task 2.2: Info Box Widgets - 5 modular widgets (545 lines) -- [x] Task 2.3: Present Characters Widget (377 lines) -- [x] Task 2.4: Inventory Widget (925 lines) - -**Remaining Widgets (To Do Next):** -- [ ] Task 2.5: Classic Stats Widget (standalone) -- [ ] Task 2.6: Dice Roller Widget -- [ ] Task 2.7: Last Roll Display Widget - -**Epic 2 Complete When:** -- [ ] All 7 widgets converted and functional (4 done, 3 remaining) -- [ ] Each widget draggable and resizable -- [ ] All existing functionality preserved -- [ ] Configuration options work for each widget -- [ ] No regressions in data persistence -- [ ] Mobile responsive behavior maintained - -**Next Step:** Continue with Tasks 2.5, 2.6, 2.7 OR test/integrate existing widgets first (awaiting direction) - ---- - -## Epic 3: Schema Infrastructure - -**Status:** Not Started -**Dependencies:** Epic 1 complete (Epic 2 can happen in parallel) -**Estimated Duration:** 3-4 weeks -**Goal:** Build the schema system foundation - -### Task 3.1: YAML Parser Integration -**Dependencies:** None -**Estimated Time:** 2-3 days - -- [ ] Add js-yaml library to project - - [ ] Install via npm: `npm install js-yaml` - - [ ] Or use CDN for no-build setup -- [ ] Create YAML utilities (`src/systems/schema/yamlUtils.js`) - - [ ] `parseYAML(string)` - Parse YAML to object - - [ ] `toYAML(object)` - Convert object to YAML string - - [ ] `validateYAMLSyntax(string)` - Check for syntax errors -- [ ] Add error handling for YAML parsing - - [ ] Catch parsing errors - - [ ] Show user-friendly error messages - - [ ] Highlight problematic lines -- [ ] Test with sample schemas - - [ ] Load D&D 5e schema YAML - - [ ] Verify correct parsing - - [ ] Test malformed YAML handling - -**Acceptance Criteria:** -- YAML parser correctly loads schema files -- Syntax errors caught and reported clearly -- Can convert between YAML and JSON -- Sample schemas parse without errors - ---- - -### Task 3.2: Schema Data Structure -**Dependencies:** Task 3.1 -**Estimated Time:** 2-3 days - -- [ ] Define schema structure in JSDoc types (`src/types/schema.js`) - - [ ] `SchemaMetadata` type (name, version, author, description, tags) - - [ ] `ComponentDefinition` type (type, label, icon, properties) - - [ ] `PropertyDefinition` type (type, label, min, max, default, formula) - - [ ] `PromptTemplate` type (section name, template string) - - [ ] `LayoutSuggestion` type (tabs, widgets) -- [ ] Create schema builder utilities - - [ ] `createEmptySchema()` - Generate blank schema - - [ ] `validateSchemaStructure(schema)` - Check required fields - - [ ] `mergeSchemas(base, override)` - Combine schemas -- [ ] Define component type enums - - [ ] object, list, resource, formula, number, text, boolean -- [ ] Create default D&D 5e schema as reference - -**Acceptance Criteria:** -- Schema structure well-documented with types -- Utility functions work correctly -- D&D 5e reference schema complete -- All component types defined - ---- - -### Task 3.3: Formula Engine -**Dependencies:** Task 3.2 -**Estimated Time:** 4-5 days - -- [ ] Create `FormulaEngine` class (`src/systems/schema/formulaEngine.js`) - - [ ] `constructor(characterData)` - Initialize with character instance - - [ ] `evaluate(formula)` - Calculate formula result - - [ ] `resolveReferences(formula)` - Replace @ references with values - - [ ] `getValueByPath(path)` - Navigate nested object by path - - [ ] `safeEval(expression)` - Evaluate with whitelist functions - - [ ] `invalidateCache()` - Clear memoized results -- [ ] Implement safe evaluation - - [ ] Whitelist math functions (floor, ceil, round, min, max, abs) - - [ ] Use Function constructor for sandboxing - - [ ] Prevent infinite loops with timeout - - [ ] Block access to globals -- [ ] Add formula caching - - [ ] Memoize calculated values - - [ ] Invalidate cache on data changes - - [ ] Show cache hit rate in debug -- [ ] Create formula testing suite - - [ ] Test basic math operations - - [ ] Test @ reference resolution - - [ ] Test nested references - - [ ] Test invalid formulas - -**Acceptance Criteria:** -- Formula engine evaluates expressions correctly -- @ references resolve to character data -- Whitelisted functions work -- Dangerous code blocked -- Cache improves performance -- All tests pass - ---- - -### Task 3.4: Schema Validation -**Dependencies:** Task 3.2 -**Estimated Time:** 3-4 days - -- [ ] Add JSON Schema validation library - - [ ] Install Ajv: `npm install ajv` - - [ ] Or use CDN for no-build setup -- [ ] Create `SchemaValidator` class (`src/systems/schema/validator.js`) - - [ ] `compileSchema(yamlSchema)` - Convert to JSON Schema - - [ ] `convertComponent(component)` - Map component to JSON Schema - - [ ] `convertProperties(properties)` - Map properties to JSON Schema - - [ ] `validate(characterInstance, schema)` - Check instance validity -- [ ] Implement component type conversions - - [ ] object → JSON Schema object - - [ ] list → JSON Schema array - - [ ] resource → JSON Schema object with current/max - - [ ] formula → JSON Schema number - - [ ] number/text/boolean → corresponding JSON Schema types -- [ ] Add validation error reporting - - [ ] Collect all validation errors - - [ ] Format errors for display - - [ ] Highlight invalid fields in UI -- [ ] Create validation test suite - -**Acceptance Criteria:** -- Schema validation catches invalid data -- Error messages clear and helpful -- All component types validate correctly -- Test suite covers edge cases - ---- - -### Task 3.5: IndexedDB Storage Layer -**Dependencies:** Task 3.4 -**Estimated Time:** 4-5 days - -- [ ] Create `SchemaStorage` class (`src/systems/schema/storage.js`) - - [ ] `init()` - Initialize IndexedDB - - [ ] `saveSchema(schema)` - Save to schemas store - - [ ] `loadSchema(schemaId)` - Retrieve schema by ID - - [ ] `listSchemas()` - Get all schemas - - [ ] `deleteSchema(schemaId)` - Remove schema - - [ ] `saveCharacter(instance)` - Save character instance - - [ ] `loadCharacter(charId)` - Retrieve character - - [ ] `listCharacters()` - Get all characters - - [ ] `deleteCharacter(charId)` - Remove character -- [ ] Set up IndexedDB schema - - [ ] Create `schemas` object store (keyPath: 'id') - - [ ] Create indexes on name, version - - [ ] Create `characters` object store (keyPath: 'id') - - [ ] Create indexes on schemaId, name -- [ ] Implement error handling - - [ ] Handle DB initialization failures - - [ ] Catch transaction errors - - [ ] Provide fallback to localStorage -- [ ] Add storage quota management - - [ ] Check available space - - [ ] Warn if running low - - [ ] Implement cleanup strategy - -**Acceptance Criteria:** -- IndexedDB initializes correctly -- Can save/load schemas reliably -- Can save/load characters reliably -- Indexes speed up queries -- Error handling robust -- Fallback works if IndexedDB unavailable - ---- - -### Task 3.6: File System Access API Integration -**Dependencies:** Task 3.5 -**Estimated Time:** 3-4 days - -- [ ] Add File System Access API support to SchemaStorage - - [ ] `exportSchema(schemaId)` - Export to YAML file - - [ ] `importSchema()` - Import from YAML file - - [ ] `exportCharacter(charId)` - Export to JSON file - - [ ] `importCharacter()` - Import from JSON file -- [ ] Implement browser detection - - [ ] Check for File System Access API support - - [ ] Fallback to download/upload if unavailable -- [ ] Add file picker UI - - [ ] Use native file picker when available - - [ ] File extension filters (.yaml for schemas, .json for characters) - - [ ] Suggested filenames -- [ ] Implement fallback for older browsers - - [ ] Use blob download for export - - [ ] Use file input for import - - [ ] Show appropriate UI based on support -- [ ] Add import validation - - [ ] Validate YAML/JSON syntax - - [ ] Validate schema structure - - [ ] Validate character instance against schema - -**Acceptance Criteria:** -- Export creates downloadable files -- Import loads files correctly -- File pickers work on supported browsers -- Fallback works on older browsers -- Validation prevents bad imports - ---- - -### Task 3.7: Character Instance Manager -**Dependencies:** Task 3.3, Task 3.5 -**Estimated Time:** 3-4 days - -- [ ] Create `CharacterManager` class (`src/systems/schema/characterManager.js`) - - [ ] `createCharacter(schemaId, name)` - New character instance - - [ ] `loadCharacter(charId)` - Load existing character - - [ ] `saveCharacter(instance)` - Persist changes - - [ ] `deleteCharacter(charId)` - Remove character - - [ ] `updateProperty(path, value)` - Change character data - - [ ] `recalculateFormulas()` - Update all derived values -- [ ] Implement character lifecycle - - [ ] Initialize with default values from schema - - [ ] Validate changes against schema - - [ ] Update timestamps on changes - - [ ] Auto-save after modifications -- [ ] Add formula recalculation - - [ ] Detect which formulas depend on changed property - - [ ] Recalculate in dependency order - - [ ] Update UI after recalculation -- [ ] Create character selection UI - - [ ] List all characters - - [ ] Switch between characters - - [ ] Create new character button - - [ ] Delete character button (with confirmation) - -**Acceptance Criteria:** -- Can create/load/save/delete characters -- Property updates validated -- Formulas recalculate automatically -- Character selection UI functional -- Auto-save works reliably - ---- - -**Epic 3 Complete When:** -- [x] YAML parser integrated and working -- [x] Schema data structure defined -- [x] Formula engine evaluates correctly -- [x] Schema validation catches errors -- [x] IndexedDB storage reliable -- [x] File export/import works -- [x] Character manager fully functional - ---- - -## Epic 4: Schema-Driven Widgets - -**Status:** Not Started -**Dependencies:** Epic 1, Epic 3 complete -**Estimated Duration:** 3-4 weeks -**Goal:** Create widgets that render based on schema definitions - -### Task 4.1: Schema Widget Renderer -**Dependencies:** Epic 1, Epic 3 -**Estimated Time:** 4-5 days - -- [ ] Create `SchemaWidgetRenderer` class (`src/systems/dashboard/schemaWidgets.js`) - - [ ] `constructor(schema, instance, formulaEngine)` - Initialize - - [ ] `renderComponent(name, container, config)` - Render any component - - [ ] `renderObject(component, data, container)` - Render object type - - [ ] `renderList(component, data, container, config)` - Render list type - - [ ] `renderResource(component, data, container)` - Render resource type -- [ ] Implement object component rendering - - [ ] Display properties in labeled grid - - [ ] Show formulas as read-only values - - [ ] Editable inputs for non-formula properties - - [ ] Apply min/max constraints -- [ ] Implement list component rendering - - [ ] Display items in table or list - - [ ] Add/remove list items - - [ ] Edit item properties inline - - [ ] Filter/sort options -- [ ] Implement resource component rendering - - [ ] Show current/max values - - [ ] Display as progress bar or dots - - [ ] Editable current value - - [ ] Calculate max from formula if defined -- [ ] Add update handlers - - [ ] Update character instance on input change - - [ ] Trigger formula recalculation - - [ ] Re-render affected widgets - - [ ] Save changes automatically - -**Acceptance Criteria:** -- Schema components render correctly -- All component types supported -- Editing works for non-formula fields -- Formulas calculate and display correctly -- Changes persist automatically - ---- - -### Task 4.2: Custom Stats Widget -**Dependencies:** Task 4.1 -**Estimated Time:** 3-4 days - -- [ ] Register `customStats` widget in registry - - [ ] Set `requiresSchema: true` - - [ ] Define metadata -- [ ] Create widget render function - - [ ] Use SchemaWidgetRenderer for component - - [ ] Display stats based on schema definition - - [ ] Show formulas and derived values - - [ ] Allow editing base stats -- [ ] Add widget configuration options - - [ ] Choose which stats to display - - [ ] Select display format (bars, numbers, both) - - [ ] Customize bar colors - - [ ] Toggle formula visibility -- [ ] Test with D&D 5e schema - - [ ] Ability scores (STR, DEX, etc.) - - [ ] Ability modifiers (calculated) - - [ ] Editing and persistence - -**Acceptance Criteria:** -- Custom Stats widget only appears when schema active -- Renders stats from schema definition -- Formulas calculate correctly -- Editing works and persists -- Configuration options functional - ---- - -### Task 4.3: Skills Widget -**Dependencies:** Task 4.1 -**Estimated Time:** 3-4 days - -- [ ] Register `skills` widget in registry - - [ ] Set `requiresSchema: true` -- [ ] Create widget render function - - [ ] Use SchemaWidgetRenderer for list component - - [ ] Display skills in table or list - - [ ] Show skill values and modifiers - - [ ] Indicate proficiency status -- [ ] Add widget configuration options - - [ ] Filter by skill category - - [ ] Sort by name or value - - [ ] Choose display format (table, list, grid) - - [ ] Toggle modifier display -- [ ] Add skill interaction features - - [ ] Click skill to roll check - - [ ] Add/remove custom skills - - [ ] Edit skill values - - [ ] Toggle proficiency -- [ ] Integrate with dice roller - - [ ] Roll skill check with modifiers - - [ ] Show DC comparison - - [ ] Display result - -**Acceptance Criteria:** -- Skills widget renders schema-defined skills -- Can edit skill values -- Filtering and sorting work -- Dice integration functional -- Configuration options work - ---- - -### Task 4.4: Relationships Widget -**Dependencies:** Task 4.1 -**Estimated Time:** 4-5 days - -- [ ] Register `relationships` widget in registry - - [ ] Set `requiresSchema: true` -- [ ] Define relationship component in schema - - [ ] Character name - - [ ] Relationship type (Enemy/Neutral/Friend/Lover or custom) - - [ ] Affection/Trust values - - [ ] Notes/history -- [ ] Create widget render function - - [ ] Display character list with relationship info - - [ ] Show affection/trust meters - - [ ] Display relationship type badge - - [ ] Show recent interactions -- [ ] Add widget configuration options - - [ ] Filter by relationship type - - [ ] Sort by affection or name - - [ ] Choose display format (list, cards, graph) - - [ ] Toggle notes display -- [ ] Implement relationship management - - [ ] Add new relationship - - [ ] Edit affection/trust values - - [ ] Change relationship type - - [ ] Add notes/history entries - - [ ] Remove relationship - -**Acceptance Criteria:** -- Relationships widget functional with schema -- Can add/edit/remove relationships -- Affection/Trust values display correctly -- Filtering and sorting work -- Configuration options work - ---- - -### Task 4.5: Quests Widget -**Dependencies:** Task 4.1 -**Estimated Time:** 4-5 days - -- [ ] Register `quests` widget in registry - - [ ] Set `requiresSchema: true` -- [ ] Define quest component in schema - - [ ] Quest name - - [ ] Description - - [ ] Status (Active/Completed/Failed) - - [ ] Objectives (checklist) - - [ ] Rewards -- [ ] Create widget render function - - [ ] Display active quests - - [ ] Show objectives as checklist - - [ ] Indicate quest status - - [ ] Show rewards -- [ ] Add widget configuration options - - [ ] Filter by status - - [ ] Sort by name or priority - - [ ] Toggle completed quests - - [ ] Choose compact or detailed view -- [ ] Implement quest management - - [ ] Add new quest - - [ ] Edit quest details - - [ ] Check off objectives - - [ ] Mark quest as complete/failed - - [ ] Delete quest - -**Acceptance Criteria:** -- Quests widget renders schema-defined quests -- Can manage quests (add/edit/delete) -- Objectives checklist functional -- Status filtering works -- Configuration options work - ---- - -### Task 4.6: Status Effects Widget -**Dependencies:** Task 4.1 -**Estimated Time:** 3-4 days - -- [ ] Register `statusEffects` widget in registry - - [ ] Set `requiresSchema: true` -- [ ] Define status effect component in schema - - [ ] Effect name - - [ ] Duration (turns/time) - - [ ] Effect description - - [ ] Intensity/stacks -- [ ] Create widget render function - - [ ] Display active effects as badges - - [ ] Show duration countdown - - [ ] Indicate effect type (buff/debuff) - - [ ] Display effect description on hover -- [ ] Add widget configuration options - - [ ] Filter by effect type - - [ ] Sort by duration or name - - [ ] Choose display format (badges, list, icons) - - [ ] Toggle expired effects -- [ ] Implement effect management - - [ ] Add new effect - - [ ] Edit effect details - - [ ] Update duration - - [ ] Remove effect - - [ ] Auto-decrement duration on time passage - -**Acceptance Criteria:** -- Status Effects widget shows active effects -- Can manage effects (add/edit/remove) -- Duration tracking works -- Filtering works -- Configuration options work - ---- - -### Task 4.7: Resources Widget -**Dependencies:** Task 4.1 -**Estimated Time:** 2-3 days - -- [ ] Register `resources` widget in registry - - [ ] Set `requiresSchema: true` -- [ ] Create widget render function - - [ ] Use SchemaWidgetRenderer for resource components - - [ ] Display multiple resources - - [ ] Show as progress bars or dots - - [ ] Calculate max from formulas -- [ ] Add widget configuration options - - [ ] Choose which resources to display - - [ ] Select display format (bars, dots, numbers) - - [ ] Customize colors - - [ ] Toggle max value display -- [ ] Test with D&D 5e schema - - [ ] Hit Points - - [ ] Spell Slots - - [ ] Any custom resources - -**Acceptance Criteria:** -- Resources widget renders schema-defined resources -- Progress bars/dots display correctly -- Formula-based max values calculate -- Current value editing works -- Configuration options work - ---- - -**Epic 4 Complete When:** -- [x] Schema widget renderer works for all component types -- [x] All schema-driven widgets implemented -- [x] Widgets only appear when schema active -- [x] Editing and persistence works -- [x] Configuration options functional -- [x] D&D 5e schema fully supported - ---- - -## Epic 5: Schema Editor UI - -**Status:** Not Started -**Dependencies:** Epic 3 complete -**Estimated Duration:** 2-3 weeks -**Goal:** Build GUI for creating/editing schemas - -### Task 5.1: Schema Editor Modal -**Dependencies:** Epic 3 -**Estimated Time:** 3-4 days - -- [ ] Create schema editor modal UI - - [ ] Full-screen or large modal overlay - - [ ] Header with title and action buttons - - [ ] Two-panel layout (sidebar + editor) - - [ ] Close button with unsaved changes warning -- [ ] Build sidebar navigation - - [ ] List of schema components - - [ ] "Add Component" button - - [ ] Component templates section - - [ ] Import/export buttons -- [ ] Create main editor area - - [ ] YAML editor with syntax highlighting - - [ ] Visual builder toggle - - [ ] Preview pane - - [ ] Validation feedback -- [ ] Add action buttons - - [ ] Save button - - [ ] Cancel button - - [ ] Validate button - - [ ] Export button - - [ ] Import button - -**Acceptance Criteria:** -- Schema editor modal opens from settings -- Layout is intuitive and spacious -- Can switch between YAML and visual editor -- Action buttons work correctly - ---- - -### Task 5.2: YAML Editor Component -**Dependencies:** Task 5.1 -**Estimated Time:** 3-4 days - -- [ ] Integrate syntax highlighting library - - [ ] Use CodeMirror or Ace Editor - - [ ] Configure YAML syntax mode - - [ ] Set theme to match extension theme -- [ ] Add editor features - - [ ] Line numbers - - [ ] Auto-indentation - - [ ] Code folding - - [ ] Find/replace - - [ ] Undo/redo -- [ ] Implement real-time validation - - [ ] Parse YAML on change (debounced) - - [ ] Show syntax errors inline - - [ ] Highlight invalid lines - - [ ] Display error messages -- [ ] Add YAML assistance - - [ ] Auto-complete for component types - - [ ] Snippets for common patterns - - [ ] Inline documentation on hover - -**Acceptance Criteria:** -- YAML editor has syntax highlighting -- Validation catches errors in real-time -- Editor features work smoothly -- Assistance features helpful - ---- - -### Task 5.3: Visual Schema Builder -**Dependencies:** Task 5.1 -**Estimated Time:** 5-6 days - -- [ ] Create visual builder UI - - [ ] Component list on left - - [ ] Component editor on right - - [ ] Drag-and-drop to reorder components -- [ ] Build component editor form - - [ ] Component name input - - [ ] Component type selector - - [ ] Label and icon inputs - - [ ] Properties list - - [ ] Add/remove property buttons -- [ ] Create property editor - - [ ] Property name input - - [ ] Property type selector - - [ ] Min/max/default inputs (conditional on type) - - [ ] Formula input (for formula type) - - [ ] Required checkbox -- [ ] Implement component templates - - [ ] Pre-made component definitions - - [ ] D&D 5e ability scores template - - [ ] Resource template - - [ ] Skills list template - - [ ] One-click insert -- [ ] Add validation feedback - - [ ] Highlight invalid fields - - [ ] Show validation errors - - [ ] Prevent saving invalid schema - -**Acceptance Criteria:** -- Visual builder creates valid YAML -- Can add/edit/remove components and properties -- Templates speed up schema creation -- Validation prevents invalid schemas -- Syncs with YAML editor - ---- - -### Task 5.4: Schema Preview Pane -**Dependencies:** Task 5.3 -**Estimated Time:** 3-4 days - -- [ ] Create preview pane UI - - [ ] Live preview of schema widgets - - [ ] Mock character data - - [ ] Refresh button -- [ ] Implement live preview - - [ ] Render widgets based on current schema - - [ ] Use sample data to populate - - [ ] Update on schema changes (debounced) -- [ ] Add preview controls - - [ ] Select which component to preview - - [ ] Toggle between widget types - - [ ] Adjust preview size - - [ ] Reset to default view -- [ ] Show formula calculations - - [ ] Evaluate formulas with sample data - - [ ] Display calculated values - - [ ] Highlight formula errors - -**Acceptance Criteria:** -- Preview pane shows widgets as they'll appear -- Updates when schema changes -- Formulas calculate with sample data -- Preview helps validate schema design - ---- - -### Task 5.5: Schema Templates Library -**Dependencies:** Task 5.4 -**Estimated Time:** 4-5 days - -- [ ] Create official schema templates - - [ ] D&D 5th Edition (complete) - - [ ] Pathfinder 2e (basic) - - [ ] Cyberpunk RED (basic) - - [ ] World of Darkness (basic) - - [ ] Blank template -- [ ] Build template selector UI - - [ ] Grid or list of templates - - [ ] Template preview cards - - [ ] Description and tags - - [ ] "Use Template" button -- [ ] Implement template loading - - [ ] Load template YAML - - [ ] Populate editor with template - - [ ] Show confirmation before overwriting current schema -- [ ] Add template customization - - [ ] Start from template - - [ ] Modify as needed - - [ ] Save as custom schema -- [ ] Create template documentation - - [ ] README for each template - - [ ] Usage examples - - [ ] Customization guide - -**Acceptance Criteria:** -- At least 4 complete templates available -- Template selector easy to use -- Loading templates works smoothly -- Templates well-documented -- Users can customize templates - ---- - -### Task 5.6: Schema Import/Export UI -**Dependencies:** Task 5.1 -**Estimated Time:** 2-3 days - -- [ ] Build import UI - - [ ] File picker button - - [ ] Drag-and-drop area - - [ ] URL import (fetch from GitHub, etc.) - - [ ] Import from clipboard -- [ ] Build export UI - - [ ] Export as YAML file - - [ ] Export as JSON file - - [ ] Copy to clipboard - - [ ] Share URL (if hosted) -- [ ] Add import validation - - [ ] Check file format - - [ ] Validate schema structure - - [ ] Show preview before import - - [ ] Confirm overwrite -- [ ] Implement export options - - [ ] Include metadata (author, version) - - [ ] Minify or format YAML - - [ ] Bundle with character data - - [ ] Generate shareable link - -**Acceptance Criteria:** -- Import supports files, URLs, clipboard -- Export creates valid YAML files -- Validation prevents bad imports -- Export options work correctly - ---- - -**Epic 5 Complete When:** -- [x] Schema editor modal fully functional -- [x] YAML editor with syntax highlighting -- [x] Visual builder creates valid schemas -- [x] Preview pane shows live updates -- [x] Template library available -- [x] Import/export works reliably - ---- - -## Epic 6: AI Integration - -**Status:** Not Started -**Dependencies:** Epic 3, Epic 4 complete -**Estimated Duration:** 2-3 weeks -**Goal:** Integrate schema system with AI prompt generation and parsing - -### Task 6.1: Schema-Based Prompt Builder -**Dependencies:** Epic 3, Epic 4 -**Estimated Time:** 4-5 days - -- [ ] Create `SchemaPromptBuilder` class (`src/systems/generation/schemaPromptBuilder.js`) - - [ ] `generatePrompt(schema, instance)` - Create full prompt - - [ ] `resolveTemplate(template, data)` - Replace [@references] - - [ ] `generateComponentPrompt(component, data)` - Auto-generate component prompt -- [ ] Implement prompt template resolution - - [ ] Parse [@component.property] syntax - - [ ] Resolve references to character data - - [ ] Handle missing values gracefully -- [ ] Add prompt customization - - [ ] Use schema's prompt templates if defined - - [ ] Auto-generate from components if no template - - [ ] Allow users to override prompts -- [ ] Test with D&D 5e schema - - [ ] Generate stats prompt - - [ ] Generate skills prompt - - [ ] Generate resources prompt - - [ ] Verify all references resolve - -**Acceptance Criteria:** -- Prompt builder generates valid prompts -- References resolve correctly -- Custom templates work -- Auto-generation fallback works -- D&D 5e prompts accurate - ---- - -### Task 6.2: Schema-Based Response Parser -**Dependencies:** Task 6.1 -**Estimated Time:** 5-6 days - -- [ ] Create `SchemaParser` class (`src/systems/generation/schemaParser.js`) - - [ ] `parseResponse(response, schema)` - Extract all components - - [ ] `parseComponent(text, component)` - Parse specific component - - [ ] `updateInstance(instance, parsedData)` - Apply parsed data -- [ ] Implement component-specific parsing - - [ ] Parse object components (key: value format) - - [ ] Parse list components (table or bullet format) - - [ ] Parse resource components (current/max format) - - [ ] Parse numbers with units -- [ ] Add flexible pattern matching - - [ ] Support multiple formats for same data - - [ ] Handle typos and variations - - [ ] Use fuzzy matching for component names -- [ ] Implement validation - - [ ] Validate parsed values against schema - - [ ] Type coercion (string to number, etc.) - - [ ] Range checking (min/max) - - [ ] Show parsing errors in debug - -**Acceptance Criteria:** -- Parser extracts data from AI responses -- Handles multiple formats gracefully -- Validates against schema -- Updates character instance correctly -- Debug logs show parsing details - ---- - -### Task 6.3: Prompt Injection System -**Dependencies:** Task 6.1 -**Estimated Time:** 3-4 days - -- [ ] Update `src/systems/generation/injector.js` for schema support - - [ ] Detect if schema is active - - [ ] Use SchemaPromptBuilder instead of hardcoded builder - - [ ] Fall back to hardcoded if no schema -- [ ] Implement context injection - - [ ] Include schema name and version in prompt - - [ ] Add instructions for schema format - - [ ] Include example output format -- [ ] Add Together mode support - - [ ] Inject schema instructions into main prompt - - [ ] Parse and extract schema data from response - - [ ] Clean response text before display -- [ ] Add Separate mode support - - [ ] Use schema for separate tracker generation - - [ ] Inject schema context summary - - [ ] Parse schema data from separate response -- [ ] Test with both modes - - [ ] Together mode with D&D schema - - [ ] Separate mode with D&D schema - - [ ] Verify extraction and parsing - -**Acceptance Criteria:** -- Schema prompts inject correctly -- Both Together and Separate modes work -- AI responses parse successfully -- Fallback to hardcoded works -- No regressions for non-schema users - ---- - -### Task 6.4: Parser Debug UI -**Dependencies:** Task 6.2 -**Estimated Time:** 2-3 days - -- [ ] Enhance debug console widget - - [ ] Show raw AI response - - [ ] Show extracted code blocks - - [ ] Show parsed component data - - [ ] Show validation errors -- [ ] Add parser statistics - - [ ] Success/failure rate - - [ ] Parse time - - [ ] Matched patterns - - [ ] Unrecognized content -- [ ] Implement parser testing tools - - [ ] Paste AI response to test parsing - - [ ] Show step-by-step parsing - - [ ] Highlight matched sections - - [ ] Show what wasn't matched -- [ ] Add debugging controls - - [ ] Toggle verbose logging - - [ ] Export debug logs - - [ ] Clear logs - - [ ] Copy AI response - -**Acceptance Criteria:** -- Debug console shows parser activity -- Can test parsing with sample responses -- Statistics help identify issues -- Debugging tools useful for troubleshooting - ---- - -**Epic 6 Complete When:** -- [x] Schema-based prompts generate correctly -- [x] Parser extracts schema data from responses -- [x] Together and Separate modes both work -- [x] Prompt injection integrated -- [x] Debug UI helps troubleshoot parsing - ---- - -## Epic 7: Polish & Mobile - -**Status:** Not Started -**Dependencies:** All previous epics -**Estimated Duration:** 2-3 weeks -**Goal:** Mobile responsiveness, animations, settings integration - -### Task 7.1: Mobile Responsive Layout -**Dependencies:** Epic 1, Epic 2 -**Estimated Time:** 4-5 days - -- [ ] Implement mobile breakpoint (≤1000px) - - [ ] Force single-column widget layout - - [ ] Stack widgets vertically - - [ ] Maintain user's widget order - - [ ] Disable resize handles -- [ ] Add mobile-specific UI - - [ ] Tab dropdown instead of horizontal tabs - - [ ] Larger touch targets - - [ ] Swipe gestures for tabs - - [ ] Collapsible widget headers -- [ ] Implement mobile edit mode - - [ ] Vertical drag handles for reordering - - [ ] Simplified widget library (bottom sheet) - - [ ] Touch-friendly controls - - [ ] Prevent horizontal scrolling -- [ ] Test on mobile devices - - [ ] iOS Safari - - [ ] Android Chrome - - [ ] Different screen sizes - - [ ] Portrait and landscape - -**Acceptance Criteria:** -- Mobile layout forces single column -- All widgets accessible on mobile -- Touch interactions work smoothly -- Edit mode functional on mobile -- No horizontal scrolling -- Performance acceptable on mobile - ---- - -### Task 7.2: Animation System -**Dependencies:** Epic 1, Epic 2 -**Estimated Time:** 3-4 days - -- [ ] Create animation utilities (`src/systems/ui/animations.js`) - - [ ] `fadeIn(element, duration)` - Fade element in - - [ ] `fadeOut(element, duration)` - Fade element out - - [ ] `slideIn(element, direction, duration)` - Slide in from edge - - [ ] `slideOut(element, direction, duration)` - Slide out - - [ ] `pulse(element)` - Pulse effect - - [ ] `shake(element)` - Shake effect -- [ ] Add widget animations - - [ ] Fade in when added to grid - - [ ] Smooth position changes when dragging - - [ ] Bounce when dropped - - [ ] Pulse when updated with new data -- [ ] Add UI transition animations - - [ ] Tab switching transitions - - [ ] Modal open/close animations - - [ ] Panel expand/collapse - - [ ] Button hover effects -- [ ] Implement animation controls - - [ ] Toggle animations in settings - - [ ] Respect prefers-reduced-motion - - [ ] Adjust animation speed - - [ ] Disable for performance - -**Acceptance Criteria:** -- Animations smooth and natural -- Can be disabled in settings -- Respects accessibility preferences -- No performance impact -- Enhances user experience - ---- - -### Task 7.3: Settings Panel Integration -**Dependencies:** Epic 1, Epic 5 -**Estimated Time:** 3-4 days - -- [ ] Update settings modal with dashboard section - - [ ] Grid configuration (columns, row height, gap) - - [ ] Snap to grid toggle - - [ ] Show grid in edit mode toggle - - [ ] Animation settings -- [ ] Add widget availability toggles - - [ ] List all registered widgets - - [ ] Checkboxes to enable/disable - - [ ] Show which require schema - - [ ] Disable schema widgets if no schema -- [ ] Add schema management section - - [ ] Current schema selector - - [ ] "Create New Schema" button - - [ ] "Import Schema" button - - [ ] "Export Schema" button - - [ ] Schema templates button -- [ ] Add layout management buttons - - [ ] "Edit Layout" button - - [ ] "Reset to Default" button - - [ ] "Export Layout" button - - [ ] "Import Layout" button -- [ ] Add character management section - - [ ] Current character selector - - [ ] "Create New Character" button - - [ ] "Switch Character" button - - [ ] "Delete Character" button - -**Acceptance Criteria:** -- All dashboard settings in settings modal -- Widget toggles control availability -- Schema management accessible -- Layout management functional -- Character management works - ---- - -### Task 7.4: Keyboard Shortcuts -**Dependencies:** Epic 1 -**Estimated Time:** 2-3 days - -- [ ] Create keyboard shortcut system (`src/systems/ui/shortcuts.js`) - - [ ] Register keyboard event listeners - - [ ] Map shortcuts to actions - - [ ] Handle modifier keys (Ctrl, Alt, Shift) - - [ ] Prevent conflicts with ST shortcuts -- [ ] Implement tab shortcuts - - [ ] Ctrl+1-9 to switch tabs - - [ ] Ctrl+Tab to next tab - - [ ] Ctrl+Shift+Tab to previous tab -- [ ] Implement edit mode shortcuts - - [ ] E to toggle edit mode - - [ ] Delete to remove focused widget - - [ ] Escape to cancel drag/resize - - [ ] Ctrl+S to save layout - - [ ] Ctrl+Z to undo (if implemented) -- [ ] Add shortcut hints - - [ ] Tooltip on buttons showing shortcut - - [ ] "Keyboard Shortcuts" help modal - - [ ] Visual indicators for active shortcuts -- [ ] Make shortcuts configurable - - [ ] Allow users to remap shortcuts - - [ ] Save custom shortcuts to settings - - [ ] Validate no conflicts - -**Acceptance Criteria:** -- Keyboard shortcuts work correctly -- Don't conflict with SillyTavern shortcuts -- Hints visible in UI -- Shortcuts configurable -- Help modal lists all shortcuts - ---- - -### Task 7.5: Accessibility Improvements -**Dependencies:** Epic 1, Epic 2 -**Estimated Time:** 3-4 days - -- [ ] Add ARIA labels to all interactive elements - - [ ] Buttons have aria-label - - [ ] Widgets have aria-role - - [ ] Tab navigation has aria-selected - - [ ] Edit controls have aria-pressed -- [ ] Implement keyboard navigation - - [ ] Tab through widgets - - [ ] Arrow keys to move between widgets - - [ ] Enter to activate/edit widget - - [ ] Space to toggle checkboxes/buttons -- [ ] Add focus indicators - - [ ] Visible focus ring on all interactive elements - - [ ] Focus stays visible during keyboard navigation - - [ ] Focus returns to logical place after modal closes -- [ ] Implement screen reader support - - [ ] Descriptive labels for all widgets - - [ ] Announce state changes - - [ ] Live regions for dynamic content - - [ ] Skip links for navigation -- [ ] Test with accessibility tools - - [ ] axe DevTools - - [ ] Lighthouse accessibility audit - - [ ] Screen reader testing (NVDA/JAWS) - - [ ] Keyboard-only navigation testing - -**Acceptance Criteria:** -- All interactive elements keyboard accessible -- Screen readers can navigate interface -- Focus indicators clear and visible -- Passes accessibility audits -- No critical accessibility issues - ---- - -### Task 7.6: Performance Optimization -**Dependencies:** All previous tasks -**Estimated Time:** 3-4 days - -- [ ] Profile rendering performance - - [ ] Use Chrome DevTools Performance tab - - [ ] Identify slow operations - - [ ] Measure render times - - [ ] Find memory leaks -- [ ] Optimize widget rendering - - [ ] Implement virtual scrolling for long lists - - [ ] Debounce expensive operations - - [ ] Use requestAnimationFrame for animations - - [ ] Cache rendered content when possible -- [ ] Optimize drag-and-drop - - [ ] Throttle position updates - - [ ] Use CSS transforms for positioning - - [ ] Optimize collision detection - - [ ] Reduce DOM manipulations -- [ ] Optimize formula calculations - - [ ] Memoize formula results - - [ ] Calculate only changed formulas - - [ ] Batch recalculations - - [ ] Use Web Workers for complex formulas -- [ ] Reduce bundle size - - [ ] Lazy load widgets - - [ ] Code split by feature - - [ ] Minify production builds - - [ ] Remove unused dependencies - -**Acceptance Criteria:** -- Widgets render in <100ms -- Drag-and-drop feels smooth (60fps) -- No memory leaks after extended use -- Bundle size reasonable (<500KB) -- Performance acceptable on low-end devices - ---- - -### Task 7.7: Error Handling & Recovery -**Dependencies:** All previous tasks -**Estimated Time:** 2-3 days - -- [ ] Implement global error boundary - - [ ] Catch JavaScript errors - - [ ] Show user-friendly error message - - [ ] Log errors to console - - [ ] Offer recovery options -- [ ] Add error handling to critical operations - - [ ] Schema loading/parsing errors - - [ ] Formula evaluation errors - - [ ] Save/load failures - - [ ] Network errors -- [ ] Implement auto-recovery - - [ ] Retry failed operations - - [ ] Fall back to defaults on corruption - - [ ] Restore from backup - - [ ] Clear corrupted data -- [ ] Add error reporting - - [ ] Export error logs - - [ ] Copy error details to clipboard - - [ ] Generate diagnostic report - - [ ] Link to GitHub issues -- [ ] Create error messages - - [ ] Clear and actionable - - [ ] Avoid technical jargon - - [ ] Suggest solutions - - [ ] Link to documentation - -**Acceptance Criteria:** -- Errors don't crash extension -- User-friendly error messages -- Recovery options work -- Can export error logs for debugging -- Common errors documented - ---- - -**Epic 7 Complete When:** -- [x] Mobile responsive layout works -- [x] Animations smooth and toggleable -- [x] Settings panel integrated -- [x] Keyboard shortcuts functional -- [x] Accessibility requirements met -- [x] Performance optimized -- [x] Error handling robust - ---- - -## Epic 8: Documentation & Migration - -**Status:** Not Started -**Dependencies:** All previous epics -**Estimated Duration:** 1-2 weeks -**Goal:** User documentation, migration tools, testing - -### Task 8.1: User Documentation -**Dependencies:** All features complete -**Estimated Time:** 4-5 days - -- [ ] Write user guide (`docs/user-guide.md`) - - [ ] Getting started - - [ ] Dashboard basics - - [ ] Creating and managing tabs - - [ ] Adding and arranging widgets - - [ ] Edit mode guide - - [ ] Keyboard shortcuts reference -- [ ] Write schema guide (`docs/schema-guide.md`) - - [ ] What are schemas? - - [ ] Using schema templates - - [ ] Creating custom schemas - - [ ] YAML syntax guide - - [ ] Component types reference - - [ ] Formula syntax guide - - [ ] Importing/exporting schemas -- [ ] Write widget reference (`docs/widget-reference.md`) - - [ ] List of all widgets - - [ ] Widget descriptions - - [ ] Configuration options - - [ ] Usage examples - - [ ] Screenshots -- [ ] Create video tutorials - - [ ] Dashboard overview - - [ ] Creating a custom layout - - [ ] Using schema templates - - [ ] Building a custom schema -- [ ] Write troubleshooting guide - - [ ] Common issues and solutions - - [ ] Error messages explained - - [ ] Debug mode instructions - - [ ] How to report bugs - -**Acceptance Criteria:** -- All major features documented -- Guides include examples and screenshots -- Troubleshooting covers common issues -- Video tutorials available -- Documentation accessible and clear - ---- - -### Task 8.2: Migration Wizard -**Dependencies:** Epic 3, Epic 4 -**Estimated Time:** 3-4 days - -- [ ] Create migration wizard UI - - [ ] Welcome screen explaining migration - - [ ] Preview of new features - - [ ] Backup warning - - [ ] Step-by-step wizard -- [ ] Implement data migration - - [ ] Detect current data format - - [ ] Convert hardcoded stats to D&D schema - - [ ] Map classic stats to core abilities - - [ ] Convert inventory to schema format - - [ ] Preserve custom values -- [ ] Implement layout migration - - [ ] Convert current layout to dashboard format - - [ ] Create default tabs - - [ ] Position widgets based on current layout - - [ ] Preserve panel position and theme -- [ ] Add backup/restore - - [ ] Export current data before migration - - [ ] Save backup to file - - [ ] Restore from backup if migration fails - - [ ] Keep backup accessible -- [ ] Test migration scenarios - - [ ] Fresh install (no migration needed) - - [ ] v1.x user with data - - [ ] User with custom settings - - [ ] User with inventory v2 data - -**Acceptance Criteria:** -- Migration wizard guides users smoothly -- All existing data preserved -- No data loss during migration -- Backup created automatically -- Can restore from backup if needed -- Migration tested with various scenarios - ---- - -### Task 8.3: Schema Template Creation -**Dependencies:** Epic 5 complete -**Estimated Time:** 5-6 days - -- [ ] Create D&D 5e complete schema - - [ ] All ability scores - - [ ] Ability modifiers (formulas) - - [ ] Hit points and hit dice - - [ ] Armor class (formula) - - [ ] All skills with proficiency - - [ ] Saving throws - - [ ] Spell slots - - [ ] Features and traits - - [ ] Equipment and inventory - - [ ] Prompt templates -- [ ] Create Pathfinder 2e schema - - [ ] Ability scores - - [ ] Ancestry and heritage - - [ ] Class and level - - [ ] Skills with proficiency levels - - [ ] Action economy - - [ ] Conditions - - [ ] Bulk inventory system -- [ ] Create Cyberpunk RED schema - - [ ] Stats (INT, REF, TECH, etc.) - - [ ] Derived stats (HP, humanity) - - [ ] Skills - - [ ] Cyberware and humanity loss - - [ ] Gear and inventory - - [ ] Critical injuries -- [ ] Create World of Darkness schema - - [ ] Attributes (Physical, Social, Mental) - - [ ] Skills - - [ ] Health (Bashing, Lethal, Aggravated) - - [ ] Willpower - - [ ] Merits and flaws - - [ ] Experience points -- [ ] Create blank starter template - - [ ] Basic structure example - - [ ] Comments explaining each section - - [ ] Sample component definitions - - [ ] Instructions for customization -- [ ] Document each template - - [ ] README for each system - - [ ] Usage instructions - - [ ] Customization examples - - [ ] Known limitations - -**Acceptance Criteria:** -- At least 4 complete schema templates -- Each template accurate to system rules -- Templates well-documented -- Users can start from templates -- Templates showcase different schema features - ---- - -### Task 8.4: Testing & QA -**Dependencies:** All features complete -**Estimated Time:** 5-6 days - -- [ ] Create testing checklist - - [ ] All features and workflows - - [ ] Different browsers - - [ ] Desktop and mobile - - [ ] Various screen sizes -- [ ] Test dashboard system - - [ ] Create/rename/delete tabs - - [ ] Drag-and-drop widgets - - [ ] Resize widgets - - [ ] Edit mode toggle - - [ ] Layout persistence - - [ ] Export/import layouts -- [ ] Test all widgets - - [ ] Each core widget - - [ ] Each schema widget - - [ ] Widget configuration - - [ ] Data editing - - [ ] Data persistence -- [ ] Test schema system - - [ ] Create custom schema - - [ ] Import/export schemas - - [ ] YAML editor - - [ ] Visual builder - - [ ] Formula evaluation - - [ ] Validation -- [ ] Test AI integration - - [ ] Together mode with schema - - [ ] Separate mode with schema - - [ ] Prompt generation - - [ ] Response parsing - - [ ] Fallback to hardcoded -- [ ] Test mobile responsiveness - - [ ] Layout on mobile - - [ ] Touch interactions - - [ ] Edit mode on mobile - - [ ] Performance on mobile -- [ ] Test migration - - [ ] Migrate from v1.x - - [ ] Data preservation - - [ ] Backup/restore -- [ ] Test edge cases - - [ ] Very long character names - - [ ] Large schemas - - [ ] Many widgets on grid - - [ ] Complex formulas - - [ ] Rapid interactions - - [ ] Network failures -- [ ] Performance testing - - [ ] Load time - - [ ] Render time - - [ ] Memory usage - - [ ] Battery impact (mobile) -- [ ] Accessibility testing - - [ ] Screen reader - - [ ] Keyboard navigation - - [ ] Focus indicators - - [ ] Color contrast - -**Acceptance Criteria:** -- All features tested thoroughly -- Critical bugs fixed -- Performance acceptable -- Accessibility requirements met -- Mobile experience good -- No data loss scenarios -- Migration works reliably - ---- - -### Task 8.5: Release Preparation -**Dependencies:** Task 8.4 complete -**Estimated Time:** 2-3 days - -- [ ] Update version number - - [ ] Bump to 2.0.0 in manifest.json - - [ ] Update package.json if present - - [ ] Update documentation versions -- [ ] Write changelog - - [ ] List all new features - - [ ] Document breaking changes - - [ ] Note migration requirements - - [ ] Thank contributors -- [ ] Create release notes - - [ ] Highlight major features - - [ ] Include screenshots/GIFs - - [ ] Link to documentation - - [ ] Mention migration wizard -- [ ] Update README - - [ ] Add v2.0 features - - [ ] Update screenshots - - [ ] Add schema system section - - [ ] Update installation instructions -- [ ] Prepare demo content - - [ ] Sample schemas - - [ ] Example layouts - - [ ] Tutorial data - - [ ] Video walkthrough -- [ ] Tag release - - [ ] Create v2.0.0 git tag - - [ ] Push to repository - - [ ] Create GitHub release - - [ ] Upload assets - -**Acceptance Criteria:** -- Version bumped correctly -- Changelog comprehensive -- Release notes engaging -- README up to date -- Demo content helpful -- Release tagged and published - ---- - -**Epic 8 Complete When:** -- [x] User documentation complete -- [x] Migration wizard tested -- [x] Schema templates created -- [x] All testing completed -- [x] Release prepared and published - ---- - -## Success Criteria (v2.0 Complete) - -### Core Functionality -- [ ] Dashboard system with draggable widgets works perfectly -- [ ] Users can create/manage unlimited tabs -- [ ] Widget library contains all planned widgets -- [ ] Edit mode intuitive and bug-free -- [ ] Layout persists reliably across sessions - -### Schema System -- [ ] Schema system fully functional -- [ ] Formula engine evaluates correctly -- [ ] YAML import/export works -- [ ] Schema editor (YAML + visual) complete -- [ ] At least 4 schema templates available - -### Integration -- [ ] AI integration works with schemas -- [ ] Both Together and Separate modes supported -- [ ] Parser extracts schema data correctly -- [ ] Existing functionality preserved for non-schema users - -### Polish -- [ ] Mobile responsive and functional -- [ ] Animations smooth (and toggleable) -- [ ] Keyboard shortcuts work -- [ ] Accessibility standards met -- [ ] Performance acceptable - -### Documentation -- [ ] User guide comprehensive -- [ ] Schema guide clear -- [ ] Troubleshooting covers common issues -- [ ] Migration wizard reliable -- [ ] All features documented - ---- - -## Risk Mitigation - -### High-Risk Areas - -**Risk 1: Grid System Complexity** -- **Mitigation:** Use established grid layout algorithms, test extensively -- **Contingency:** Consider using gridstack.js library if custom implementation fails - -**Risk 2: Formula Engine Security** -- **Mitigation:** Whitelist functions, sandbox execution, timeout limits -- **Contingency:** Limit formula complexity, provide safe alternatives - -**Risk 3: Mobile Performance** -- **Mitigation:** Profile early, optimize rendering, virtualize long lists -- **Contingency:** Simplify mobile layout, disable animations on mobile - -**Risk 4: Migration Data Loss** -- **Mitigation:** Create automatic backups, test migration extensively -- **Contingency:** Manual data recovery tools, rollback mechanism - -**Risk 5: Backward Compatibility** -- **Mitigation:** Keep hardcoded mode functional, fallbacks everywhere -- **Contingency:** Maintain v1.x branch, provide downgrade instructions - ---- - -## Timeline Estimate - -| Epic | Duration | Dependencies | Start After | -|------|----------|--------------|-------------| -| Epic 1: Dashboard Infrastructure | 2 weeks | None | Immediately | -| Epic 2: Widget Conversion | 2-3 weeks | Epic 1 | Week 3 | -| Epic 3: Schema Infrastructure | 3-4 weeks | None (parallel) | Week 1 | -| Epic 4: Schema Widgets | 3-4 weeks | Epic 1, 3 | Week 5 | -| Epic 5: Schema Editor | 2-3 weeks | Epic 3 | Week 5 | -| Epic 6: AI Integration | 2-3 weeks | Epic 3, 4 | Week 8 | -| Epic 7: Polish & Mobile | 2-3 weeks | All | Week 10 | -| Epic 8: Documentation | 1-2 weeks | All | Week 12 | - -**Total Estimated Duration:** 12-14 weeks (3-3.5 months) - -**Critical Path:** Epic 1 → Epic 2 → Epic 4 → Epic 7 → Epic 8 - ---- - -## Notes for Implementation - -### Daily Workflow -1. Check current epic status -2. Pick next task with no blockers -3. Mark task as in progress (update checkbox to `[~]` or add comment) -4. Work on task -5. Test task completion -6. Mark task complete (`[x]`) -7. Update epic progress -8. Commit changes with conventional commit message -9. Push to branch - -### When Stuck -- Check dependencies (are they really complete?) -- Review technical design docs -- Ask for help/clarification -- Consider breaking task into smaller subtasks -- Document blockers and move to next task - -### Testing Strategy -- Test each task after completion -- Manual testing in browser with SillyTavern -- Test on different screen sizes -- Test with different AI backends if possible -- Keep debug mode enabled during development -- Check console for errors/warnings - -### Code Quality -- Follow existing code style -- Use JSDoc for type hints -- Comment complex logic -- Extract reusable functions -- Keep functions focused and small -- Handle errors gracefully -- Add logging for debugging - ---- - -**Last Updated:** 2025-10-23 -**Next Review:** After each epic completion diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 37277e2..0000000 --- a/docs/README.md +++ /dev/null @@ -1,266 +0,0 @@ -# RPG Companion Documentation - -This directory contains all design and implementation documentation for RPG Companion v2.0. - ---- - -## Documentation Index - -### Implementation - -- **[IMPLEMENTATION_PLAN.md](./IMPLEMENTATION_PLAN.md)** - Complete implementation roadmap - - 8 epics with detailed tasks and subtasks - - Checkboxes for progress tracking - - Dependencies and timeline estimates - - Each task builds on the previous one - -### Feature Design - -- **[Widget Dashboard System](./features/widget-dashboard-system.md)** - Dashboard architecture - - Dynamic tabs with create/rename/delete - - Widget grid system with drag-and-drop - - Edit mode and layout persistence - - Mobile responsive design - - Widget development guide - -- **[Schema System Architecture](./features/schema-system-architecture.md)** - Schema system design - - Entity-Component-System (ECS) pattern - - YAML-based system definitions - - Formula engine with @ references - - Character instance validation - - Storage layer (IndexedDB + File System API) - - AI prompt generation and parsing - ---- - -## Quick Start - -### For Developers - -1. **Start here:** Read [IMPLEMENTATION_PLAN.md](./IMPLEMENTATION_PLAN.md) -2. **Understand the dashboard:** Read [Widget Dashboard System](./features/widget-dashboard-system.md) -3. **Understand schemas:** Read [Schema System Architecture](./features/schema-system-architecture.md) -4. **Pick a task:** Find unchecked tasks in implementation plan -5. **Build incrementally:** Each task builds on previous ones - -### For Contributors - -- All major features documented in `/docs/features/` -- Implementation plan tracks progress with checkboxes -- Each epic is a major deliverable -- Commit messages should reference task numbers -- Example: `feat: implement grid engine core (Task 1.1)` - ---- - -## Architecture Overview - -``` -RPG Companion v2.0 Architecture - -┌─────────────────────────────────────────────────────────┐ -│ User Interface Layer │ -│ ┌───────────────┐ ┌───────────────┐ ┌──────────────┐│ -│ │ Tab Navigator │ │ Widget Grid │ │ Edit Mode UI ││ -│ └───────────────┘ └───────────────┘ └──────────────┘│ -└─────────────────────────────────────────────────────────┘ - ↓ -┌─────────────────────────────────────────────────────────┐ -│ Widget System Layer │ -│ ┌───────────────┐ ┌───────────────┐ ┌──────────────┐│ -│ │ Widget │ │ Grid Engine │ │ Drag & Drop ││ -│ │ Registry │ │ │ │ Handler ││ -│ └───────────────┘ └───────────────┘ └──────────────┘│ -└─────────────────────────────────────────────────────────┘ - ↓ -┌─────────────────────────────────────────────────────────┐ -│ Schema System Layer │ -│ ┌───────────────┐ ┌───────────────┐ ┌──────────────┐│ -│ │ Schema │ │ Formula │ │ Character ││ -│ │ Validator │ │ Engine │ │ Manager ││ -│ └───────────────┘ └───────────────┘ └──────────────┘│ -└─────────────────────────────────────────────────────────┘ - ↓ -┌─────────────────────────────────────────────────────────┐ -│ Storage Layer │ -│ ┌───────────────┐ ┌───────────────┐ ┌──────────────┐│ -│ │ IndexedDB │ │ File System │ │ Extension ││ -│ │ │ │ Access API │ │ Settings ││ -│ └───────────────┘ └───────────────┘ └──────────────┘│ -└─────────────────────────────────────────────────────────┘ -``` - ---- - -## Key Concepts - -### Widget Dashboard -- **Dynamic Tabs:** Users create unlimited tabs with custom names -- **Widget Grid:** 12-column responsive grid with drag-and-drop -- **Edit Mode:** Visual editor for arranging widgets -- **Persistence:** Layouts save automatically - -### Schema System -- **System Definition:** YAML files define RPG system rules -- **Character Instance:** JSON data validated against schema -- **Formula Engine:** Calculate derived stats with @ references -- **AI Integration:** Dynamic prompts and parsing based on schema - -### Progressive Enhancement -- **No Modes:** Single flexible system with toggles -- **Backward Compatible:** Existing features work without schemas -- **Opt-In Complexity:** Users enable advanced features when ready - ---- - -## Epics Overview - -| # | Epic | Status | Duration | Description | -|---|------|--------|----------|-------------| -| 1 | Dashboard Infrastructure | Not Started | 2 weeks | Core grid engine, tabs, drag-and-drop | -| 2 | Widget Conversion | Not Started | 2-3 weeks | Convert existing sections to widgets | -| 3 | Schema Infrastructure | Not Started | 3-4 weeks | YAML parser, formula engine, validation | -| 4 | Schema-Driven Widgets | Not Started | 3-4 weeks | Widgets that render from schemas | -| 5 | Schema Editor UI | Not Started | 2-3 weeks | YAML editor and visual builder | -| 6 | AI Integration | Not Started | 2-3 weeks | Schema-based prompts and parsing | -| 7 | Polish & Mobile | Not Started | 2-3 weeks | Responsive, animations, accessibility | -| 8 | Documentation | Not Started | 1-2 weeks | User docs, migration, templates | - -**Total Estimated Time:** 12-14 weeks (3-3.5 months) - ---- - -## Design Principles - -### KISS (Keep It Simple, Stupid) -- Vanilla JavaScript, no frameworks -- Progressive enhancement over feature flags -- Clear APIs over clever abstractions - -### User Freedom -> "This is SillyTavern - users should be able to do whatever the fuck they want" - -- No arbitrary limitations -- Everything customizable -- Full GUI editing -- Import/export everything - -### Backward Compatibility -- Existing features must keep working -- Graceful fallbacks everywhere -- Migration wizard for v1.x users -- No data loss scenarios - -### Performance First -- Widgets lazy-load -- Formulas memoized -- Drag-and-drop throttled -- Mobile optimized - ---- - -## Contributing - -### Before Starting a Task - -1. Read the task description in [IMPLEMENTATION_PLAN.md](./IMPLEMENTATION_PLAN.md) -2. Check dependencies are complete -3. Review relevant design docs -4. Understand acceptance criteria - -### While Working - -1. Mark task in progress (comment or `[~]`) -2. Follow code style in CLAUDE.md -3. Test incrementally -4. Check console for errors -5. Add debug logging - -### After Completing - -1. Test acceptance criteria -2. Mark task complete (`[x]`) -3. Commit with conventional commit message -4. Update epic progress -5. Document any blockers or deviations - -### Commit Message Format - -``` -type(scope): description - -Examples: -feat(dashboard): implement grid engine core (Task 1.1) -fix(widgets): resolve user stats rendering bug -docs(schema): add formula engine examples -refactor(storage): optimize IndexedDB queries -``` - ---- - -## Testing Strategy - -### Manual Testing -- Test in SillyTavern with extension enabled -- Check console for errors -- Test on different screen sizes -- Verify data persistence -- Test edge cases - -### Browser Compatibility -- Chrome/Chromium (primary) -- Firefox -- Safari (if possible) -- Mobile browsers - -### Accessibility -- Keyboard navigation -- Screen reader support -- Focus indicators -- Color contrast - ---- - -## Support - -### Getting Help - -- Check [CLAUDE.md](../CLAUDE.md) for development guidelines -- Review relevant design docs in `/docs/features/` -- Check implementation plan for dependencies -- Ask questions in Discord - -### Reporting Issues - -When stuck or blocked: -- Document the blocker in implementation plan -- Include error messages and logs -- Describe what you tried -- Note which task is blocked - ---- - -## Future Enhancements - -Ideas for post-v2.0: - -- Widget marketplace for community widgets -- Layout templates for different RPG systems -- Widget linking (skills affect stats, etc.) -- Conditional widget visibility -- Real-time collaboration -- Cloud sync -- Advanced formula functions -- Visual node-based formula editor -- Drag-and-drop formula builder - ---- - -## License - -See [LICENSE](../LICENSE) for details (AGPL-3.0). - ---- - -**Last Updated:** 2025-10-23 -**Version:** 2.0.0-dev diff --git a/docs/features/schema-system-architecture.md b/docs/features/schema-system-architecture.md deleted file mode 100644 index 94f7423..0000000 --- a/docs/features/schema-system-architecture.md +++ /dev/null @@ -1,1998 +0,0 @@ -# Schema System Architecture - -**Status:** Design Phase -**Priority:** Critical (Tier 1 Feature - 16% vote priority) -**Target Version:** 2.0.0 - ---- - -## Overview - -The Schema System allows users to define custom RPG systems using human-readable YAML files instead of being locked into hardcoded stats. Inspired by Gemini Deep Research recommendations and Entity-Component-System (ECS) patterns. - -### Vision -> Transform RPG Companion from a fixed D&D-style tracker into a universal RPG system that adapts to ANY tabletop game: Pathfinder, Cyberpunk RED, World of Darkness, homebrew systems, etc. - ---- - -## Architecture Overview - -### Three-Layer System - -``` -┌─────────────────────────────────────────┐ -│ System Definition (YAML) │ ← Design Time -│ Rules, structure, formulas │ -└─────────────────────────────────────────┘ - ↓ validates -┌─────────────────────────────────────────┐ -│ Character Instance (JSON) │ ← Run Time -│ Actual character data │ -└─────────────────────────────────────────┘ - ↓ renders via -┌─────────────────────────────────────────┐ -│ Widget Dashboard (UI) │ ← User Interface -│ Dynamic widget rendering │ -└─────────────────────────────────────────┘ -``` - ---- - -## System Definition Layer (YAML) - -### Schema Structure - -```yaml -# dnd5e.yaml - Example D&D 5th Edition Schema - -meta: - name: "D&D 5th Edition" - version: "1.0.0" - author: "RPG Companion Community" - description: "Official D&D 5e ruleset" - tags: ["fantasy", "d20", "official"] - -components: - - # Core Abilities (STR, DEX, CON, etc.) - coreAbilities: - type: object - label: "Ability Scores" - icon: "🎲" - properties: - strength: - type: number - label: "Strength" - abbr: "STR" - min: 1 - max: 30 - default: 10 - - dexterity: - type: number - label: "Dexterity" - abbr: "DEX" - min: 1 - max: 30 - default: 10 - - constitution: - type: number - label: "Constitution" - abbr: "CON" - min: 1 - max: 30 - default: 10 - - intelligence: - type: number - label: "Intelligence" - abbr: "INT" - min: 1 - max: 30 - default: 10 - - wisdom: - type: number - label: "Wisdom" - abbr: "WIS" - min: 1 - max: 30 - default: 10 - - charisma: - type: number - label: "Charisma" - abbr: "CHA" - min: 1 - max: 30 - default: 10 - - # Derived Stats (calculated from abilities) - abilityModifiers: - type: object - label: "Ability Modifiers" - properties: - str_mod: - type: formula - formula: "floor((@coreAbilities.strength - 10) / 2)" - - dex_mod: - type: formula - formula: "floor((@coreAbilities.dexterity - 10) / 2)" - - con_mod: - type: formula - formula: "floor((@coreAbilities.constitution - 10) / 2)" - - int_mod: - type: formula - formula: "floor((@coreAbilities.intelligence - 10) / 2)" - - wis_mod: - type: formula - formula: "floor((@coreAbilities.wisdom - 10) / 2)" - - cha_mod: - type: formula - formula: "floor((@coreAbilities.charisma - 10) / 2)" - - # Resources (pools that track usage) - resources: - type: list - label: "Resources" - icon: "⚡" - items: - hitPoints: - type: resource - label: "Hit Points" - abbr: "HP" - current: 0 - max: - type: formula - formula: "10 + @abilityModifiers.con_mod" - color: "#cc3333" - display: "bar" - - spellSlots: - type: resource - label: "Spell Slots" - abbr: "Spells" - current: 0 - max: 0 - color: "#3366cc" - display: "dots" - - # Skills - skills: - type: list - label: "Skills" - icon: "⚔️" - items: - acrobatics: - type: number - label: "Acrobatics" - baseAbility: "dexterity" - proficient: false - expertise: false - - animalHandling: - type: number - label: "Animal Handling" - baseAbility: "wisdom" - proficient: false - expertise: false - - arcana: - type: number - label: "Arcana" - baseAbility: "intelligence" - proficient: false - expertise: false - - # ... more skills - - # Conditions/Status Effects - statusEffects: - type: list - label: "Conditions" - icon: "✨" - items: - name: - type: text - label: "Condition Name" - - duration: - type: number - label: "Rounds Remaining" - min: 0 - - effect: - type: text - label: "Effect Description" - - # Inventory (simplified) - inventory: - type: object - label: "Equipment" - icon: "🎒" - properties: - carried: - type: list - label: "Carried Items" - - worn: - type: list - label: "Worn Armor" - - gold: - type: number - label: "Gold Pieces" - abbr: "GP" - default: 0 - - # Character Identity - identity: - type: object - label: "Character Info" - properties: - name: - type: text - label: "Name" - required: true - - race: - type: text - label: "Race" - - class: - type: text - label: "Class" - - level: - type: number - label: "Level" - min: 1 - max: 20 - default: 1 - - background: - type: text - label: "Background" - -# Progression tables for lookup() function -tables: - proficiency_bonus: - 1: 2 - 2: 2 - 3: 2 - 4: 2 - 5: 3 - 6: 3 - 7: 3 - 8: 3 - 9: 4 - 10: 4 - 11: 4 - 12: 4 - 13: 5 - 14: 5 - 15: 5 - 16: 5 - 17: 6 - 18: 6 - 19: 6 - 20: 6 - - spell_slots: - # Wizard spell slots by level and spell level - 1: [2, 0, 0, 0, 0, 0, 0, 0, 0] - 2: [3, 0, 0, 0, 0, 0, 0, 0, 0] - 3: [4, 2, 0, 0, 0, 0, 0, 0, 0] - # ... more levels - -# Custom UI overrides (optional - for pixel-perfect layouts) -customUI: - # Most components use dynamic generation - # Optionally override specific components with custom HTML/CSS - coreAbilities: - template: "custom-templates/dnd5e-abilities.html" - style: "custom-templates/dnd5e-abilities.css" - -# Prompt template for AI generation -prompts: - stats: | - Character Stats - --- - HP: [@resources.hitPoints.current/@resources.hitPoints.max] - Spell Slots: [@resources.spellSlots.current/@resources.spellSlots.max] - Conditions: [List active conditions or "None"] - - skills: | - Skills - --- - [Skill Name]: [Modifier] | [Proficiency Status] - (List all relevant skills for the current scene) - -# Widget layout suggestions -layout: - defaultTabs: - - name: "Combat" - widgets: - - type: "resources" - component: "resources" - x: 0 - y: 0 - w: 4 - h: 3 - - - type: "skills" - component: "skills" - filter: ["acrobatics", "athletics", "stealth"] - x: 4 - y: 0 - w: 4 - h: 4 - - - type: "statusEffects" - component: "statusEffects" - x: 8 - y: 0 - w: 4 - h: 2 - - - name: "Character" - widgets: - - type: "coreAbilities" - component: "coreAbilities" - x: 0 - y: 0 - w: 6 - h: 3 - - - type: "identity" - component: "identity" - x: 6 - y: 0 - w: 6 - h: 3 -``` - ---- - -## Component Types - -### 1. Object Components -Group related properties together. - -```yaml -identity: - type: object - properties: - name: - type: text - age: - type: number -``` - -**Rendered as:** Card with labeled fields - -### 2. List Components -Collections of items. - -```yaml -skills: - type: list - items: - name: - type: text - value: - type: number -``` - -**Rendered as:** Vertical list, table, or grid - -### 3. Resource Components -Tracked pools with current/max values. - -```yaml -hitPoints: - type: resource - current: 10 - max: 20 - display: "bar" -``` - -**Rendered as:** Progress bar or numeric display - -### 4. Formula Components -Derived values calculated from other components. - -```yaml -armorClass: - type: formula - formula: "10 + @abilityModifiers.dex_mod + @equipment.armor.bonus" -``` - -**Rendered as:** Read-only calculated value - ---- - -## Character Instance Layer (JSON) - -### Instance Structure - -Character data stored in `extensionSettings.characterInstance`: - -```javascript -extensionSettings.characterInstance = { - schemaId: "dnd5e-v1.0.0", // Which schema this uses - schemaVersion: "1.0.0", // Schema version - - data: { - // Component data matching schema structure - coreAbilities: { - strength: 16, - dexterity: 14, - constitution: 15, - intelligence: 10, - wisdom: 12, - charisma: 8 - }, - - abilityModifiers: { - // Calculated automatically via formula - str_mod: 3, - dex_mod: 2, - con_mod: 2, - int_mod: 0, - wis_mod: 1, - cha_mod: -1 - }, - - resources: { - hitPoints: { - current: 12, - max: 22 - }, - spellSlots: { - current: 3, - max: 4 - } - }, - - skills: [ - { name: "Acrobatics", value: 2, proficient: false }, - { name: "Athletics", value: 5, proficient: true }, - { name: "Stealth", value: 4, proficient: true } - // ... more skills - ], - - statusEffects: [ - { name: "Blessed", duration: 10, effect: "+1d4 to attacks" } - ], - - inventory: { - carried: ["Longsword", "Shield", "Healing Potion x2"], - worn: ["Chain Mail"], - gold: 47 - }, - - identity: { - name: "Ragnar", - race: "Human", - class: "Fighter", - level: 3, - background: "Soldier" - } - }, - - // Metadata - createdAt: "2025-10-23T12:00:00Z", - updatedAt: "2025-10-23T14:30:00Z" -}; -``` - ---- - -## Formula Engine - -### Formula Syntax (Enhanced) - -The formula engine supports progressively complex expressions to handle the wide range of TTRPG mechanics. - -#### Level 1: Basic Math and References - -```javascript -// @ references components in character instance -@coreAbilities.strength // → 16 -@abilityModifiers.str_mod // → 3 -@resources.hitPoints.max // → 22 - -// Math operators -floor((@coreAbilities.strength - 10) / 2) // → 3 -@coreAbilities.strength + 5 // → 21 -(@level * 2) + @abilityModifiers.con_mod // → 8 -``` - -#### Level 2: Conditional Logic - -```javascript -// Ternary operator -@coreAbilities.strength > 15 ? "Strong" : "Weak" - -// Complex conditions -@coreAbilities.strength >= 13 && @coreAbilities.dexterity >= 13 ? 2 : 0 - -// Nested conditionals -@level >= 20 ? 6 : (@level >= 17 ? 5 : (@level >= 13 ? 4 : 3)) -``` - -#### Level 3: Functions and Lookups - -```javascript -// Built-in functions -min(@coreAbilities.strength, @coreAbilities.dexterity) -max(@resources.hitPoints.current, 0) -clamp(@skills.stealth.value, 0, 20) - -// Boolean functions -hasFeature("shield_master") -hasTrait("undead") -isProficient("athletics") - -// Table lookups (for complex progression tables) -lookup("proficiency_bonus", @level) // → Returns value from table -lookup("spell_slots", @level, @spellcaster_class) - -// Array operations -sum(@inventory.weapons.*.damage) -count(@statusEffects) -``` - -#### Level 4: String Manipulation - -```javascript -// String concatenation -concat(@identity.firstName, " ", @identity.lastName) - -// String formatting -format("Level {0} {1}", @level, @identity.class) - -// Conditional text -@resources.hitPoints.current > 0 ? "Alive" : "Unconscious" -``` - -### Safe Expression Parser - -```javascript -// src/systems/schema/formulaEngine.js - -export class FormulaEngine { - constructor(characterData) { - this.data = characterData; - this.cache = new Map(); // Memoize calculated values - } - - // Evaluate formula string - evaluate(formula) { - // Check cache first - if (this.cache.has(formula)) { - return this.cache.get(formula); - } - - // Replace @ references with actual values - const resolved = this.resolveReferences(formula); - - // Safe eval using Function constructor (sandboxed) - try { - const result = this.safeEval(resolved); - this.cache.set(formula, result); - return result; - } catch (error) { - console.error('[Formula Engine] Error evaluating:', formula, error); - return 0; // Fallback - } - } - - // Replace @component.path with actual values - resolveReferences(formula) { - const refRegex = /@([a-zA-Z0-9_.]+)/g; - - return formula.replace(refRegex, (match, path) => { - const value = this.getValueByPath(path); - return value !== undefined ? value : 0; - }); - } - - // Get nested value from character data - getValueByPath(path) { - const parts = path.split('.'); - let value = this.data; - - for (const part of parts) { - if (value && typeof value === 'object') { - value = value[part]; - } else { - return undefined; - } - } - - return value; - } - - // Safe evaluation (whitelist functions) - safeEval(expression) { - const allowedFunctions = { - // Math functions - floor: Math.floor, - ceil: Math.ceil, - round: Math.round, - abs: Math.abs, - min: Math.min, - max: Math.max, - pow: Math.pow, - sqrt: Math.sqrt, - - // Utility functions - clamp: (val, min, max) => Math.max(min, Math.min(max, val)), - - // Boolean functions (check character data) - hasFeature: (featureName) => { - return this.data.features?.some(f => f.name === featureName) || false; - }, - hasTrait: (traitName) => { - return this.data.traits?.includes(traitName) || false; - }, - isProficient: (skillName) => { - return this.data.skills?.find(s => s.name === skillName)?.proficient || false; - }, - - // Table lookup functions - lookup: (tableName, ...keys) => { - return this.lookupTable(tableName, keys); - }, - - // Array operations - sum: (array) => Array.isArray(array) ? array.reduce((a, b) => a + b, 0) : 0, - count: (array) => Array.isArray(array) ? array.length : 0, - - // String functions - concat: (...strings) => strings.join(''), - format: (template, ...args) => { - return template.replace(/\{(\d+)\}/g, (match, index) => args[index] || ''); - } - }; - - // Create sandboxed function - const func = new Function(...Object.keys(allowedFunctions), `return ${expression}`); - - // Execute with whitelisted functions - return func(...Object.values(allowedFunctions)); - } - - // Lookup value from a progression table defined in schema - lookupTable(tableName, keys) { - const tables = this.schema.tables || {}; - const table = tables[tableName]; - - if (!table) { - console.warn(`[Formula Engine] Table not found: ${tableName}`); - return 0; - } - - // Simple single-key lookup - if (keys.length === 1) { - return table[keys[0]] || 0; - } - - // Multi-key lookup (for 2D tables) - let value = table; - for (const key of keys) { - value = value?.[key]; - if (value === undefined) return 0; - } - - return value; - } - - // Clear cache (call when character data changes) - invalidateCache() { - this.cache.clear(); - } -} - -// Usage: -const engine = new FormulaEngine(characterInstance.data); -const strMod = engine.evaluate("floor((@coreAbilities.strength - 10) / 2)"); -console.log('STR Modifier:', strMod); // → 3 -``` - ---- - -## Schema Validation - -### JSON Schema Integration - -Use JSON Schema to validate character instances: - -```javascript -// src/systems/schema/validator.js - -import Ajv from 'ajv'; // Lightweight JSON Schema validator - -export class SchemaValidator { - constructor() { - this.ajv = new Ajv({ allErrors: true }); - } - - // Convert YAML schema to JSON Schema - compileSchema(yamlSchema) { - const jsonSchema = { - type: 'object', - properties: {}, - required: [] - }; - - // Convert each component to JSON Schema property - for (const [componentName, component] of Object.entries(yamlSchema.components)) { - jsonSchema.properties[componentName] = this.convertComponent(component); - - if (component.required) { - jsonSchema.required.push(componentName); - } - } - - return this.ajv.compile(jsonSchema); - } - - // Convert component definition to JSON Schema - convertComponent(component) { - switch (component.type) { - case 'object': - return { - type: 'object', - properties: this.convertProperties(component.properties) - }; - - case 'list': - return { - type: 'array', - items: this.convertComponent(component.items) - }; - - case 'resource': - return { - type: 'object', - properties: { - current: { type: 'number' }, - max: { type: 'number' } - }, - required: ['current', 'max'] - }; - - case 'number': - return { - type: 'number', - minimum: component.min, - maximum: component.max, - default: component.default - }; - - case 'text': - return { - type: 'string', - minLength: component.minLength, - maxLength: component.maxLength - }; - - case 'formula': - // Formulas are always numbers - return { type: 'number' }; - - default: - return { type: 'string' }; - } - } - - // Validate character instance against schema - validate(characterInstance, schema) { - const compiled = this.compileSchema(schema); - const valid = compiled(characterInstance.data); - - if (!valid) { - return { - valid: false, - errors: compiled.errors - }; - } - - return { valid: true }; - } -} -``` - ---- - -## Storage Layer - -### Hybrid Storage Strategy (Gemini Recommendation) - -**IndexedDB** for internal operations: -- Fast local access -- Query capabilities -- No size limits (within reason) - -**File System Access API** for import/export: -- User-friendly YAML files -- Version control compatible -- Shareable with community - -```javascript -// src/systems/schema/storage.js - -export class SchemaStorage { - constructor() { - this.db = null; - this.init(); - } - - async init() { - // Initialize IndexedDB - const request = indexedDB.open('RPGCompanionSchemas', 1); - - request.onupgradeneeded = (event) => { - const db = event.target.result; - - // Schemas store - if (!db.objectStoreNames.contains('schemas')) { - const schemaStore = db.createObjectStore('schemas', { keyPath: 'id' }); - schemaStore.createIndex('name', 'meta.name'); - schemaStore.createIndex('version', 'meta.version'); - } - - // Character instances store - if (!db.objectStoreNames.contains('characters')) { - const charStore = db.createObjectStore('characters', { keyPath: 'id' }); - charStore.createIndex('schemaId', 'schemaId'); - charStore.createIndex('name', 'data.identity.name'); - } - }; - - request.onsuccess = (event) => { - this.db = event.target.result; - console.log('[Schema Storage] IndexedDB initialized'); - }; - } - - // Save schema to IndexedDB - async saveSchema(schema) { - const transaction = this.db.transaction(['schemas'], 'readwrite'); - const store = transaction.objectStore('schemas'); - - const schemaWithId = { - id: `${schema.meta.name}-v${schema.meta.version}`, - ...schema, - savedAt: new Date().toISOString() - }; - - await store.put(schemaWithId); - return schemaWithId.id; - } - - // Load schema from IndexedDB - async loadSchema(schemaId) { - const transaction = this.db.transaction(['schemas'], 'readonly'); - const store = transaction.objectStore('schemas'); - - return new Promise((resolve, reject) => { - const request = store.get(schemaId); - request.onsuccess = () => resolve(request.result); - request.onerror = () => reject(request.error); - }); - } - - // List all schemas - async listSchemas() { - const transaction = this.db.transaction(['schemas'], 'readonly'); - const store = transaction.objectStore('schemas'); - - return new Promise((resolve, reject) => { - const request = store.getAll(); - request.onsuccess = () => resolve(request.result); - request.onerror = () => reject(request.error); - }); - } - - // Export schema to YAML file - async exportSchema(schemaId) { - const schema = await this.loadSchema(schemaId); - - // Convert to YAML - const yaml = this.toYAML(schema); - - // Use File System Access API (if available) - if ('showSaveFilePicker' in window) { - const handle = await window.showSaveFilePicker({ - suggestedName: `${schema.meta.name}.yaml`, - types: [{ - description: 'YAML Schema', - accept: { 'text/yaml': ['.yaml', '.yml'] } - }] - }); - - const writable = await handle.createWritable(); - await writable.write(yaml); - await writable.close(); - } else { - // Fallback: download blob - const blob = new Blob([yaml], { type: 'text/yaml' }); - const url = URL.createObjectURL(blob); - const a = document.createElement('a'); - a.href = url; - a.download = `${schema.meta.name}.yaml`; - a.click(); - URL.revokeObjectURL(url); - } - } - - // Import schema from YAML file - async importSchema() { - // Use File System Access API (if available) - if ('showOpenFilePicker' in window) { - const [handle] = await window.showOpenFilePicker({ - types: [{ - description: 'YAML Schema', - accept: { 'text/yaml': ['.yaml', '.yml'] } - }] - }); - - const file = await handle.getFile(); - const yaml = await file.text(); - const schema = this.fromYAML(yaml); - - // Validate and save - await this.saveSchema(schema); - return schema; - } else { - // Fallback: file input - return new Promise((resolve, reject) => { - const input = document.createElement('input'); - input.type = 'file'; - input.accept = '.yaml,.yml'; - - input.onchange = async (e) => { - const file = e.target.files[0]; - const yaml = await file.text(); - const schema = this.fromYAML(yaml); - await this.saveSchema(schema); - resolve(schema); - }; - - input.click(); - }); - } - } - - // Convert schema object to YAML string - toYAML(schema) { - // Use js-yaml library - return jsyaml.dump(schema, { - indent: 2, - lineWidth: 80, - noRefs: true - }); - } - - // Parse YAML string to schema object - fromYAML(yaml) { - // Use js-yaml library - return jsyaml.load(yaml); - } -} -``` - ---- - -## Custom UI Override System - -### Rationale - -While dynamic UI generation from schema definitions is powerful and efficient, some game systems benefit from highly stylized, pixel-perfect layouts that match their official character sheets. The Custom UI Override System allows schema authors to optionally provide custom HTML/CSS for specific components while maintaining the benefits of schema-driven data management. - -### Hybrid Approach - -```yaml -# In system.yaml - -customUI: - # Override specific components with custom templates - coreAbilities: - template: "custom-templates/dnd5e-abilities.html" - style: "custom-templates/dnd5e-abilities.css" - - # Other components use dynamic generation (default behavior) - # skills: (auto-generated) - # resources: (auto-generated) -``` - -### Custom Template Structure - -```html - -