Last updated: Sep 1, 2025, 01:10 PM UTC

HTML Generation Issues Resolution

Overview

This document describes the comprehensive fixes implemented to resolve three critical issues with HTML generation in the Sasha Studio documentation system.

Issues Resolved

1. Toast Notification Never Dismisses

Problem: The "Generating HTML reports..." toast would remain spinning indefinitely, never showing completion status.

Root Cause: Toast dismissal logic was conditional and could fail to execute in error scenarios.

Solution:

  • Always dismiss loading toast immediately after receiving server response
  • Moved toast.dismiss(toastId) to execute before conditional logic
  • Added proper error message extraction from server response
// Before: Conditional dismissal
if (response.data && response.data.success) {
  toast.dismiss(toastId);
  // success handling
} else {
  toast.dismiss(toastId); // Could be missed
}

// After: Always dismiss first
toast.dismiss(toastId);
if (response.data && response.data.success) {
  // success handling
} else {
  // error handling
}

2. No Initial HTML Content on Docker Startup

Problem: Even when markdown files existed, no HTML documentation was available until manual generation.

Root Cause: HTML generation only occurred on manual trigger, not during container initialization.

Solution:

  • Stage 1: Generate SPA content-only HTML immediately during startup
  • Stage 2: Generate full HTML documentation after server becomes ready
  • Background process ensures non-blocking container startup

Implementation:

# docker-entrypoint.sh
# Generate SPA content immediately
node /app/scripts/generate-spa-html.js

# Schedule full HTML generation after server startup
(sleep 10 && node /app/scripts/generate-initial-html.js) &

3. Auto-Refresh Doesn't Work

Problem: After generating HTML, the documentation iframe didn't refresh automatically, requiring manual browser refresh.

Root Cause: DocsPanel iframe wasn't listening for live-reload WebSocket messages.

Solution:

  • Added WebSocket connection to live-reload endpoint
  • Added custom event listener for immediate refresh triggers
  • Proper cleanup on component unmount

Implementation:

// Dual refresh mechanism
const handleDocsGenerated = () => setRefreshKey(prev => prev + 1);
window.addEventListener('docs-generated', handleDocsGenerated);

// WebSocket live-reload
const ws = new WebSocket(`${protocol}//${window.location.host}/live-reload`);
ws.onmessage = (event) => {
  if (event.data === 'reload') {
    setRefreshKey(prev => prev + 1);
  }
};

Architecture Changes

Container Startup Flow

graph TD A[Container Starts] --> B[Copy MD Files to Persistent Volume] B --> C[Generate SPA Content-Only HTML] C --> D[Start Server in Background] D --> E[Schedule Full HTML Generation] E --> F[Server Ready Check] F --> G[Generate Full HTML Documentation] G --> H[Ready for User Access]

User Interaction Flow

graph TD A[User Clicks 'Publish HTML'] --> B[Show Loading Toast] B --> C[API Call to Generate Reports] C --> D[Always Dismiss Loading Toast] D --> E{Success?} E -->|Yes| F[Show Success Toast] E -->|No| G[Show Error Toast] F --> H[Dispatch 'docs-generated' Event] H --> I[DocsPanel Auto-Refreshes] G --> I

Files Modified

1. src/components/FileTree.jsx

  • Fixed toast dismissal logic in handleGenerateReports()
  • Added custom event dispatch for DocsPanel refresh
  • Improved error handling and message extraction

2. src/components/DocsPanel.jsx

  • Added WebSocket connection for live-reload
  • Added custom event listener for immediate refresh
  • Proper cleanup in useEffect return function

3. docker-entrypoint.sh

  • Added immediate SPA content generation
  • Added background full HTML generation
  • Non-blocking startup process

4. scripts/generate-initial-html.js (New)

  • Server readiness checking with retry logic
  • API-based HTML generation trigger
  • Graceful error handling with fallback

Testing Scenarios

Scenario 1: Fresh Container Startup

  1. Container starts with markdown files
  2. SPA content generated immediately
  3. Server starts successfully
  4. Full HTML generated in background
  5. Documentation accessible on first visit

Scenario 2: Manual HTML Generation

  1. User clicks "Publish HTML" button
  2. Loading toast appears
  3. Toast dismisses regardless of success/error
  4. Appropriate success/error message shown
  5. DocsPanel refreshes automatically

Scenario 3: Development Live-Reload

  1. WebSocket connection established
  2. Server broadcasts reload on HTML generation
  3. DocsPanel receives signal and refreshes
  4. No manual refresh required

Benefits

  • Immediate Availability: HTML documentation ready on container startup
  • Better UX: Proper toast feedback and auto-refresh
  • Reliability: Robust error handling and fallback mechanisms
  • Development Experience: Live-reload works seamlessly
  • Non-blocking: Background processes don't delay container startup

Future Considerations

  • Monitor server startup time to optimize background generation delay
  • Consider adding progress indicators for long HTML generation processes
  • Evaluate caching strategies for frequently accessed documentation
  • Monitor WebSocket connection stability in production environments

Status: Complete
Generated: 2025-08-24 09:00 UTC