From 9046c93b484b0ff8d31c56754221b14cc5441b0f Mon Sep 17 00:00:00 2001
From: rameel <rameel-b@hotmail.com>
Date: Tue, 13 Oct 2026 22:07:22 +0500
Subject: [PATCH] config: document request restrictions of the no-cors fetch
 mode

In no-cors mode, the browser rejects methods other than GET, HEAD, and
POST and drops request headers that are not CORS-safelisted, including
HX-* headers, even for same-origin requests.

The XML remarks and the HTMX 4.x configuration guide described only
opaque responses, which apply only to cross-origin requests.
---
 docs/articles/configuration-v4.md               |  8 +++++++-
 .../Configuration/HtmxFetchMode.cs              | 17 ++++++++++++++---
 2 files changed, 21 insertions(+), 4 deletions(-)

diff --git a/docs/articles/configuration-v4.md b/docs/articles/configuration-v4.md
index ecede10..bbec919 100644
--- a/docs/articles/configuration-v4.md
+++ b/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.
 
diff --git a/src/Ramstack.HtmxToolkit/Configuration/HtmxFetchMode.cs b/src/Ramstack.HtmxToolkit/Configuration/HtmxFetchMode.cs
index 4fe6565..013c7bc 100644
--- a/src/Ramstack.HtmxToolkit/Configuration/HtmxFetchMode.cs
+++ b/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
 }