Release Notes - Version 0.6.7

Release Date: 2025-06-22

Parallax Theme Enhancement & Image Health Check System

Overview

Version 0.6.7 delivers major improvements to the Parallax theme experience and introduces a comprehensive image health check system. This release focuses on feature parity between themes and proactive error detection for image-related issues.

Major Features

Parallax Image Generation Polling

Enhancement: Real-time image generation feedback for Parallax theme

Problem Solved:

Parallax theme lacked image generation polling (available in vanilla theme)
Users had to manually refresh pages to see generated images
No visual feedback during image generation process

Solution Implemented:

Feature Parity: Parallax theme now matches vanilla theme functionality
Automatic Detection: Detects ongoing image generation on page load
Smart Polling: Only polls when generation is likely happening (within 10 minutes)
Efficient Updates: Uses lightweight 273-byte status checks vs full node data
Visual Feedback: Shows “Generating image…” state with spinner

Technical Details:

Client-side polling system with 3-second intervals
Smart polling conditions based on node age and generation status
Automatic page refresh when images become available
3-minute timeout to prevent infinite polling
Proper cleanup on page transitions

Benefits:

✅ Identical UX: Parallax theme now matches vanilla theme experience
✅ Automatic Updates: Images appear without manual refresh
✅ Performance: Minimal overhead with lightweight status endpoint
✅ Resource Management: Timeout prevents runaway polling

Image Layer Settings Health Check System

Enhancement: Comprehensive validation and repair system for image layer settings

Problem Solved:

Story nodes being saved with empty imageLayerSettingsUUID values
Failed image generation due to invalid layer configurations
No user-visible way to detect or fix these issues
Console warnings with no clear resolution path

Health Check Features:

Automatic Detection: Runs on page load for edit forms
Validation Logic: Checks enabled layers against UUID values
Visual Warnings: Orange warning box with clear issue description
One-Click Fixes: “Fix Image Layer Settings” button resolves issues
Prevention: New nodes cannot be saved with invalid configurations

Technical Implementation:

Backend Services:

validateImageLayerSettings() - Prevents saving invalid configurations
checkImageLayerSettingsHealth() - Analyzes layer health status
fixImageLayerSettingsUUIDs() - Automatically repairs empty UUIDs

Frontend Components:

ImageLayerSettingsWarning.tsx - React component for health warnings
Integration with EditStoryNodeForm for immediate feedback
Enhanced PresetInfo component with error state indicators

API Endpoints:

POST /admin/story-node-health/check-image-layer-settings/:nodeId
POST /admin/story-node-health/fix-image-layer-settings/:nodeId

User Experience Improvements

Before v0.6.7 (Parallax Theme)

No visual feedback during image generation
Images required manual page refresh to appear
Inconsistent experience compared to vanilla theme

After v0.6.7 (Parallax Theme)

Real-time Feedback: Automatic “Generating…” state display
Seamless Updates: Images appear automatically when ready
Consistent Experience: Matches vanilla theme functionality perfectly

Before v0.6.7 (Image Health)

Silent failures with console warnings only
No user-visible indication of layer setting problems
Manual database intervention required to fix issues

After v0.6.7 (Image Health)

Proactive Detection: Issues identified automatically
Clear Warnings: Visual indicators with specific problem descriptions
Self-Service Repair: One-click fix for common configuration issues
Prevention: Invalid configurations blocked at save time

Technical Enhancements

Parallax Polling Architecture

Smart Polling Conditions:

const shouldPoll =
	storyData?.autoGenerateImages !== false &&
	nodeData.debug &&
	(recentlyGenerated || generatedByAI);

Resource Management:

3-second polling intervals for responsiveness
3-minute timeout prevents infinite loops
Cleanup on page transitions and unload events
Error handling for API failures

Health Check System Architecture

Validation Flow:

Check story layer configuration
Validate enabled layers have non-empty UUIDs
Provide specific error messages for each issue
Generate repair suggestions automatically

Fix Process:

Generate new UUIDs for affected layers
Update node with proper settings
Return detailed success/failure information
Trigger UI refresh to show resolved state

Performance Optimizations

Parallax Theme

Lightweight Status Checks: 273 bytes vs 2KB+ for full node data
No Side Effects: Status endpoint doesn’t increment view counts
Hardware Acceleration: Smooth parallax transitions with 0.6s duration

Health Check System

Lazy Loading: Health checks only run when editing nodes
Efficient Validation: Quick UUID existence checks
Minimal Database Impact: Targeted queries for affected data

Testing Results

Frontend Tests: 129/129 passing (100% success rate)
Backend Tests: 331/331 passing (100% success rate)
Integration Tests: End-to-end polling and health check validation
Manual Testing: Verified across multiple browsers and scenarios

API Changes

New Endpoints

GET /api/v1/stories/nodes/{nodeId}/image-status - Lightweight status check
POST /admin/story-node-health/check-image-layer-settings/:nodeId - Health validation
POST /admin/story-node-health/fix-image-layer-settings/:nodeId - Automatic repair

Response Formats

// Image Status Response
{
  nodeId: string;
  imageUrl: string;
  hasImage: boolean;
  isGenerating: boolean;
}

// Health Check Response
{
  nodeId: string;
  issues: string[];
  enabledLayers: string[];
  layersWithEmptyUUID: string[];
  canFixEmptyUUIDs: boolean;
  suggestedFix?: string;
}

Developer Experience

Debugging Improvements

Enhanced logging for inheritance and polling processes
Clear error messages for configuration issues
Visual indicators for problematic preset loading

Code Quality

Consistent polling patterns between themes
Reusable health check utilities
Proper TypeScript interfaces for all new functionality

Compatibility

Backward Compatible: All existing functionality preserved
No Breaking Changes: Existing nodes and themes continue to work
Progressive Enhancement: New features activate automatically where appropriate

Upgrade Notes

For Users:

Parallax theme now provides real-time image generation feedback
Orange warnings will appear for nodes with layer setting issues
One-click fix button resolves most common configuration problems

For Developers:

New health check utilities available for other validation scenarios
Polling pattern can be extended to other real-time features
Enhanced error handling patterns established

Version: 0.6.7
Build: Production Ready
Deployment: Automatic via Railway
Database Changes: None
Breaking Changes: None

Everything That Can Happen

Release Notes - Version v0.6.7