Selective Hydration and Interactive Prioritization in Suspense

[ Server HTML Streamed to Browser ]
  ├── <Header />                  --> JS chunk loaded: [ Hydrated (Interactive)   ]
  ├── <Suspense> (Product Island)  --> JS chunk loaded: [ Background Hydration...  ]
  └── <Suspense> (Reviews Island)  --> JS chunk in transit: [ Awaiting Network... ]

+----------------- [ User Action: CLICK! ] -----------------+
User clicks "Add to Cart" inside [ Product Island ]!
  1. Global root event capture on document intercepts click/pointerdown.
  2. Fiber engine determines that target node is currently dehydrated.
  3. React escalates [ Product Island ] priority to SyncLane.
  4. Ongoing background idle work is interrupted; Product Island hydrates synchronously.
  5. The Event Replay mechanism re-dispatches the captured click event.
  6. Cart state updates with zero perceptible lag for the user!
+-----------------------------------------------------------+

interface QueuedDiscreteEvent {
  blockedOn: FiberNode | null; // Fiber node whose hydration blocks this event
  domEventName: string;
  event: Event;
  targetContainer: Node;
}

const queuedDiscreteEvents: QueuedDiscreteEvent[] = [];

export function dispatchDiscreteEvent(
  domEventName: string,
  event: Event,
  targetContainer: Node
): void {
  const target = event.target as Node | null;
  const targetFiber = getFiberFromNode(target);

  // If target Fiber is still dehydrated
  if (targetFiber !== null && isFiberDehydrated(targetFiber)) {
    // 1. Prevent default native actions and propagation
    event.preventDefault();
    event.stopPropagation();

    // 2. Buffer event in replay queue
    queuedDiscreteEvents.push({
      blockedOn: targetFiber,
      domEventName,
      event,
      targetContainer,
    });

    // 3. PRIORITY ESCALATION: Force immediate hydration of target subtree!
    // Fiber lane promoted from IdleLane to SyncLane
    escalateHydrationPriority(targetFiber);
    return;
  }

  // Standard synchronous dispatch for hydrated targets
  dispatchEvent(domEventName, event, targetContainer);
}

export function replayDiscreteEventsForFiber(hydratedFiber: FiberNode): void {
  for (let i = 0; i < queuedDiscreteEvents.length; i++) {
    const queued = queuedDiscreteEvents[i];
    if (queued.blockedOn === hydratedFiber) {
      // Re-dispatch buffered event on live, interactive DOM
      queued.targetContainer.dispatchEvent(queued.event);
      queuedDiscreteEvents.splice(i, 1);
      i--;
    }
  }
}

import React, { Suspense, lazy, useState } from 'react';

// Code-split interactive widgets into isolated JavaScript chunks
const DynamicColorCustomizer = lazy(() => import('./DynamicColorCustomizer'));
const HeavyReviewSection = lazy(() => import('./HeavyReviewSection'));
const InteractiveSimilarProducts = lazy(() => import('./InteractiveSimilarProducts'));

interface ProductProps {
  id: string;
  name: string;
  price: number;
  initialStock: number;
}

// 1. Critical Interactive Component: Purchase Panel
function BuyActionPanel({ price, initialStock }: { price: number; initialStock: number }) {
  const [stock, setStock] = useState(initialStock);
  const [isAdded, setIsAdded] = useState(false);

  const handlePurchase = () => {
    if (stock > 0) {
      setStock((s) => s - 1);
      setIsAdded(true);
    }
  };

  return (
    <div className="p-4 bg-bg-elevated border border-border rounded-lg space-y-3">
      <div className="flex justify-between items-center">
        <span className="text-2xl font-bold text-accent-cyan">${price}</span>
        <span className="text-xs text-text-muted">In Stock: {stock} units</span>
      </div>
      <button
        type="button"
        onClick={handlePurchase}
        disabled={stock === 0}
        className="w-full py-3 bg-accent-cyan text-bg-surface font-bold rounded-md hover:opacity-90 disabled:opacity-40 transition-opacity"
      >
        {isAdded ? 'Added to Cart!' : 'Buy Now'}
      </button>
    </div>
  );
}

export function ProductCommerceView({ product }: { product: ProductProps }) {
  return (
    <div className="max-w-4xl mx-auto p-6 space-y-8">
      <header className="space-y-2">
        <h1 className="text-3xl font-extrabold text-text-primary">{product.name}</h1>
        <p className="text-sm text-text-muted">SKU: {product.id}</p>
      </header>

      {/* 
        ZONE 1: Critical purchase block.
        Not wrapped in lazy; hydrates first with immediate priority!
      */}
      <BuyActionPanel price={product.price} initialStock={product.initialStock} />

      {/* 
        ZONE 2: Color Customizer.
        Isolated by Suspense. If clicked prematurely, React escalates
        its priority to SyncLane immediately!
      */}
      <Suspense fallback={<div className="h-24 bg-bg-elevated/40 rounded animate-pulse" />}>
        <DynamicColorCustomizer productId={product.id} />
      </Suspense>

      {/* 
        ZONE 3: Heavy reviews section.
        Hydrates in the background (IdleLane) without delaying button responsiveness.
      */}
      <Suspense fallback={<div className="h-64 bg-bg-elevated/40 rounded animate-pulse" />}>
        <HeavyReviewSection productId={product.id} />
      </Suspense>

      {/* ZONE 4: Recommendations */}
      <Suspense fallback={<div className="h-48 bg-bg-elevated/40 rounded animate-pulse" />}>
        <InteractiveSimilarProducts productId={product.id} />
      </Suspense>
    </div>
  );
}

[ Page: Root Document ]
  ├── <Header />                  --> Hydration successful: Server DOM preserved
  ├── <Suspense> (Widget Island)  --> ERROR: Hydration Mismatch!
  │                                   React locally resets ONLY this boundary
  │                                   and client-renders this isolated slice.
  └── <Footer />                  --> Hydration successful: Server DOM preserved