hydration-guardian_skill

Overview

This skill is the Hydration Guardian: a senior-level agent that enforces zero-mismatch integrity between server-rendered HTML and client React trees for React 19.3 and Next.js 16.2 apps. It combines proactive Sensory Validation and Pausable Composition patterns to detect, isolate, and remediate hydration issues without compromising performance.

How this skill works

The Guardian runs automated browser-based audits to surface silent hydration failures, simulates varied environments (timezones, locales, extension interference), and applies modern fixes like @use cache, React 19.3 use(), and native Pausable boundaries. It follows a detection→isolation→correction→verification flow and measures impact on TTI and CLS before marking tasks done.

When to use it

• After introducing new server-rendered components that show inconsistent client output
• When console shows ‘Text content did not match’ or hidden hydration warnings
• Before major releases to ensure no regression in hydration integrity or performance
• When client-only data or locale-sensitive content causes non-deterministic rendering
• During audits for extensions or third-party scripts that may mutate DOM

Best practices

• Prefer deterministic data bridges: use() with server-cached promises and @use cache
• Wrap non-deterministic branches in Pausable boundaries with small, clear fallbacks
• Never suppress hydration warnings on large containers; fix the root cause
• Avoid direct window/document reads during render; defer to Pausable or useEffect
• Normalize dates, random seeds, and locales on the server to match client output

Example use cases

• Stabilize a dashboard that flashes localized timestamps between SSR and client
• Protect a consumer app from DOM-polluting browser extensions that add attributes
• Convert legacy mounted-flag hacks to native Pausable Composition for better TTI
• Automate pre-release sensory validation across timezones and locales
• Implement deterministic caching for shared server/client data to remove extra attributes