Known Issues and Solutions - Editor Web

Widget Library Issues

✅ FIXED: Widgets Not Showing in Widget Library

Issue: Widget library showed "No se encontraron widgets que coincidan con tu búsqueda" despite having registered widgets.

Symptoms:

• Debug panel showed: Total widgets: 0
• Console logs showed: 📊 Metadata registry has 0 widgets
• Missing initialization logs: 🚀 WIDGET_FACTORIES_INITIALIZER: Starting widget factory registration...

Root Cause: Critical bug in WIDGET_FACTORIES_INITIALIZER in libs/widgets/src/lib/initializers/widget-factories.initializer.ts. The initializer was not properly calling the returned initialization function.

Broken Code:

export const WIDGET_FACTORIES_INITIALIZER: EnvironmentProviders = provideAppInitializer(() => {
  runInInjectionContext(inject(Injector), initializeWidgetFactories);
  // ↑ This returns a function but never calls it!
});

Fixed Code:

export const WIDGET_FACTORIES_INITIALIZER: EnvironmentProviders = provideAppInitializer(() => {
  const injector = inject(Injector);
  const initializationFn = runInInjectionContext(injector, initializeWidgetFactories);
  initializationFn(); // ← Actually calls the initialization!
});

Technical Details:

• initializeWidgetFactories() returns a function that does the actual widget registration work
• The provideAppInitializer was not calling that returned function
• Result: No widgets were ever registered in the metadata registry
• Widget library service found 0 widgets because none were registered

Solution Applied:

1. Fixed the initializer to properly call the returned initialization function
2. Added comprehensive debugging to track widget initialization flow
3. Added visual debugging panel in widget library component for future troubleshooting

Verification: After fix, console shows:

🚀 WIDGET_FACTORIES_INITIALIZER: Starting widget factory registration...
✅ Widget factory registration completed
📊 Available widget types after init: text,button,image,container,shape,video,simple,hero,card,gallery,testimonial,feature,pricing
Total widgets: 13

Prevention:

• Always verify that initialization functions returned by factory functions are actually called
• Use comprehensive debugging during development to catch initialization timing issues
• Test widget registration early in development cycle

Pages State Management Issues

✅ FIXED: Cannot read properties of undefined (reading 'activePage')

Issue: Runtime error in pages state management when selectors were called before state initialization.

Error Message:

ERROR TypeError: Cannot read properties of undefined (reading 'activePage')
    at _a.activePage (pages.state.ts:38:18)

Root Cause: NGXS selectors in libs/core-angular/src/lib/state/pages/pages.state.ts were not handling undefined state properly. When the state wasn't initialized yet, selectors would receive undefined as the state parameter, causing runtime errors.

Broken Code Example:

@Selector()
static activePage(state: PagesStateModel): Page | undefined {
  return state.activePage; // Error when state is undefined
}

@Selector()
static publishedPages(state: PagesStateModel): Page[] {
  return state.pages.filter(page => page.status === PageStatus.PUBLISHED); // Error when state is undefined
}

Fixed Code:

@Selector()
static activePage(state: PagesStateModel): Page | undefined {
  return state?.activePage || null;
}

@Selector()
static publishedPages(state: PagesStateModel): Page[] {
  return state?.pages?.filter(page => page.status === PageStatus.PUBLISHED) || [];
}

Solution Applied:

1. Added null safety checks to all NGXS selectors using optional chaining (?.)
2. Added fallback values for each selector return type
3. Fixed selectors: pages, page, activePage, publishedPages, draftPages, archivedPages, isLoading, isSaving, error, pageById, pagesByParentId

Prevention:

• Always add null safety checks to NGXS selectors
• Use optional chaining (?.) when accessing state properties
• Provide appropriate fallback values for each return type
• Test selector behavior during state initialization phases

Flash Persistence / Widget State Issues

✅ FIXED: Widget Changes Not Persisting (Movement, Position, etc.)

Issue: Widget changes like position, movement, or property modifications were not being saved or persisted through Flash Persistence.

Symptoms:

• Widget movements on canvas would reset after page refresh
• Position changes weren't saved
• Flash Persistence logs showed successful writes but changes didn't persist
• Console showed: ✅ WRITE VERIFICATION: flash:editor-state successfully persisted and readable

Root Cause: Missing connection between canvas widget changes and Flash Persistence state updates. The onWidgetsChange method in EditorUiComponent was calling this.editorService.setWidgets(widgets), and while the method existed, there was a potential issue with debugging visibility.

Technical Investigation:

// Canvas emits changes
canvas -> (widgetsChange)="onWidgetsChange($event)"

// EditorUI component handles event
onWidgetsChange(widgets: Widget[]): void {
  this.editorService.setWidgets(widgets); // ✅ This method existed
  this.widgetsChange.emit(widgets);       // ✅ Output existed  
}

// EditorService updates Flash Persistence  
setWidgets(widgets: Widget[]): void {
  this.editorState.update(state => ({     // ✅ Flash Persistence
    ...state,
    widgets: widgets,                      // ✅ State update
    isModified: true
  }));
}

Solution Applied:

1. Added comprehensive debugging to track the widget change flow:

   • EditorUiComponent.onWidgetsChange() - logs when canvas events are received
   • EditorService.setWidgets() - logs when state updates are triggered
   • Widget count comparisons to detect changes

2. Verified complete chain:

   • ✅ Canvas component emits widgetsChange events
   • ✅ editor-ui.component.html binds to (widgetsChange)="onWidgetsChange($event)"
   • ✅ onWidgetsChange() method exists and calls setWidgets()
   • ✅ setWidgets() method exists and updates Flash Persistence state
   • ✅ @Output() widgetsChange properly declared

Expected Console Output After Fix:

🔄 EditorUiComponent.onWidgetsChange called with 2 widgets
📊 Current widgets: 1 | New widgets: 2
🎯 EditorService.setWidgets called with 2 widgets
📊 Current widgets: 1 | New widgets: 2
✅ EditorService.setWidgets completed - Flash Persistence should trigger
💾 Flash Persistence: Persisted flash:editor-state via storage bridge
✅ WRITE VERIFICATION: flash:editor-state successfully persisted

Testing:

• Move widgets on canvas and check console for complete debugging chain
• Refresh page to verify widgets maintain their positions
• Check Flash Persistence logs for successful state persistence

Flash Persistence Configuration Issues

✅ FIXED: Missing Flash Persistence Provider in editor-web App

Issue: editor-web app showed ⏳ flash:editor-state waiting for hydration - starting with default and widgets wouldn't persist after page refresh.

Root Cause: The editor-web app was missing the provideAutoFlashPersistence provider entirely, while the EditorService was using autoFlashState('editor-state', {...}) which requires Flash Persistence to be configured.

App Configuration Comparison:

// ✅ gograb-space app (persistence worked)
provideAutoFlashPersistence({
  namespace: 'gograb-space',
  devMode: isDevMode()
})

// ❌ editor-web app (persistence failed) 
// Missing provideAutoFlashPersistence!
// Only had provideNgxsIntelligentStorage

Technical Details:

• EditorService uses autoFlashState('editor-state', {...}) for state management
• Flash Persistence requires provideAutoFlashPersistence to initialize the hydration system
• Without the provider: Components get stuck in "waiting for hydration" state
• Console showed: ⏳ flash:editor-state waiting for hydration - starting with default

Solution Applied:

// apps/editor-web/src/app/app.config.ts
export const appConfig: ApplicationConfig = {
  providers: [
    WIDGET_FACTORIES_INITIALIZER,

    // 🚀 BASE STORAGE PROVIDER: Required first!
    provideGgStorage({
      namespace: 'editor-web',
      // ... config
    }, (config) => GgStorage.create(config) as any),

    // ⚡ FLASH PERSISTENCE: CRITICAL FIX!
    // EditorService uses autoFlashState() which requires this provider
    provideAutoFlashPersistence({
      namespace: 'editor-web',
      devMode: isDevMode()
      // ✨ No state lists needed - automatically discovers states!
    }),

    // ... other providers
    EditorService, // Now works properly with Flash Persistence
    // ...
  ],
};

Expected Console Output After Fix:

🚀 Auto Flash Persistence initializing...
✨ Auto-discovered state: flash:editor-state
🎯 flash:editor-state loaded with persisted value: {...}
💾 Flash Persistence: Persisted flash:editor-state via storage bridge
✅ WRITE VERIFICATION: flash:editor-state successfully persisted

Key Learning: Always ensure that the persistence system provider matches the persistence API being used in services:

• autoFlashState() requires provideAutoFlashPersistence
• NGXS state requires provideStore + provideNgxsIntelligentStorage

Prevention:

• Check all apps using EditorService have Flash Persistence configured
• Use consistent persistence approaches within the same app
• Monitor console for "waiting for hydration" messages during development

Development Notes

Debugging Best Practices Applied

1. Comprehensive Logging: Added detailed console logs throughout widget initialization flow
2. Visual Debugging: Added debug panel in widget library component showing:
   • Total widgets count
   • Filtered widgets count
   • Selected category
   • Widget types list
   • Manual refresh capability
3. Multiple Retry Mechanisms: Added fallback timing checks for widget loading
4. Clear Error Messages: Enhanced error reporting with specific context

Architecture Improvements Made

1. Proper Dependency Injection: Used modern Angular inject() pattern consistently
2. Signal-Based Reactivity: Leveraged computed signals for reactive state management
3. Error Boundaries: Added proper error handling with fallbacks
4. Accessibility: Added keyboard support to interactive elements

Last Updated: September 27, 2025 Contributors: AI Assistant