import { createRoot } from 'react-dom/client';
import { StrictMode } from 'react';
import ApplicationShell from './components/ApplicationShell';

const mountNode = document.getElementById('app-root');

if (mountNode) {
  const rootInstance = createRoot(mountNode);
  
  rootInstance.render(
    <StrictMode>
      <ApplicationShell />
    </StrictMode>
  );

  // Graceful teardown for micro-frontends or dynamic routing
  export const unmountApplication = () => rootInstance.unmount();
}

import { useState, useTransition, useCallback } from 'react';
import type { ChangeEvent } from 'react';

interface FilterPanelProps {
  onFilterChange: (criteria: string) => void;
}

export function FilterPanel({ onFilterChange }: FilterPanelProps) {
  const [inputValue, setInputValue] = useState('');
  const [isComputing, startTransition] = useTransition();

  const handleInputChange = useCallback((event: ChangeEvent<HTMLInputElement>) => {
    const nextValue = event.target.value;
    
    // Urgent: input must reflect keystrokes immediately
    setInputValue(nextValue);

    // Non-urgent: defer expensive filtering logic
    startTransition(() => {
      onFilterChange(nextValue);
    });
  }, [onFilterChange]);

  return (
    <div className="filter-container">
      <input 
        type="text" 
        value={inputValue} 
        onChange={handleInputChange} 
        placeholder="Search inventory..."
        aria-busy={isComputing}
      />
      {isComputing && <span className="status-indicator">Updating results...</span>}
    </div>
  );
}

import { useState, useDeferredValue, useMemo } from 'react';

interface DataGr

idProps { rawDataset: Array<{ id: number; label: string; category: string }>; searchCriteria: string; }

export function DataGrid({ rawDataset, searchCriteria }: DataGridProps) { const deferredCriteria = useDeferredValue(searchCriteria);

const matchedRecords = useMemo(() => { const normalizedQuery = deferredCriteria.toLowerCase(); return rawDataset.filter(record => record.label.toLowerCase().includes(normalizedQuery) || record.category.toLowerCase().includes(normalizedQuery) ); }, [rawDataset, deferredCriteria]);

return ( <table> <thead> <tr> <th>ID</th> <th>Label</th> <th>Category</th> </tr> </thead> <tbody> {matchedRecords.map(record => ( <tr key={record.id}> <td>{record.id}</td> <td>{record.label}</td> <td>{record.category}</td> </tr> ))} </tbody> </table> ); }

**Architecture Rationale:** `useDeferredValue` creates a stable snapshot of the incoming prop that updates only when the scheduler has spare capacity. Unlike `useTransition`, it does not require wrapping setters, making it ideal for library consumers or deeply nested components. The `useMemo` dependency on the deferred value ensures the expensive filter runs only when the deferred snapshot changes, not on every parent render.

### Step 4: Opt-Out Synchronously When Required

Automatic batching groups all state updates into a single render cycle. When immediate DOM measurement is required after a state change, `flushSync` forces synchronous rendering.

```typescript
import { useState, flushSync } from 'react';
import { flushSync as flushSyncDOM } from 'react-dom';

interface MeasurementPanelProps {
  onHeightCalculated: (height: number) => void;
}

export function MeasurementPanel({ onHeightCalculated }: MeasurementPanelProps) {
  const [isVisible, setIsVisible] = useState(false);

  const triggerMeasurement = () => {
    flushSyncDOM(() => {
      setIsVisible(true);
    });
    
    const element = document.getElementById('dynamic-content');
    if (element) {
      const computedHeight = element.getBoundingClientRect().height;
      onHeightCalculated(computedHeight);
    }
  };

  return (
    <div>
      <button onClick={triggerMeasurement}>Measure Content</button>
      {isVisible && <div id="dynamic-content">Dynamic payload</div>}
    </div>
  );
}

Architecture Rationale: flushSync breaks automatic batching intentionally. It should be reserved for scenarios where DOM state must align with React state before the next JavaScript execution frame (e.g., measuring layout, focusing inputs, or integrating with third-party canvas libraries). Overuse negates concurrent benefits and reintroduces main-thread blocking.

Pitfall Guide

1. Wrapping Controlled Input Values in Transitions

Explanation: Developers sometimes wrap the entire onChange handler, including the input state setter, inside startTransition. This causes keystroke lag because the input value is deferred. Fix: Keep the input state update outside the transition. Only wrap the downstream computation or API call that depends on the input.

2. Treating isPending as a Network Loading State

Explanation: isPending indicates a concurrent transition is in progress, not that data is fetching. Using it to trigger spinner animations for async requests creates misleading UX. Fix: Reserve isPending for UI dimming, placeholder rendering, or disabling non-critical controls. Use dedicated loading states for network operations.

3. Overusing flushSync for Routine Updates

Explanation: Calling flushSync on every state change forces synchronous rendering, defeating automatic batching and concurrent scheduling. This causes layout thrashing and jank. Fix: Limit flushSync to cases requiring immediate DOM measurement or third-party library synchronization. Profile with React DevTools to verify batching behavior.

4. Confusing useTransition with useDeferredValue

Explanation: Both APIs defer work, but they operate at different levels. useTransition wraps state setters; useDeferredValue wraps incoming values or props. Mixing them leads to redundant deferrals or missed optimizations. Fix: Use useTransition when you control the state update. Use useDeferredValue when consuming a prop or value from a parent that you cannot modify.

5. Ignoring Hydration Mismatches in SSR

Explanation: Concurrent rendering can expose hydration mismatches if server and client trees diverge due to random values, timestamps, or non-deterministic renders. This causes content flicker and hydration failures. Fix: Use useId for stable element identifiers. Avoid generating random values or dates during render. Wrap non-deterministic content in Suspense boundaries with explicit fallbacks.

6. Batching Side Effects Incorrectly

Explanation: Automatic batching groups state updates, but useEffect still executes after each render cycle. Developers sometimes assume effects are batched, leading to stale closures or redundant API calls. Fix: Consolidate effect dependencies. If multiple state changes must trigger a single effect, use a single state object or useReducer to batch the logical update before the effect runs.

7. Assuming Concurrent Rendering Eliminates Virtualization

Explanation: Concurrency improves scheduling but does not reduce DOM node count. Rendering thousands of unvirtualized rows still causes memory pressure and paint bottlenecks. Fix: Combine concurrent transitions with windowing libraries (e.g., react-window, @tanstack/react-virtual). Use transitions to defer filter/sort logic, and virtualization to limit DOM nodes.

Production Bundle

Action Checklist

• Replace ReactDOM.render() with createRoot() and verify concurrent mode activation in React DevTools
• Audit state updates and wrap heavy computations or large dataset filters with useTransition
• Replace prop-driven expensive renders with useDeferredValue to prevent parent blocking
• Remove legacy ReactDOM.hydrate() calls and migrate to hydrateRoot() for SSR applications
• Audit flushSync usage and restrict it to DOM measurement or third-party integration points
• Add useId to all dynamically generated elements to prevent hydration mismatches
• Profile rendering with React DevTools Profiler to verify batching and transition interruptibility
• Implement isPending UI states for deferred transitions instead of network spinners

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Real-time search over 10k+ records	useTransition + useDeferredValue	Defers filtering computation while keeping input responsive	Low (CPU scheduling optimization)
Form validation with immediate feedback	Urgent state updates only	Validation must reflect user input instantly; deferral causes lag	None (baseline performance)
Dashboard metrics with heavy chart rendering	useTransition for data aggregation	Chart updates can be interrupted without breaking UX	Low (reduced main-thread blocking)
SSR hydration with dynamic content	hydrateRoot + Suspense boundaries	Ensures server/client tree alignment and graceful fallbacks	Medium (requires boundary structuring)
Third-party canvas/DOM library integration	flushSync + useLayoutEffect	Guarantees DOM state matches before external library reads	High (breaks batching, use sparingly)

Configuration Template

// src/infrastructure/react-root.ts
import { createRoot, hydrateRoot } from 'react-dom/client';
import { StrictMode, type ReactNode } from 'react';

interface RootConfig {
  container: HTMLElement;
  children: ReactNode;
  isHydration?: boolean;
}

export function initializeReactRoot({ container, children, isHydration = false }: RootConfig) {
  if (isHydration) {
    const root = hydrateRoot(container, <StrictMode>{children}</StrictMode>);
    return { root, unmount: () => root.unmount() };
  }

  const root = createRoot(container);
  root.render(<StrictMode>{children}</StrictMode>);
  
  return { root, unmount: () => root.unmount() };
}

// src/hooks/useConcurrentTransition.ts
import { useTransition, useCallback, type Dispatch, type SetStateAction } from 'react';

export function useConcurrentTransition<T>(
  setter: Dispatch<SetStateAction<T>>
) {
  const [isPending, startTransition] = useTransition();

  const deferredSetter = useCallback(
    (value: T | ((prev: T) => T)) => {
      startTransition(() => {
        setter(value);
      });
    },
    [setter]
  );

  return { isPending, deferredSetter };
}

Quick Start Guide

1. Upgrade and Mount: Replace ReactDOM.render() with createRoot() from react-dom/client. Verify concurrent mode is active in React DevTools (look for the concurrent badge).
2. Identify Heavy Updates: Locate state setters that trigger expensive computations, large list filters, or complex chart renders. Wrap them with useTransition.
3. Add Deferred Boundaries: For components receiving heavy props, replace direct prop usage with useDeferredValue. Connect the deferred value to useMemo or useCallback to prevent redundant calculations.
4. Validate Batching: Open React DevTools Profiler. Trigger multiple state updates across sync and async contexts. Confirm they render as a single commit. Use flushSync only if DOM measurement fails without it.
5. Deploy and Monitor: Ship the changes. Monitor main-thread blocking metrics and user interaction latency. Adjust transition boundaries based on real-world profiling data.