Legacy Client-Side Fetch Mutation (Laggy 400ms Spinner):
User clicks "Like" ──► [ Spinner 400ms ] ──► Server Responds ──► UI updates ❌

Next.js 16 Optimistic Server Action (0ms Instant Feedback):
User clicks "Like" ──► [ Instant UI Update (0ms) via useOptimistic() ] ✅
   │
   ▼ (Async Server Action executes in background on Edge)
   ├── Success: Database confirms mutation; UI seamlessly reconciles!
   └── Failure: Catches network error & automatically rolls back state with Toast alert!

┌─────────────────────────────────────────────────────────────────────────┐
│                 NEXT.JS 16 OPTIMISTIC MUTATION ENGINE                   │
├─────────────────┬───────────────────────────────────────────────────────┤
│ 1. `useAction-  │ Manages pending states, action errors, and returned   │
│    State()`     │ payload states without manual `try/catch` or `useState│
├─────────────────┼───────────────────────────────────────────────────────┤
│ 2. `useOpti-    │ Immediately renders projected state to the DOM while  │
│    mistic()`    │ the asynchronous Server Action Promise is in flight.  │
├─────────────────┼───────────────────────────────────────────────────────┤
│ 3. Server       │ Secure server-only async function running on Edge or  │
│    Action       │ Node.js runtime with automatic CSRF & input validation│
└─────────────────┴───────────────────────────────────────────────────────┘

// app/actions/tasks.ts - Edge Server Action
"use server";

import { revalidatePath } from "next/cache";

export interface Task {
  id: string;
  title: string;
  isCompleted: boolean;
}

export async function toggleTaskCompletionAction(
  prevState: any,
  formData: FormData
) {
  const taskId = formData.get("taskId") as string;
  const targetStatus = formData.get("status") === "true";

  try {
    // 1. Simulate Edge Database Update (e.g. Neon Postgres / Supabase / ScyllaDB)
    await new Promise((resolve) => setTimeout(resolve, 250)); // 250ms server latency

    // 2. Revalidate server cache
    revalidatePath("/dashboard/tasks");

    return { success: true, taskId, isCompleted: targetStatus };
  } catch (error) {
    return { success: false, error: "Database unreachable, changes reverted." };
  }
}

// components/TaskItem.tsx - Instant Optimistic UI
"use client";

import { useActionState, useOptimistic, startTransition } from "react";
import { toggleTaskCompletionAction, Task } from "@/app/actions/tasks";
import { CheckCircle2, Circle, Loader2 } from "lucide-react";

export function TaskItem({ task }: { task: Task }) {
  // 1. Hook for Server Action state management
  const [state, formAction, isPending] = useActionState(
    toggleTaskCompletionAction,
    null
  );

  // 2. Optimistic state hook: reflects instant toggle before server resolves
  const [optimisticTask, setOptimisticTask] = useOptimistic(
    task,
    (currentTask, newStatus: boolean) => ({
      ...currentTask,
      isCompleted: newStatus,
    })
  );

  const handleToggle = async (formData: FormData) => {
    const nextStatus = !optimisticTask.isCompleted;
    // Apply instant optimistic transition
    startTransition(async () => {
      setOptimisticTask(nextStatus);
      await formAction(formData);
    });
  };

  return (
    <form
      action={handleToggle}
      className="flex items-center justify-between p-4 bg-neutral-900 border border-neutral-800 rounded-xl hover:border-neutral-700 transition-all"
    >
      <input type="hidden" name="taskId" value={task.id} />
      <input type="hidden" name="status" value={String(!optimisticTask.isCompleted)} />

      <button
        type="submit"
        className="flex items-center gap-3 text-left w-full cursor-pointer group"
      >
        {optimisticTask.isCompleted ? (
          <CheckCircle2 className="w-5 h-5 text-red-500 flex-shrink-0 transition-transform group-hover:scale-110" />
        ) : (
          <Circle className="w-5 h-5 text-neutral-500 flex-shrink-0 transition-transform group-hover:scale-110" />
        )}
        <span
          className={`text-sm font-medium transition-all ${
            optimisticTask.isCompleted
              ? "line-through text-neutral-500"
              : "text-neutral-200"
          }`}
        >
          {optimisticTask.title}
        </span>
      </button>

      {isPending && (
        <span className="text-[10px] uppercase font-bold text-neutral-500 tracking-wider flex items-center gap-1">
          <Loader2 className="w-3 h-3 animate-spin text-red-500" />
          Syncing
        </span>
      )}
    </form>
  );
}

Interaction to Next Paint - INP (Milliseconds - Lower is Better):
┌─────────────────────────────────────────────────────────┐
│ Classic Full Form POST: ████████████████████ 890 ms     │
│ React Query Refetch:    ████████ 340 ms                 │
│ Next.js 16 Optimistic:  █ 8 ms (42x Faster!) 🏆         │
└─────────────────────────────────────────────────────────┘