rpg-companion-sillytavern/docs/IMPLEMENTATION_PLAN.md

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

• Add resize handles to widget corners (edit mode only)
• Implement resize logic
  • Track mouse position relative to widget
  • Update widget width/height in grid units
  • Respect minSize constraints from widget definition
  • Snap resize to grid cells
• Add visual feedback during resize
  • Show new dimensions in overlay
  • Highlight affected grid cells
  • Show collision warnings
• Handle resize collisions
  • Push other widgets down if needed
  • Prevent resize if would overlap and can't push

Acceptance Criteria:

• Resize handles appear in edit mode
• Can resize widgets by dragging corners
• Respects minimum size constraints
• Grid snapping works during resize
• Collisions handled gracefully

---

Task 1.7: Edit Mode UI

Dependencies: Task 1.4, Task 1.5, Task 1.6 Estimated Time: 3-4 days

• Create edit mode state management
  • Add isEditMode flag to state
  • Toggle edit mode with button in panel header
  • Show/hide edit controls based on mode
• Build edit mode UI elements
  • "Edit Layout" button in panel header
  • "Save" and "Cancel" buttons when in edit mode
  • Grid overlay visualization (dotted lines)
  • Widget library sidebar
• Implement widget controls (edit mode only)
  • Drag handle in widget header
  • Delete button (×) in widget header
  • Settings button (⚙) in widget header
  • Resize handles on widget corners
• Add confirmation dialogs
  • Confirm before deleting widget
  • Confirm before canceling unsaved changes
  • Confirm before resetting to default layout

Acceptance Criteria:

• Edit mode toggle works smoothly
• All edit controls visible only in edit mode
• Grid overlay appears when editing
• Confirmation dialogs prevent accidental changes
• Changes saved on "Save", reverted on "Cancel"

---

Task 1.8: Layout Persistence

Dependencies: Task 1.7 Estimated Time: 2-3 days

• Create LayoutPersistence class (src/systems/dashboard/layoutPersistence.js)
  • saveLayout(dashboard) - Save to extensionSettings
  • loadLayout() - Load from extensionSettings
  • exportLayout() - Export as JSON file
  • importLayout(file) - Import from JSON file
  • resetToDefault() - Restore default layout
• Add debounced auto-save
  • Save 500ms after widget position change
  • Save immediately on tab create/delete/rename
  • Show save indicator in UI
• Implement import/export UI
  • "Export Layout" button in settings
  • "Import Layout" button in settings
  • File picker for import
  • Download JSON file for export

Acceptance Criteria:

• Layout changes persist across page refreshes
• Auto-save works reliably without lag
• Export creates valid JSON file
• Import correctly restores layout
• Reset button restores default layout

---

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: Not Started 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

• 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

Acceptance Criteria:

• User Stats widget appears in widget library
• Can drag onto grid and resize
• Displays all current stats correctly
• Configuration options work
• Editable fields still functional

---

Task 2.2: Info Box Widget

Dependencies: Task 2.1 Estimated Time: 2-3 days

• Register infoBox widget in registry
• Create widget render function
  • Reuse existing renderInfoBox() logic
  • Maintain dashboard widget styling
  • Keep editable fields functional
• Add widget configuration options
  • Toggle individual widgets (calendar, weather, temp, clock, location)
  • Choose widget layout (horizontal/vertical)
  • Customize colors
• Test all info box interactions
  • Editing date/weather/time/location
  • Field focus/blur behavior
  • Data persistence

Acceptance Criteria:

• Info Box widget draggable and resizable
• All dashboard widgets render correctly
• Editing functionality preserved
• Configuration options work
• Responsive on mobile

---

Task 2.3: Present Characters Widget

Dependencies: Task 2.2 Estimated Time: 3-4 days

• 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
• Add widget configuration options
  • Choose card layout (list/grid)
  • Filter by relationship type
  • Toggle thought bubbles in chat
  • Customize card styling
• Test character card interactions
  • Editing character fields
  • Avatar loading
  • Thought bubble overlay in chat

Acceptance Criteria:

• Present Characters widget functional
• Character cards display correctly
• Editing works as before
• Thought bubbles still appear in chat
• Configuration options work

---

Task 2.4: Inventory Widget

Dependencies: Task 2.3 Estimated Time: 4-5 days

• Register inventory widget in registry
• Create widget render function
  • Reuse existing renderInventory() logic
  • Show sub-tabs (On Person, Stored, Assets)
  • Maintain list/grid view toggles
  • Keep collapsible locations
• Add widget configuration options
  • Set default sub-tab
  • Choose default view mode (list/grid)
  • Customize location order
  • Toggle item counts
• Test all inventory interactions
  • Adding/removing items
  • Creating/deleting storage locations
  • Editing item names
  • Switching view modes
  • Collapsing/expanding locations

Acceptance Criteria:

• Inventory widget fully functional
• All sub-tabs work correctly
• View mode toggles work
• Storage locations editable
• Item editing preserved
• Configuration options functional

---

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 Complete When:

• All core widgets converted and functional
• Each widget draggable and resizable
• All existing functionality preserved
• Configuration options work for each widget
• No regressions in data persistence
• Mobile responsive behavior maintained

---

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