D3.js visualization hangs indefinitely with no error messages

Issue

The Framework Network visualization on the About page (/about) displayed a persistent “Loading framework network…” state with no errors or feedback after the Voronoi stippling feature was added to the homepage (/). The issue was intermittent, requiring dev server restarts to temporarily resolve it. Key symptoms included:

• Canvas remained blank despite loading indicators
• No console errors or warnings
• Silent hangs with no timeout or recovery mechanism
• Dev server cache conflicts between pages

Culprit

The root cause was race conditions in dynamic script loading combined with ambiguous state tracking in D3.js loading. The original implementation lacked:

1. Script State Management: No clear mechanism to determine if the script loaded successfully, failed, or was still in progress
2. Race Condition Handling: Multiple pages could trigger concurrent script loads, causing unresolved states
3. Timeout Protection: No safeguard against CDN delays or slow network conditions
4. Debugging Visibility: No progression logging or error signaling

The dynamic script loading approach relied on implicit event resolution, which failed when multiple pages competed for the same D3.js resource in the dev server cache.

Solution

To address these issues, a deterministic loading pipeline was implemented:

1. Explicit State Tracking

A centralized scriptLoaded flag was introduced as the single source of truth to track the script’s lifecycle, ensuring all components could query its state deterministically.

2. Timeout Mechanism

A 10-second timeout was added to prevent indefinite hangs, providing immediate feedback if the script failed to load within an acceptable timeframe.

3. Enhanced Debugging

Progression logging was implemented to trace the loading process, enabling clearer error identification and debugging. Logs included:

• Script loading initiation
• CDN response tracking
• Error states

4. Comprehensive Error Handling

Improved error reporting included:

• Detailed error messages with script source verification
• User-facing error states
• Clean resource cleanup on failure

Key Improvements:

• Transformed ambiguous implicit loading into explicit, deterministic state management
• Eliminated silent hangs with guaranteed resolution (success/failure/timeout)
• Provided clear error feedback for troubleshooting
• Enabled debuggable progression with detailed logging

Modified File: frontend/src/components/FrameworkNetworkCanvas.astro

Result: Stable loading behavior across pages, consistent error recovery (≤10s), and actionable debug information.