Pakobbix/rpg-companion-sillytavern
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
revert-40-feat/responsive-dashboard-layout
rpg-companion-sillytavern/docs/IMPLEMENTATION_PLAN.md
T
Lucas 'Paperboy' Rose-Winters 122bb3194a feat(dashboard): add auto-layout button with smart widget packing 
Implements intelligent auto-layout system that efficiently arranges widgets to maximize space usage while respecting panel width constraints.

**Key Features:**
- Smart packing algorithm that sorts by widget area and finds optimal positions
- Respects responsive column count (2-4 columns based on panel width)
- Prefers full-width widgets when possible to eliminate gaps
- Fallback to narrower widths for better vertical packing
- Maintains minimum widget sizes

**Implementation:**
- GridEngine.autoLayout() - Core packing algorithm with collision detection
- DashboardManager.autoLayoutWidgets() - High-level API that re-renders after layout
- Auto-Arrange button in dashboard header (uses fa-table-cells-large icon)
- Event handler wired to call autoLayoutWidgets with preferFullWidth=true

**Algorithm Strategy:**
1. Sort widgets by area (largest first) for efficient packing
2. For each widget, try full-width placement first
3. Find first available position using row-by-row scan
4. If position is too far down, try narrower widths
5. Mark cells as occupied to prevent overlaps

**Testing Notes:**
- Works with current responsive column system (2-4 columns)
- Respects minimum sizes and column constraints
- Re-renders all widgets after repositioning
- Auto-saves layout changes

Part of Epic 2: Dashboard Widget Library
2025-10-23 14:00:00 +11:00

74 KiB
Raw Permalink Blame History

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

  • Create src/systems/dashboard/ directory structure
  • Implement GridEngine class (src/systems/dashboard/gridEngine.js)
    • constructor(config) - Initialize grid with columns, rowHeight, gap
    • getPixelPosition(widget) - Convert grid coords to pixels
    • snapToCell(pixelX, pixelY) - Snap pixel position to grid
    • detectCollision(widget, widgets) - Check for widget overlaps
    • reflow(widgets) - Auto-reflow on collision
  • Add unit tests for grid calculations
    • Test snap-to-grid accuracy
    • Test collision detection edge cases
    • 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

  • Create WidgetRegistry class (src/systems/dashboard/widgetRegistry.js)
    • register(type, definition) - Register widget type
    • get(type) - Retrieve widget definition
    • getAvailable(hasSchema) - List available widgets
    • unregister(type) - Remove widget type
  • Define widget definition interface (JSDoc types)
  • Create base widget template with lifecycle hooks
  • 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

  • Define dashboard config structure in src/core/state.js
    • Add extensionSettings.dashboard object
    • Add gridConfig (columns, rowHeight, gap, snapToGrid, showGrid)
    • Add tabs array structure
    • Add defaultTab string
  • Create default layout generator
    • Generate "Status" tab with userStats, infoBox, presentCharacters
    • Generate "Inventory" tab with inventory widget
  • Add dashboard config to settings save/load
  • 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

  • Create TabManager class (src/systems/dashboard/tabManager.js)
    • createTab(name, icon) - Add new tab
    • renameTab(tabId, newName) - Rename existing tab
    • deleteTab(tabId) - Remove tab (with confirmation)
    • reorderTabs(tabIds) - Change tab order
    • duplicateTab(tabId) - Copy tab with all widgets
    • setActiveTab(tabId) - Switch active tab
    • changeTabIcon(tabId, newIcon) - Change tab icon
    • switchToTabByIndex(index) - Switch by numeric index
    • switchToNextTab() - Navigate to next tab
    • switchToPreviousTab() - Navigate to previous tab
  • Implement tab navigation UI
    • Tab buttons with icons and names
    • Active tab highlighting
    • Tab overflow handling (scroll with flex-wrap)
    • "+" button to add new tab
    • Quick close button on each tab
  • Add keyboard shortcuts for tab switching
    • Ctrl+1-9 for direct tab access
    • Ctrl+Tab for next tab
    • Ctrl+Shift+Tab for previous tab
  • Add tab context menu (right-click)
    • Rename option
    • Change icon option
    • Duplicate option
    • Delete option (with danger styling)
  • Event system with change listeners
  • 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

  • Create DragDropHandler class (src/systems/dashboard/dragDrop.js)
    • initWidget(element, widget, onDragEnd) - Attach drag listeners (mouse + touch)
    • startDrag(e, element, widget) - Begin drag operation with ghost creation
    • onMouseMove(e) - Update widget position during mouse drag
    • onTouchMove(e) - Update widget position during touch drag
    • onMouseUp(e) / onTouchEnd(e) - Complete drag and snap to grid
    • Full touch event support with 150ms delay for scrolling
    • updateDragPosition() - Unified position update for mouse/touch
    • destroyWidget() - Remove drag handlers and cleanup
  • Add visual drag feedback
    • Ghost/preview of widget during drag (configurable opacity)
    • Grid cells highlight on hover (green overlay)
    • Grid overlay with cell highlighting
    • Original widget dims to 30% opacity during drag
  • Mobile-first implementation
    • Touch delay (150ms) to allow scrolling
    • Passive event listeners where appropriate
    • viewport meta tag with user-scalable=no
    • touch-action: none to prevent browser gestures
    • 44px minimum touch targets
    • Responsive grid that adapts to screen size
  • Add drag constraints
    • Grid snapping on position update
    • Cancel drag on Escape key
    • Bounded to grid columns (x + w ≤ columns)
    • Collision detection available via hasCollision()
  • Additional features
    • Event-driven architecture (onDragEnd callback)
    • Cleanup on destroy
    • Cursor changes (grab → grabbing)
    • 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

  • Add resize handles to widget corners/edges (8 total: 4 corners + 4 edges)
    • Handles appear on hover (fade in/out transition)
    • Proper cursor styles for each handle direction
    • Touch and mouse event support with 150ms delay
    • Handle positioning with CSS transforms
  • Implement resize logic
    • Track pointer position relative to widget
    • Update widget width/height in grid units
    • Update widget x/y when resizing from top/left
    • Respect min/max size constraints from configuration
    • Snap resize to grid cells in real-time
    • Unified mouse + touch event handling
  • Add visual feedback during resize
    • Dimension overlay showing current size (e.g., "6×3")
    • Grid cell highlighting (green overlay)
    • Widget glow effect while resizing
    • Smooth transitions for handle visibility
  • Mobile-first implementation
    • Touch delay (150ms) for scroll compatibility
    • Passive event listeners where appropriate
    • 12px touch-friendly handle size
    • Hover effects scale handles for visibility
  • Additional features
    • Escape key cancels resize and restores original size
    • Prevent resize beyond grid boundaries
    • Event-driven architecture (onResizeEnd callback)
    • 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

  • Create edit mode state management
    • Add isEditMode flag to state
    • Toggle edit mode with button
    • Show/hide edit controls based on mode
    • Store original layout for cancel
    • Event-driven architecture with change listeners
  • Build edit mode UI elements
    • "Edit Layout" toggle button in header
    • "Save" and "Cancel" buttons when in edit mode
    • Grid overlay visualization (repeating linear gradient)
    • Widget library sidebar with click-to-add
    • Status bar showing mode, widget count, grid units
  • Implement widget controls (edit mode only)
    • Settings button (⚙) in widget header
    • Delete button (×) in widget header
    • Controls fade in on hover
    • Stop propagation to prevent drag conflicts
    • Resize handles integrated from Task 1.6
  • Add confirmation dialogs
    • Confirm before deleting widget
    • Confirm before canceling unsaved changes
    • Confirm before resetting to default layout (method provided)
  • Complete integration
    • Drag, resize, and edit all work together
    • Edit mode class added to container
    • Widget library with 6 widget types
    • 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

  • Create LayoutPersistence class (src/systems/dashboard/layoutPersistence.js)
    • saveLayout(dashboard, immediate) - Save with optional debouncing
    • debouncedSave(dashboard) - 500ms debounced save
    • performSave(dashboard) - Actual save operation with validation
    • loadLayout() - Load from localStorage/extensionSettings
    • exportLayout(dashboard, filename) - Export as JSON download
    • importLayout(file) - Import from JSON file with validation
    • resetToDefault(defaultDashboard) - Restore default layout
    • validateDashboard(dashboard) - Comprehensive validation
  • Add debounced auto-save
    • Save 500ms after widget position change (drag/resize)
    • Save on widget add/delete operations
    • Save on edit mode save
    • Show save status indicator in UI
    • Visual feedback for save states (saving, saved, pending, error)
  • Implement import/export UI
    • "Save Now" button for manual immediate save
    • "Export Layout" button downloads JSON file with timestamp
    • "Import Layout" button with hidden file input
    • File picker for import with validation
    • Download JSON file with metadata (version, timestamp, appVersion)
    • "Reset to Default" button with confirmation
  • Additional features
    • Event system with onChange listeners
    • Event log showing all persistence operations
    • Save status tracking (isSaving, pendingSave, lastSaveTime)
    • Error handling with user-friendly messages
    • Metadata in saved layouts (version, savedAt, appVersion)
    • 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:

  • Grid engine works with accurate positioning
  • Widget registry can register/retrieve widgets
  • Dashboard config persists correctly
  • Tab management fully functional
  • Drag-and-drop works on desktop and mobile
  • Resize handles work smoothly
  • Edit mode toggle and UI complete
  • 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

  • Register userStats widget in registry
    • Define widget metadata (name, icon, minSize, defaultSize)
    • Set requiresSchema: false
  • Create widget render function
    • Reuse existing renderUserStats() logic
    • Wrap in widget container with header
    • Add widget-specific CSS classes
  • Add widget configuration options
    • Toggle classic stats display
    • Choose stat bar style (solid/gradient)
    • Select which stats to show
  • Implement configuration UI
    • Settings icon opens config modal
    • Config changes update widget immediately
    • 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)

  • Register 5 separate widgets in registry (calendar, weather, temperature, clock, location)

  • Create widget render functions for each

    • Reuse existing renderInfoBox() logic with shared data parsing
    • Maintain dashboard widget styling
    • Keep editable fields functional

  • Shared data parsing utilities

    • parseInfoBoxData() - Parse shared infoBox data source
    • updateInfoBoxField() - Update shared data

  • Add widget configuration options

    • Weather widget: compact mode
    • Clock widget: analog/digital toggle
    • Temperature widget: Celsius/Fahrenheit

  • Test all info box interactions

    • Editing date/weather/time/location
    • Field focus/blur behavior
    • 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

  • Register presentCharacters widget in registry
  • Create widget render function
    • Reuse existing renderThoughts() logic
    • Display character cards with avatars
    • Show relationship badges (⚔️ ⚖️ ⭐ ❤️)
    • Render traits and thoughts
  • Fuzzy name matching for avatars
    • Exact match, parenthetical stripping, word boundary matching
  • Add widget configuration options
    • Choose card layout (list/grid/compact)
    • Toggle thought bubbles in chat
  • Test character card interactions
    • Editing character fields (emoji, name, traits, relationship)
    • Avatar loading with fuzzy matching
    • 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

  • Register inventory widget in registry
  • Create widget render function
    • Reuse existing renderInventory() logic with itemParser integration
    • Show sub-tabs (On Person, Stored, Assets)
    • Maintain list/grid view toggles per sub-tab
    • Keep collapsible locations
  • Per-widget instance state management
    • Active sub-tab tracking
    • Collapsed locations tracking
    • View modes per sub-tab
  • Full CRUD operations
    • Add/remove items with inline forms
    • Create/delete storage locations
    • Edit item names inline
    • Enter/Escape key support
  • Add widget configuration options
    • Compact mode toggle
  • Test all inventory interactions
    • Adding/removing items
    • Creating/deleting storage locations with confirmation
    • Editing item names (contenteditable)
    • Switching view modes (list/grid)
    • Collapsing/expanding locations
    • 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):

  • Task 2.1: User Stats Widget (408 lines)
  • Task 2.2: Info Box Widgets - 5 modular widgets (545 lines)
  • Task 2.3: Present Characters Widget (377 lines)
  • 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:

  • YAML parser integrated and working
  • Schema data structure defined
  • Formula engine evaluates correctly
  • Schema validation catches errors
  • IndexedDB storage reliable
  • File export/import works
  • 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:

  • Schema widget renderer works for all component types
  • All schema-driven widgets implemented
  • Widgets only appear when schema active
  • Editing and persistence works
  • Configuration options functional
  • 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:

  • Schema editor modal fully functional
  • YAML editor with syntax highlighting
  • Visual builder creates valid schemas
  • Preview pane shows live updates
  • Template library available
  • 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:

  • Schema-based prompts generate correctly
  • Parser extracts schema data from responses
  • Together and Separate modes both work
  • Prompt injection integrated
  • 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:

  • Mobile responsive layout works
  • Animations smooth and toggleable
  • Settings panel integrated
  • Keyboard shortcuts functional
  • Accessibility requirements met
  • Performance optimized
  • 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:

  • User documentation complete
  • Migration wizard tested
  • Schema templates created
  • All testing completed
  • 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

Reference in New Issue View Git Blame Copy Permalink