From 2d52b1894b6f3aedb92fe6b5c39b235cf07c37ef Mon Sep 17 00:00:00 2001
From: rameel <rameel-b@hotmail.com>
Date: Wed, 9 Sep 2026 21:32:02 +0500
Subject: [PATCH 1/2] build: validate packaged library with Native AOT

---
 .github/workflows/publish.yml                 | 10 +-------
 .github/workflows/test.yml                    | 13 +++++++++--
 .../Ramstack.HtmxToolkit.csproj               |  3 +--
 .../TagHelpers/HtmxUrlTagHelper.cs            |  1 +
 .../Program.cs                                |  3 +++
 .../Ramstack.HtmxToolkit.AotValidation.csproj | 23 +++++++++++++++++++
 6 files changed, 40 insertions(+), 13 deletions(-)
 create mode 100644 tests/Ramstack.HtmxToolkit.AotValidation/Program.cs
 create mode 100644 tests/Ramstack.HtmxToolkit.AotValidation/Ramstack.HtmxToolkit.AotValidation.csproj

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 890a4b5..5d4e5c6 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -32,16 +32,8 @@ jobs:
       - name: Build
         run: dotnet build -c Release
 
-      - name: Build (AOT Analyze)
-        run: dotnet build src/Ramstack.HtmxToolkit/Ramstack.HtmxToolkit.csproj -c Release -f net8.0 --no-incremental --no-restore --warnaserror -p:EnableAotAnalysis=true
-
-      # NOTE: net8.0 is CI-only (AOT analysis above); the package ships net6.0 assets only.
-      # Do not "fix" this to pack all TargetFrameworks without also updating the csproj comment.
-      - name: Restore NuGet Package
-        run: dotnet restore src/Ramstack.HtmxToolkit/Ramstack.HtmxToolkit.csproj -p:TargetFrameworks=net6.0
-
       - name: Create NuGet Packages
-        run: dotnet pack src/Ramstack.HtmxToolkit/Ramstack.HtmxToolkit.csproj -c Release -o ./nuget --no-build --no-restore -p:TargetFrameworks=net6.0
+        run: dotnet pack src/Ramstack.HtmxToolkit/Ramstack.HtmxToolkit.csproj -c Release -o ./nuget --no-build --no-restore
 
       - name: NuGet login (OIDC)
         id: login
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index fe62c92..7e1f8e8 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -28,8 +28,17 @@ jobs:
       - name: Build (Release)
         run: dotnet build -c Release
 
-      - name: Build (AOT Analyze)
-        run: dotnet build src/Ramstack.HtmxToolkit/Ramstack.HtmxToolkit.csproj -c Release -f net8.0 --no-incremental --no-restore --warnaserror -p:EnableAotAnalysis=true
+      - name: Pack (AOT validation)
+        run: dotnet pack src/Ramstack.HtmxToolkit/Ramstack.HtmxToolkit.csproj -c Release -o "${RUNNER_TEMP}/aot-packages" --no-build --no-restore -p:MinVerVersionOverride=0.0.0-aot
+
+      - name: Restore (AOT validation)
+        run: dotnet restore tests/Ramstack.HtmxToolkit.AotValidation/Ramstack.HtmxToolkit.AotValidation.csproj -r linux-x64 --source "${RUNNER_TEMP}/aot-packages" --source https://api.nuget.org/v3/index.json
+
+      - name: Publish (AOT validation)
+        run: dotnet publish tests/Ramstack.HtmxToolkit.AotValidation/Ramstack.HtmxToolkit.AotValidation.csproj -c Release -r linux-x64 --no-restore --warnaserror
+
+      - name: Run (AOT validation)
+        run: tests/Ramstack.HtmxToolkit.AotValidation/bin/Release/net8.0/linux-x64/publish/Ramstack.HtmxToolkit.AotValidation
 
       - name: Test (Debug)
         run: dotnet test -c Debug --no-build
diff --git a/src/Ramstack.HtmxToolkit/Ramstack.HtmxToolkit.csproj b/src/Ramstack.HtmxToolkit/Ramstack.HtmxToolkit.csproj
index a90aaaa..fbc3f99 100644
--- a/src/Ramstack.HtmxToolkit/Ramstack.HtmxToolkit.csproj
+++ b/src/Ramstack.HtmxToolkit/Ramstack.HtmxToolkit.csproj
@@ -1,7 +1,6 @@
 <Project Sdk="Microsoft.NET.Sdk">
   <PropertyGroup>
-    <TargetFrameworks>net6.0;net8.0</TargetFrameworks>
-    <IsAotCompatible Condition="'$(TargetFramework)' == 'net8.0' and '$(EnableAotAnalysis)' == 'true'">true</IsAotCompatible>
+    <TargetFramework>net6.0</TargetFramework>
     <Description>Enables seamless integration of HTMX with ASP.NET Core (https://htmx.org).</Description>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
diff --git a/src/Ramstack.HtmxToolkit/TagHelpers/HtmxUrlTagHelper.cs b/src/Ramstack.HtmxToolkit/TagHelpers/HtmxUrlTagHelper.cs
index eea2798..eecb416 100644
--- a/src/Ramstack.HtmxToolkit/TagHelpers/HtmxUrlTagHelper.cs
+++ b/src/Ramstack.HtmxToolkit/TagHelpers/HtmxUrlTagHelper.cs
@@ -26,6 +26,7 @@ namespace Ramstack.HtmxToolkit.TagHelpers;
 [HtmlTargetElement(Attributes = HostAttributeName)]
 [HtmlTargetElement(Attributes = ProtocolAttributeName)]
 [HtmlTargetElement(Attributes = FragmentAttributeName)]
+[RequiresUnreferencedCode("Razor Page URL generation is not compatible with trimming.")]
 public sealed class HtmxUrlTagHelper(IUrlHelperFactory factory) : TagHelper
 {
     private const string ActionAttributeName = "hx-action";
diff --git a/tests/Ramstack.HtmxToolkit.AotValidation/Program.cs b/tests/Ramstack.HtmxToolkit.AotValidation/Program.cs
new file mode 100644
index 0000000..fc53e7c
--- /dev/null
+++ b/tests/Ramstack.HtmxToolkit.AotValidation/Program.cs
@@ -0,0 +1,3 @@
+using Ramstack.HtmxToolkit;
+
+Console.WriteLine(HtmxAssets.Hash);
diff --git a/tests/Ramstack.HtmxToolkit.AotValidation/Ramstack.HtmxToolkit.AotValidation.csproj b/tests/Ramstack.HtmxToolkit.AotValidation/Ramstack.HtmxToolkit.AotValidation.csproj
new file mode 100644
index 0000000..ed5c81a
--- /dev/null
+++ b/tests/Ramstack.HtmxToolkit.AotValidation/Ramstack.HtmxToolkit.AotValidation.csproj
@@ -0,0 +1,23 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <PublishAot>true</PublishAot>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <TrimmerSingleWarn>false</TrimmerSingleWarn>
+    <ILLinkTreatWarningsAsErrors>true</ILLinkTreatWarningsAsErrors>
+    <!-- CI restores this synthetic version from its runner-local package source. -->
+    <AotPackageVersion Condition="'$(AotPackageVersion)' == ''">0.0.0-aot</AotPackageVersion>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <FrameworkReference Include="Microsoft.AspNetCore.App" />
+    <PackageReference Include="Ramstack.HtmxToolkit" Version="$(AotPackageVersion)" />
+    <!-- Analyze every library method, including APIs not called by Program.cs. -->
+    <TrimmerRootAssembly Include="Ramstack.HtmxToolkit" />
+  </ItemGroup>
+
+</Project>

From 73f7a67ef9b0f41cd90ca7af7116a30a107082d6 Mon Sep 17 00:00:00 2001
From: rameel <rameel-b@hotmail.com>
Date: Thu, 10 Sep 2026 00:33:26 +0500
Subject: [PATCH 2/2] build: exclude the trim-incompatible URL tag helper from
 AOT validation

HtmxUrlTagHelper is marked [RequiresUnreferencedCode]; rooting the whole
assembly leaks IL2026 from the unannotated framework
UrlHelperExtensions.Page. Root the API surface through a descriptor that
leaves that tag helper out.
---
 .../Ramstack.HtmxToolkit.AotValidation.csproj |  2 +-
 .../TrimmerRoots.xml                          | 24 +++++++++++++++++++
 2 files changed, 25 insertions(+), 1 deletion(-)
 create mode 100644 tests/Ramstack.HtmxToolkit.AotValidation/TrimmerRoots.xml

diff --git a/tests/Ramstack.HtmxToolkit.AotValidation/Ramstack.HtmxToolkit.AotValidation.csproj b/tests/Ramstack.HtmxToolkit.AotValidation/Ramstack.HtmxToolkit.AotValidation.csproj
index ed5c81a..e1eb82e 100644
--- a/tests/Ramstack.HtmxToolkit.AotValidation/Ramstack.HtmxToolkit.AotValidation.csproj
+++ b/tests/Ramstack.HtmxToolkit.AotValidation/Ramstack.HtmxToolkit.AotValidation.csproj
@@ -17,7 +17,7 @@
     <FrameworkReference Include="Microsoft.AspNetCore.App" />
     <PackageReference Include="Ramstack.HtmxToolkit" Version="$(AotPackageVersion)" />
     <!-- Analyze every library method, including APIs not called by Program.cs. -->
-    <TrimmerRootAssembly Include="Ramstack.HtmxToolkit" />
+    <TrimmerRootDescriptor Include="TrimmerRoots.xml" />
   </ItemGroup>
 
 </Project>
diff --git a/tests/Ramstack.HtmxToolkit.AotValidation/TrimmerRoots.xml b/tests/Ramstack.HtmxToolkit.AotValidation/TrimmerRoots.xml
new file mode 100644
index 0000000..fa8b70e
--- /dev/null
+++ b/tests/Ramstack.HtmxToolkit.AotValidation/TrimmerRoots.xml
@@ -0,0 +1,24 @@
+<linker>
+  <!--
+    Roots the full API surface of Ramstack.HtmxToolkit so trimming and Native AOT analyze
+    every reachable member, even APIs that Program.cs never calls.
+
+    HtmxUrlTagHelper is intentionally excluded: it is marked [RequiresUnreferencedCode]
+    (Razor Page URL generation is trim-incompatible), and rooting it leaks IL2026 from the
+    unannotated framework UrlHelperExtensions. Everything else must stay AOT-clean.
+
+    When a new tag helper is added, list it here unless it is genuinely trim-incompatible.
+  -->
+  <assembly fullname="Ramstack.HtmxToolkit">
+    <namespace fullname="Ramstack.HtmxToolkit" />
+    <namespace fullname="Ramstack.HtmxToolkit.Collections" />
+    <namespace fullname="Ramstack.HtmxToolkit.Configuration" />
+    <namespace fullname="Ramstack.HtmxToolkit.Hosting" />
+    <namespace fullname="Ramstack.HtmxToolkit.Internal" />
+    <namespace fullname="Ramstack.HtmxToolkit.Serialization" />
+    <type fullname="Ramstack.HtmxToolkit.TagHelpers.HtmxConfigTagHelper" />
+    <type fullname="Ramstack.HtmxToolkit.TagHelpers.HtmxHeaderTagHelper" />
+    <type fullname="Ramstack.HtmxToolkit.TagHelpers.HtmxRequestTagHelper" />
+    <type fullname="Ramstack.HtmxToolkit.TagHelpers.HtmxValsTagHelper" />
+  </assembly>
+</linker>