SSR Hydration API

The hydration API provides fine-grained control over SSR mismatch detection, abort protocol, and recovery. Most apps only need initRuntime() — the rest is available for advanced use cases.

Hydration Lifecycle

1. startHydration() — begin hydration session

2. loadMangleMapFromDOM() — read the injected mangle map from the <script> tag

3. verifyMangleChecksum() — validate SHA-256 against data-sz-checksum

4. If invalid — abortHydration() preserves SSR HTML and CSS intact

5. If valid — React hydrates normally

6. endHydration() — close session, emit audit log

Non-negotiable

On checksum mismatch in production, abortHydration() is called automatically. React hydration is blocked. The server-rendered HTML and CSS remain intact so the user sees a correctly styled page.

This behavior is intentional and cannot be overridden in production builds.

Core Functions

startHydration()

Opens a hydration session. Call before any validation or React render.

function startHydration(): void

endHydration()

Closes the current hydration session.

function endHydration(): void

abortHydration()

Aborts hydration. Blocks React from taking over the DOM.

function abortHydration(): void

isHydrationAborted()

Returns true if abortHydration() has been called.

function isHydrationAborted(): boolean

isHydrating()

Returns true if a hydration session is active.

function isHydrating(): boolean

Mangle Map Verification

loadMangleMapFromDOM()

Reads the injected mangle map from the #__sz_mangle__ script tag in the DOM.

function loadMangleMapFromDOM(): MangleMap | null

type MangleMap = Record<string, string>; // { 'z': 'p-4', 'y': 'bg-blue-500' }

verifyMangleChecksum(map, checksum)

Computes SHA-256 of the mangle map and compares to the embedded checksum. Returns true if they match.

function verifyMangleChecksum(
  map: MangleMap,
  checksum: string
): boolean

verifyMangleMapIntegrity(map)

Validates the structure of a mangle map (non-empty, valid string values).

function verifyMangleMapIntegrity(map: MangleMap): boolean

validateHydrationClass(mangledClass, map)

Checks that a single mangled class exists in the mangle map.

function validateHydrationClass(
  mangledClass: string,
  map: MangleMap
): boolean

Error Inspection

getHydrationErrors()

Returns all recorded hydration errors for the current session.

function getHydrationErrors(): HydrationError[]

interface HydrationError {
  type: HydrationErrorType;
  message: string;
  class?: string;      // The mangled class that failed (if applicable)
  timestamp: number;
}

clearHydrationErrors()

Clears the error list. Useful for testing.

function clearHydrationErrors(): void

Error Types

type HydrationErrorType =
  | 'checksum_mismatch'  // SHA-256 does not match
  | 'missing_manifest'   // No mangle map in DOM
  | 'invalid_manifest'   // Mangle map is malformed
  | 'class_not_found'    // Mangled class has no mapping
  | 'token_invalid';     // Recovery token signature is invalid

Recovery Tokens

Recovery tokens allow trusted mangle maps to be accepted even when the main checksum check fails. Available in development only.

verifyRecoveryToken(token, map)

Verifies a recovery token against a mangle map.

function verifyRecoveryToken(
  token: string,
  map: MangleMap
): VerificationResult

interface VerificationResult {
  valid: boolean;
  mode: RecoveryMode;
  expiresAt?: number;
}

hasRecoveryToken()

Returns true if a recovery token is present in the DOM.

function hasRecoveryToken(): boolean

getRecoveryMode()

Returns the current recovery mode.

type RecoveryMode = 'none' | 'csr' | 'dev-only';
function getRecoveryMode(): RecoveryMode

enableCSRRecovery() / disableCSRRecovery() / isCSRRecoveryAllowed()

Manually enable or disable client-side recovery.

function enableCSRRecovery(): void
function disableCSRRecovery(): void
function isCSRRecoveryAllowed(): boolean

SSR Context

isSSREnvironment()

Returns true when running in an SSR context (no DOM available).

function isSSREnvironment(): boolean

getSSRContext()

Returns the current SSR context object.

function getSSRContext(): SSRContext | null

interface SSRContext {
  buildId: string;
  checksum: string;
  mangleMap: MangleMap;
}

Example: Manual Hydration Guard

For advanced control over the hydration process:

import {
  startHydration,
  endHydration,
  abortHydration,
  loadMangleMapFromDOM,
  verifyMangleChecksum,
  isHydrationAborted,
} from '@csszyx/runtime';

// In your app entry before React.hydrate()
startHydration();

const mangleMap = loadMangleMapFromDOM();
const checksum = document.documentElement.dataset.szChecksum;

if (!mangleMap || !verifyMangleChecksum(mangleMap, checksum)) {
  abortHydration();
}

if (!isHydrationAborted()) {
  // Safe to hydrate
  hydrateRoot(document.getElementById('root'), <App />);
}

endHydration();