config: document request restrictions of the no-cors fetch mode

docs/articles/configuration-v4.md

@@ -41,7 +41,13 @@ builder.Services.AddHtmxToolkit(options =>
 |---|---|
 | `SameOrigin` | Allow only same-origin requests |
 | `Cors` | Allow cross-origin requests through CORS |
-| `NoCors` | Allow restricted opaque cross-origin responses, which normally cannot be swapped |
+| `NoCors` | Allow restricted cross-origin requests that produce opaque responses |
+
+In `NoCors` mode, the browser allows only `GET`, `HEAD`, and `POST`; other methods raise `htmx:error`.
+It also removes request headers that are not CORS-safelisted, even for same-origin requests: the server receives
+no `HX-*` headers or `hx-headers` values, and no antiforgery token sent in a header. `IsHtmxRequest()` returns `false`,
+and `[HtmxRequest]` does not match. A cross-origin response is opaque, so HTMX cannot read its headers
+and swaps an empty body into the target.
 
 Changing this setting does not configure CORS on the ASP.NET Core server.
 

src/Ramstack.HtmxToolkit/Configuration/HtmxFetchMode.cs

@@ -27,9 +27,20 @@ public enum HtmxFetchMode
     /// Allows restricted cross-origin requests that produce opaque responses.
     /// </summary>
     /// <remarks>
-    /// An opaque response has status 0, and its headers and body are not accessible.
-    /// HTMX cannot read <c>HX-*</c> response headers, does not treat the response as an error,
-    /// and swaps the empty body into the target.
+    /// <para>
+    ///   The browser allows only the <c>GET</c>, <c>HEAD</c>, and <c>POST</c> methods in this mode.
+    ///   For other methods, <c>fetch</c> throws, and HTMX raises the <c>htmx:error</c> event.
+    /// </para>
+    /// <para>
+    ///   The browser also removes request headers that are not CORS-safelisted, even for same-origin requests.
+    ///   This includes all <c>HX-*</c> headers, values from <c>hx-headers</c>, and the antiforgery token
+    ///   when it is sent in a header. As a result, the server does not recognize the request as an HTMX request.
+    /// </para>
+    /// <para>
+    ///   A cross-origin response is opaque: its status is 0, and its headers and body are not accessible.
+    ///   HTMX cannot read <c>HX-*</c> response headers, does not treat the response as an error,
+    ///   and swaps the empty body into the target. A same-origin response is not opaque.
+    /// </para>
     /// </remarks>
     NoCors
 }