Everything That Can Happen

Release Notes - Version v0.6.1

Release notes for version v0.6.1

Release Notes - Version 0.6.1

Release Date: 2025-06-10
Type: Patch Release
Previous Version: 0.6.0

🎯 Release Highlights

Version 0.6.1 introduces a critical fix to the Story Node Settings system, resolving significant UX issues with the “Use Custom Settings” checkbox functionality. This patch release includes a new database field, enhanced settings inheritance behavior, and comprehensive documentation updates.

🔧 Major Fixes & Improvements

Story Node Settings System Overhaul

Problem Resolved

The “Use Custom Settings” checkbox had incorrect behavior:

  • ❌ New story nodes always had checkbox checked (should be unchecked)
  • ❌ Unchecking the checkbox had no effect (page refreshed but remained checked)
  • ❌ No explicit field to track custom vs inherited settings intent
  • ❌ Settings UUID missing from image generation TOKEN logs

Solution Implemented

  • ✅ New Database Field: Added useCustomSettings boolean field to explicitly track custom vs inherited settings
  • ✅ Correct Checkbox Behavior: New nodes start unchecked, checking/unchecking works properly
  • ✅ Settings Inheritance Fix: Fixed node targeting to use current node instead of non-existent next node
  • ✅ Complete TOKEN Logging: Added settingsUUID to all image generation logs for cost tracking
  • ✅ Proper Service Integration: Updated both story generation and image generation workflows

🗄️ Database Schema Changes

Story Node Schema

interface StoryNode {
	// ... existing fields
	storyNodeSettingsUUID?: string; // Existing field
	useCustomSettings?: boolean; // 🆕 NEW FIELD (default: false)
}

Migration Notes

  • Backward Compatible: Existing nodes default to useCustomSettings = false
  • No Data Loss: All existing settings UUIDs are preserved
  • Automatic Application: New field applied automatically during story generation

🔄 Settings Inheritance Hierarchy

Correct Behavior (v0.6.1)

  1. Custom Node Settings (useCustomSettings = true) - Highest Priority
  2. Parent Node Settings (inherited from parent) - Medium Priority
  3. Story Default Settings (story-wide configuration) - Low Priority
  4. System Default Settings (fallback) - Lowest Priority

User Experience

  • New Nodes: Start with useCustomSettings = false (checkbox unchecked)
  • Enable Custom: Checking box creates new settings record, sets useCustomSettings = true
  • Disable Custom: Unchecking box removes custom settings, sets useCustomSettings = false, reverts to inheritance

🛠️ Technical Implementation

Backend Services Updated

  • story-node.service.ts: Fixed settings retrieval to use current node instead of next node
  • story-node-settings.service.ts: Updated all CRUD operations to properly handle useCustomSettings field
  • multi-layer-image.service.ts: Added settings UUID retrieval and passing to image generation
  • All TOKEN logs: Now include settingsUUID for complete traceability

API Endpoints Enhanced

  • GET /api/v1/stories/nodes/{nodeId}/settings: Now correctly returns hasCustomSettings based on useCustomSettings field
  • POST /api/v1/stories/nodes/{nodeId}/settings/custom: Sets useCustomSettings = true when creating custom settings
  • DELETE /api/v1/stories/nodes/{nodeId}/settings/custom: Sets useCustomSettings = false when removing custom settings

Frontend Integration

  • Checkbox State: Now properly reflects hasCustomSettings value from API
  • Form Behavior: Checking/unchecking triggers appropriate API calls
  • State Management: Consistent state between frontend and backend

📊 Testing & Quality Assurance

Test Coverage

  • ✅ 286/286 Backend Tests Passing (100% success rate)
  • ✅ 106/106 Frontend Tests Passing (100% success rate)
  • ✅ Total: 392/392 Tests Passing across entire codebase

Updated Test Cases

  • story-node-settings.service.spec.ts: Updated to test new useCustomSettings field behavior
  • Integration Tests: Verified complete checkbox workflow functionality
  • TOKEN Log Tests: Confirmed settingsUUID inclusion in all scenarios

📚 Documentation Updates

Comprehensive Documentation Overhaul

All project documentation updated to reflect new behavior:

  1. Implementation Status (docs/implementation-status.md)

    • Added Story Node Settings System to completed features
    • Updated latest progress with v0.6.1 changes

  2. Schema Definitions (docs/schema-definitions.md)

    • Added complete Story Node Settings schema
    • Documented useCustomSettings field and inheritance hierarchy

  3. Technical Architecture (docs/technical-architecture.md)

    • Enhanced service architecture documentation
    • Added StoryNodeSettingsService to specialized services

  4. API Documentation (docs/api-documentation.md)

    • Added complete Story Node Settings API endpoints
    • Documented request/response examples with correct behavior

  5. User Guide (docs/user-guide.md)

    • Added comprehensive “Understanding the Use Custom Settings Checkbox” section
    • Explained settings hierarchy and inheritance rules for storytellers

🏗️ Development Workflow Improvements

Dev Journal Documentation

Created detailed development journals documenting:

  • 01-endpoint-naming-consistency-fix.md: API endpoint standardization
  • 02-story-node-settings-fix.md: Settings retrieval and UUID fixes
  • 03-use-custom-settings-checkbox-fix.md: Complete checkbox behavior solution

Code Quality

  • DRY Principles: Removed duplicate logic and consolidated settings handling
  • Error Handling: Enhanced error logging and debugging capabilities
  • Type Safety: Improved TypeScript interfaces and validation

🚀 Performance & Monitoring

Enhanced Logging

  • TOKEN Logs: All image generation now includes settingsUUID for cost tracking
  • Debug Endpoint: Enhanced /api/v1/logs/debug-recent with settings context
  • Error Tracking: Improved error context for settings-related issues

Cost Transparency

  • Settings Traceability: Every AI generation call now traceable to specific settings UUID
  • Budget Monitoring: Better cost tracking for custom settings usage
  • Administrative Visibility: Complete audit trail for settings changes

⚡ Breaking Changes

None

This release is fully backward compatible:

  • ✅ Existing story nodes continue to work without modification
  • ✅ All existing APIs maintain backward compatibility
  • ✅ Database migrations are automatic and non-destructive
  • ✅ Frontend interfaces remain unchanged (only behavior improved)

🔮 Looking Forward

Foundation for Future Features

This release establishes a solid foundation for:

  • Advanced Settings Management: More granular control over AI behavior
  • Settings Templates: Reusable settings configurations
  • Collaborative Settings: Shared settings between storytellers
  • Settings Analytics: Usage patterns and effectiveness tracking

Next Release Preview

Upcoming features planned for v0.7.0:

  • Node-Based Story Editor: Visual story editing with React Flow
  • Enhanced Visual Themes: More comprehensive theme system
  • Advanced Analytics: Deeper insights into story performance

💡 Developer Notes

Migration Required

  • None: All changes are automatic and backward compatible

Environment Variables

  • No Changes: All existing configuration remains valid

Deployment Notes

  • Database: Automatic schema updates during application startup
  • Redis/Caching: No cache invalidation required
  • CDN: No asset changes require cache busting

🎉 Acknowledgments

This release represents a significant improvement in user experience and system reliability. Special recognition for:

  • Critical Issue Identification: User feedback identified the checkbox behavior problem
  • Comprehensive Testing: 392/392 tests ensure release stability
  • Documentation Excellence: Complete documentation overhaul for clarity
  • Backward Compatibility: Zero-downtime deployment with full compatibility

📝 Full Changelog

Added

  • 🆕 useCustomSettings boolean field to Story Node schema
  • 🆕 Settings UUID inclusion in all TOKEN logs
  • 🆕 Comprehensive Story Node Settings API documentation
  • 🆕 Enhanced user guide with checkbox behavior explanation

Fixed

  • 🔧 “Use Custom Settings” checkbox now starts unchecked for new nodes
  • 🔧 Checkbox checking/unchecking now works correctly
  • 🔧 Settings inheritance uses correct node targeting
  • 🔧 Image generation TOKEN logs include settings UUID
  • 🔧 Multi-layer image service properly passes settings context

Changed

  • 📝 Updated all documentation to reflect correct behavior
  • 📝 Enhanced API responses with proper settings metadata
  • 📝 Improved error messages and logging context

Technical

  • ⚙️ Updated 6 backend service files with enhanced logic
  • ⚙️ Modified database schema with new field (backward compatible)
  • ⚙️ Enhanced 286 backend tests for new behavior
  • ⚙️ Improved TypeScript interfaces and validation

Download: Release v0.6.1
Issues: Report Issues
Documentation: Complete Documentation

Everything Happens Team - Making Interactive Storytelling Better 🚀