dom-structure-preservation

DOM Structure Preservation Rule - Three-Phase Compatible

APPLY: EVERY QUERY - CRITICAL PERFORMANCE RULE

CRITICAL: Never Break Existing DOM Structure

When refactoring, optimizing, or improving block code, you MUST preserve the exact same DOM output. This is non-negotiable and applies across all phases of the AEM Three-Phase Loading strategy.

⚠️ ABSOLUTE REQUIREMENT: IDENTICAL MARKUP POST-OPTIMIZATION

The markup that is present today MUST be present after any performance optimizations. Class names, DOM order, element types, attributes, text content - EVERYTHING must be identical.

This means:

• Same CSS works without modification
• Same visual appearance with zero changes
• Same DOM inspector view when development is complete
• Same element hierarchy and nesting structure
• Same class names and attribute values
• Same text content and innerHTML structure

Why This Matters

• Thousands of pages are QA tested and business approved
• Existing CSS relies on specific selectors and class names
• Production sites depend on current DOM structure
• Breaking changes affect live customer experiences

✅ ALLOWED Performance Optimizations (All Phases)

// ✅ GOOD - Phase E: Simple initial structure for LCP
const basicStructure = createTag('div', { class: 'hero' });
el.append(basicStructure); // Same final DOM as before

// ✅ GOOD - Phase L: Progressive enhancement maintaining final structure
setTimeout(() => {
  const enhancement = createTag('div', { class: 'hero-overlay' });
  basicStructure.append(enhancement); // Identical to non-optimized version
}, 0);

// ✅ GOOD - Internal batching without DOM changes
const promises = items.map(processItem);
await Promise.all(promises);

// ✅ GOOD - Event listener optimization keeping same behavior
element.addEventListener('click', handler, { passive: true });

// ✅ GOOD - Lazy loading that produces identical final DOM
const observer = new IntersectionObserver(loadContent);

// ✅ GOOD - requestAnimationFrame for internal state management
requestAnimationFrame(() => updateInternalState());

// ✅ GOOD - Phase D: Delayed third-party content
setTimeout(() => {
  addAnalyticsPixel(); // Same DOM structure as before
}, 3000);