From fdb1d71e507bcf9b10ce74528f00e735006cdf11 Mon Sep 17 00:00:00 2001
From: Wilmer Arambula <terabytesoftw@gmail.com>
Date: Mon, 24 Aug 2026 12:00:52 -0400
Subject: [PATCH 1/2] docs: add class-level PHPDoc for the framework-neutral
 Vite APIs.

---
 CHANGELOG.md                                  |  1 +
 src/Asset/AssetCollection.php                 | 71 ++++++++++++---
 src/Asset/InlineModule.php                    |  8 ++
 src/Asset/ModulePreload.php                   | 13 +++
 src/Asset/ModuleScript.php                    | 13 +++
 src/Asset/Stylesheet.php                      | 13 +++
 .../DevelopmentConfiguration.php              | 23 ++++-
 src/Configuration/ProductionConfiguration.php | 23 +++--
 .../InlineModuleProviderInterface.php         | 12 +++
 src/Exception/ConfigurationException.php      |  3 +
 src/Exception/EntrypointNotFoundException.php |  3 +
 src/Exception/HtmlRenderingException.php      |  3 +
 src/Exception/InvalidEntrypointException.php  |  3 +
 src/Exception/InvalidManifestException.php    |  3 +
 src/Exception/ManifestException.php           |  3 +
 src/Exception/ManifestNotFoundException.php   |  3 +
 src/Exception/ManifestReadException.php       |  3 +
 src/Exception/Message.php                     | 19 ++--
 src/Html/HtmlRenderOptions.php                | 39 ++++++--
 src/Html/HtmlRenderer.php                     | 58 +++++++++++-
 src/Manifest/Manifest.php                     | 13 ++-
 src/Manifest/ManifestChunk.php                | 21 ++++-
 src/Manifest/ManifestLoader.php               | 88 ++++++++++++++++++-
 src/Resolver/AssetResolverInterface.php       | 15 +++-
 src/Resolver/DevelopmentAssetResolver.php     | 20 +++++
 src/Resolver/ManifestAssetResolver.php        | 77 ++++++++++++++--
 src/Support/EntrypointNormalizer.php          | 16 +++-
 src/Support/Path.php                          | 30 +++++++
 src/Support/Url.php                           | 80 +++++++++++++++++
 src/Vite.php                                  | 59 ++++++++++++-
 tests/AssetCollectionTest.php                 |  2 +-
 tests/ConfigurationTest.php                   |  2 +-
 .../CapturingInlineModuleProviderStub.php     | 35 ++++++++
 tests/Fixture/UnsupportedAssetStub.php        | 14 +++
 .../CapturingInlineModuleProviderStub.php     | 20 -----
 tests/Fixtures/UnsupportedAssetStub.php       |  9 --
 tests/HtmlRendererTest.php                    |  1 +
 tests/ManifestLoaderTest.php                  |  2 +-
 tests/Provider/ConfigurationProvider.php      |  2 -
 tests/Provider/HtmlRendererProvider.php       |  2 -
 tests/Provider/ManifestLoaderProvider.php     |  3 -
 tests/Provider/UrlProvider.php                |  2 -
 tests/ViteDevelopmentTest.php                 |  2 +-
 tests/ViteProductionTest.php                  | 14 ++-
 44 files changed, 733 insertions(+), 113 deletions(-)
 create mode 100644 tests/Fixture/CapturingInlineModuleProviderStub.php
 create mode 100644 tests/Fixture/UnsupportedAssetStub.php
 delete mode 100644 tests/Fixtures/CapturingInlineModuleProviderStub.php
 delete mode 100644 tests/Fixtures/UnsupportedAssetStub.php

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1b757f7..a270a05 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,3 +8,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## 0.1.0 Under development
 
 - feat: added a framework-agnostic Vite facade with explicit development and production configuration.
+- docs: add class-level PHPDoc for the framework-neutral Vite APIs.
diff --git a/src/Asset/AssetCollection.php b/src/Asset/AssetCollection.php
index 34a5119..abde8a2 100644
--- a/src/Asset/AssetCollection.php
+++ b/src/Asset/AssetCollection.php
@@ -21,12 +21,15 @@
 final readonly class AssetCollection implements Countable, IteratorAggregate
 {
     /**
-     * @var list<AssetInterface>
+     * @var list<AssetInterface> Accepted assets in insertion order, with per-type duplicates removed.
      */
     private array $assets;
 
     /**
-     * @param iterable<AssetInterface> $assets
+     * @param iterable<AssetInterface> $assets Assets to collect.
+     *
+     * @throws ConfigurationException if a value does not implement {@see AssetInterface}, or implements it without
+     * being one of the four supported asset types.
      */
     public function __construct(iterable $assets = [])
     {
@@ -52,25 +55,45 @@ public function __construct(iterable $assets = [])
     }
 
     /**
-     * @return list<AssetInterface>
+     * Returns every collected asset in insertion order, regardless of type.
+     *
+     * @return list<AssetInterface> The collected assets.
      */
     public function all(): array
     {
         return $this->assets;
     }
 
-    public function append(AssetInterface ...$assets): self
+    /**
+     * Returns a new collection with the supplied assets added after the current ones.
+     *
+     * The receiver is left untouched; deduplication is re-applied across the combined sequence.
+     *
+     * @param AssetInterface ...$assets Assets to add at the end.
+     *
+     * @throws ConfigurationException if an asset is not one of the four supported types.
+     *
+     * @return AssetCollection A new collection holding both sequences.
+     */
+    public function append(AssetInterface ...$assets): AssetCollection
     {
         return new self([...$this->assets, ...$assets]);
     }
 
+    /**
+     * Counts the collected assets after deduplication.
+     *
+     * @return int<0, max> Number of assets in the collection.
+     */
     public function count(): int
     {
         return count($this->assets);
     }
 
     /**
-     * @return Traversable<int, AssetInterface>
+     * Iterates over the collected assets in insertion order.
+     *
+     * @return Traversable<int, AssetInterface> Iterator over the collected assets.
      */
     public function getIterator(): Traversable
     {
@@ -78,7 +101,9 @@ public function getIterator(): Traversable
     }
 
     /**
-     * @return list<InlineModule>
+     * Filters the collection down to its inline modules.
+     *
+     * @return list<InlineModule> Inline modules in insertion order.
      */
     public function inlineModules(): array
     {
@@ -94,7 +119,9 @@ public function inlineModules(): array
     }
 
     /**
-     * @return list<ModulePreload>
+     * Filters the collection down to its module-preload hints.
+     *
+     * @return list<ModulePreload> Module preloads in insertion order.
      */
     public function modulePreloads(): array
     {
@@ -110,7 +137,9 @@ public function modulePreloads(): array
     }
 
     /**
-     * @return list<ModuleScript>
+     * Filters the collection down to its module scripts.
+     *
+     * @return list<ModuleScript> Module scripts in insertion order.
      */
     public function moduleScripts(): array
     {
@@ -125,13 +154,26 @@ public function moduleScripts(): array
         return $assets;
     }
 
-    public function prepend(AssetInterface ...$assets): self
+    /**
+     * Returns a new collection with the supplied assets added before the current ones.
+     *
+     * The receiver is left untouched; deduplication is re-applied across the combined sequence.
+     *
+     * @param AssetInterface ...$assets Assets to add at the beginning.
+     *
+     * @throws ConfigurationException if an asset is not one of the four supported types.
+     *
+     * @return AssetCollection A new collection holding both sequences.
+     */
+    public function prepend(AssetInterface ...$assets): AssetCollection
     {
         return new self([...$assets, ...$this->assets]);
     }
 
     /**
-     * @return list<Stylesheet>
+     * Filters the collection down to its stylesheets.
+     *
+     * @return list<Stylesheet> Stylesheets in insertion order.
      */
     public function stylesheets(): array
     {
@@ -147,7 +189,14 @@ public function stylesheets(): array
     }
 
     /**
-     * @return InlineModule|ModulePreload|ModuleScript|Stylesheet
+     * Narrows an arbitrary value to one of the four supported asset types.
+     *
+     * @param mixed $asset Value taken from the incoming iterable.
+     *
+     * @throws ConfigurationException if the value does not implement {@see AssetInterface}, or implements it without
+     * being a supported type.
+     *
+     * @return InlineModule|ModulePreload|ModuleScript|Stylesheet The narrowed asset.
      */
     private function requireAsset(mixed $asset): AssetInterface
     {
diff --git a/src/Asset/InlineModule.php b/src/Asset/InlineModule.php
index 2baab0c..5c8437d 100644
--- a/src/Asset/InlineModule.php
+++ b/src/Asset/InlineModule.php
@@ -8,8 +8,16 @@
 
 use function trim;
 
+/**
+ * Represents validated inline JavaScript module source.
+ */
 final readonly class InlineModule implements AssetInterface
 {
+    /**
+     * @param string $source JavaScript module source rendered inside a `<script type="module">` element.
+     *
+     * @throws ConfigurationException if the source is empty or contains only whitespace.
+     */
     public function __construct(public string $source)
     {
         if (trim($source) === '') {
diff --git a/src/Asset/ModulePreload.php b/src/Asset/ModulePreload.php
index 81c5d33..ffbe75d 100644
--- a/src/Asset/ModulePreload.php
+++ b/src/Asset/ModulePreload.php
@@ -4,12 +4,25 @@
 
 namespace PHPForge\Vite\Asset;
 
+use PHPForge\Vite\Exception\ConfigurationException;
 use PHPForge\Vite\Support\Url;
 
+/**
+ * Represents a validated module-preload asset URL.
+ */
 final readonly class ModulePreload implements AssetInterface
 {
+    /**
+     * Absolute or relative URL of the chunk to preload.
+     */
     public string $url;
 
+    /**
+     * @param string $url Asset URL emitted as the `href` of a `modulepreload` link.
+     *
+     * @throws ConfigurationException if the URL is empty, malformed, protocol-relative, or uses a scheme other than
+     * HTTP(S).
+     */
     public function __construct(string $url)
     {
         $this->url = Url::requireSafeAssetUrl($url);
diff --git a/src/Asset/ModuleScript.php b/src/Asset/ModuleScript.php
index bb1e600..3af2a08 100644
--- a/src/Asset/ModuleScript.php
+++ b/src/Asset/ModuleScript.php
@@ -4,12 +4,25 @@
 
 namespace PHPForge\Vite\Asset;
 
+use PHPForge\Vite\Exception\ConfigurationException;
 use PHPForge\Vite\Support\Url;
 
+/**
+ * Represents a validated JavaScript module asset URL.
+ */
 final readonly class ModuleScript implements AssetInterface
 {
+    /**
+     * Absolute or relative URL of the JavaScript module to execute.
+     */
     public string $url;
 
+    /**
+     * @param string $url Asset URL emitted as the `src` of a `<script type="module">` element.
+     *
+     * @throws ConfigurationException if the URL is empty, malformed, protocol-relative, or uses a scheme other than
+     * HTTP(S).
+     */
     public function __construct(string $url)
     {
         $this->url = Url::requireSafeAssetUrl($url);
diff --git a/src/Asset/Stylesheet.php b/src/Asset/Stylesheet.php
index 6e2dfb2..ae49170 100644
--- a/src/Asset/Stylesheet.php
+++ b/src/Asset/Stylesheet.php
@@ -4,12 +4,25 @@
 
 namespace PHPForge\Vite\Asset;
 
+use PHPForge\Vite\Exception\ConfigurationException;
 use PHPForge\Vite\Support\Url;
 
+/**
+ * Represents a validated stylesheet asset URL.
+ */
 final readonly class Stylesheet implements AssetInterface
 {
+    /**
+     * Absolute or relative URL of the stylesheet to link.
+     */
     public string $url;
 
+    /**
+     * @param string $url Asset URL emitted as the `href` of a `stylesheet` link.
+     *
+     * @throws ConfigurationException if the URL is empty, malformed, protocol-relative, or uses a scheme other than
+     * HTTP(S).
+     */
     public function __construct(string $url)
     {
         $this->url = Url::requireSafeAssetUrl($url);
diff --git a/src/Configuration/DevelopmentConfiguration.php b/src/Configuration/DevelopmentConfiguration.php
index 729c74c..622dc8c 100644
--- a/src/Configuration/DevelopmentConfiguration.php
+++ b/src/Configuration/DevelopmentConfiguration.php
@@ -13,14 +13,24 @@
  */
 final readonly class DevelopmentConfiguration
 {
+    /**
+     * Normalized development-server URL, without a trailing separator.
+     */
     public string $devServerUrl;
+
     /**
-     * @var list<InlineModuleProviderInterface>
+     * @var list<InlineModuleProviderInterface> Providers emitted, in order, before the Vite client.
      */
     public array $inlineModuleProviders;
 
     /**
-     * @param list<InlineModuleProviderInterface> $inlineModuleProviders
+     * @param string $devServerUrl Absolute HTTP(S) URL of the running Vite development server.
+     * @param bool $includeViteClient Whether the `@vite/client` module script is emitted.
+     * @param list<InlineModuleProviderInterface> $inlineModuleProviders Providers of application-owned inline
+     * modules that must run before the Vite client.
+     *
+     * @throws ConfigurationException if the development-server URL is not an absolute HTTP(S) URL, or if a provider
+     * does not implement {@see InlineModuleProviderInterface}.
      */
     public function __construct(
         string $devServerUrl,
@@ -28,13 +38,18 @@ public function __construct(
         array $inlineModuleProviders = [],
     ) {
         $this->devServerUrl = Url::normalizeDevServerUrl($devServerUrl);
+
         $this->inlineModuleProviders = $this->normalizeProviders($inlineModuleProviders);
     }
 
     /**
-     * @param iterable<mixed> $providers
+     * Rejects any provider that does not satisfy the contract, and reindexes the survivors as a list.
+     *
+     * @param iterable<mixed> $providers Raw providers supplied by the application.
+     *
+     * @throws ConfigurationException if a value does not implement {@see InlineModuleProviderInterface}.
      *
-     * @return list<InlineModuleProviderInterface>
+     * @return list<InlineModuleProviderInterface> Providers in the order supplied.
      */
     private function normalizeProviders(iterable $providers): array
     {
diff --git a/src/Configuration/ProductionConfiguration.php b/src/Configuration/ProductionConfiguration.php
index 230a2fb..7d51775 100644
--- a/src/Configuration/ProductionConfiguration.php
+++ b/src/Configuration/ProductionConfiguration.php
@@ -4,6 +4,7 @@
 
 namespace PHPForge\Vite\Configuration;
 
+use PHPForge\Vite\Exception\ConfigurationException;
 use PHPForge\Vite\Support\{Path, Url};
 
 /**
@@ -11,14 +12,26 @@
  */
 final readonly class ProductionConfiguration
 {
+    /**
+     * Normalized base URL prefixed to every emitted asset path, without a trailing separator.
+     */
     public string $assetBaseUrl;
+
+    /**
+     * Validated absolute path to the Vite build manifest.
+     */
     public string $manifestPath;
 
-    public function __construct(
-        string $manifestPath,
-        string $assetBaseUrl,
-        public bool $modulePreload = true,
-    ) {
+    /**
+     * @param string $manifestPath Absolute path to the manifest emitted by the Vite build.
+     * @param string $assetBaseUrl Public base URL of the build output, absolute or relative.
+     * @param bool $modulePreload Whether `modulepreload` hints are emitted for transitive imports.
+     *
+     * @throws ConfigurationException if the manifest path is not absolute, or if the base URL is malformed,
+     * protocol-relative, carries a query or fragment, or uses a scheme other than HTTP(S).
+     */
+    public function __construct(string $manifestPath, string $assetBaseUrl, public bool $modulePreload = true)
+    {
         $this->manifestPath = Path::requireAbsolute($manifestPath, 'manifestPath');
         $this->assetBaseUrl = Url::normalizeAssetBaseUrl($assetBaseUrl);
     }
diff --git a/src/Development/InlineModuleProviderInterface.php b/src/Development/InlineModuleProviderInterface.php
index 13950fd..441af78 100644
--- a/src/Development/InlineModuleProviderInterface.php
+++ b/src/Development/InlineModuleProviderInterface.php
@@ -5,11 +5,23 @@
 namespace PHPForge\Vite\Development;
 
 use PHPForge\Vite\Asset\InlineModule;
+use PHPForge\Vite\Exception\ConfigurationException;
 
 /**
  * Provides application-owned inline modules that must run before the Vite client.
  */
 interface InlineModuleProviderInterface
 {
+    /**
+     * Builds the inline module to emit ahead of the Vite client and the configured entrypoints.
+     *
+     * Implementations own the module source; the package only positions the result in the resolved asset order.
+     *
+     * @param string $devServerUrl Normalized development-server URL, without a trailing separator.
+     *
+     * @throws ConfigurationException if the produced source is empty or contains only whitespace.
+     *
+     * @return InlineModule Inline module rendered before the Vite client.
+     */
     public function provide(string $devServerUrl): InlineModule;
 }
diff --git a/src/Exception/ConfigurationException.php b/src/Exception/ConfigurationException.php
index 4142495..0d022a6 100644
--- a/src/Exception/ConfigurationException.php
+++ b/src/Exception/ConfigurationException.php
@@ -6,4 +6,7 @@
 
 use InvalidArgumentException;
 
+/**
+ * Reports invalid Vite integration configuration.
+ */
 class ConfigurationException extends InvalidArgumentException implements ViteException {}
diff --git a/src/Exception/EntrypointNotFoundException.php b/src/Exception/EntrypointNotFoundException.php
index 734a4ca..8cd0fd2 100644
--- a/src/Exception/EntrypointNotFoundException.php
+++ b/src/Exception/EntrypointNotFoundException.php
@@ -4,4 +4,7 @@
 
 namespace PHPForge\Vite\Exception;
 
+/**
+ * Reports an entrypoint missing from a loaded Vite manifest.
+ */
 final class EntrypointNotFoundException extends ManifestException {}
diff --git a/src/Exception/HtmlRenderingException.php b/src/Exception/HtmlRenderingException.php
index 5a1fc61..b761b56 100644
--- a/src/Exception/HtmlRenderingException.php
+++ b/src/Exception/HtmlRenderingException.php
@@ -6,4 +6,7 @@
 
 use InvalidArgumentException;
 
+/**
+ * Reports unsafe or unsupported HTML rendering options.
+ */
 final class HtmlRenderingException extends InvalidArgumentException implements ViteException {}
diff --git a/src/Exception/InvalidEntrypointException.php b/src/Exception/InvalidEntrypointException.php
index bc6e587..64348df 100644
--- a/src/Exception/InvalidEntrypointException.php
+++ b/src/Exception/InvalidEntrypointException.php
@@ -4,4 +4,7 @@
 
 namespace PHPForge\Vite\Exception;
 
+/**
+ * Reports an invalid Vite entrypoint value.
+ */
 final class InvalidEntrypointException extends ConfigurationException {}
diff --git a/src/Exception/InvalidManifestException.php b/src/Exception/InvalidManifestException.php
index 4922534..8c97049 100644
--- a/src/Exception/InvalidManifestException.php
+++ b/src/Exception/InvalidManifestException.php
@@ -4,4 +4,7 @@
 
 namespace PHPForge\Vite\Exception;
 
+/**
+ * Reports malformed or inconsistent Vite manifest data.
+ */
 final class InvalidManifestException extends ManifestException {}
diff --git a/src/Exception/ManifestException.php b/src/Exception/ManifestException.php
index 445e1db..d252f01 100644
--- a/src/Exception/ManifestException.php
+++ b/src/Exception/ManifestException.php
@@ -6,4 +6,7 @@
 
 use RuntimeException;
 
+/**
+ * Base exception for Vite manifest loading and validation failures.
+ */
 class ManifestException extends RuntimeException implements ViteException {}
diff --git a/src/Exception/ManifestNotFoundException.php b/src/Exception/ManifestNotFoundException.php
index da269d6..f86b19a 100644
--- a/src/Exception/ManifestNotFoundException.php
+++ b/src/Exception/ManifestNotFoundException.php
@@ -4,4 +4,7 @@
 
 namespace PHPForge\Vite\Exception;
 
+/**
+ * Reports a configured Vite manifest path that does not exist.
+ */
 final class ManifestNotFoundException extends ManifestException {}
diff --git a/src/Exception/ManifestReadException.php b/src/Exception/ManifestReadException.php
index b95770d..0b488c6 100644
--- a/src/Exception/ManifestReadException.php
+++ b/src/Exception/ManifestReadException.php
@@ -4,4 +4,7 @@
 
 namespace PHPForge\Vite\Exception;
 
+/**
+ * Reports a Vite manifest that cannot be read from disk.
+ */
 final class ManifestReadException extends ManifestException {}
diff --git a/src/Exception/Message.php b/src/Exception/Message.php
index 3d7d822..a305d5f 100644
--- a/src/Exception/Message.php
+++ b/src/Exception/Message.php
@@ -95,8 +95,8 @@ enum Message: string
      *
      * Format: "Each development inline module provider must implement InlineModuleProviderInterface."
      */
-    case DEVELOPMENT_INLINE_MODULE_PROVIDER_INVALID
-        = 'Each development inline module provider must implement InlineModuleProviderInterface.';
+    case DEVELOPMENT_INLINE_MODULE_PROVIDER_INVALID = 'Each development inline module provider must implement '
+        . 'InlineModuleProviderInterface.';
 
     /**
      * The development server URL is not an absolute HTTP(S) URL.
@@ -201,8 +201,7 @@ enum Message: string
      *
      * Format: "The Vite manifest entry \"%s\" in \"%s\" has an invalid \"file\" path."
      */
-    case MANIFEST_ENTRY_FILE_PATH_INVALID
-        = 'The Vite manifest entry "%s" in "%s" has an invalid "file" path.';
+    case MANIFEST_ENTRY_FILE_PATH_INVALID = 'The Vite manifest entry "%s" in "%s" has an invalid "file" path.';
 
     /**
      * A manifest contains an invalid entry.
@@ -244,16 +243,14 @@ enum Message: string
      *
      * Format: "The Vite manifest entry \"%s\" in \"%s\" contains an invalid \"%s[%d]\" value."
      */
-    case MANIFEST_LIST_ITEM_INVALID
-        = 'The Vite manifest entry "%s" in "%s" contains an invalid "%s[%d]" value.';
+    case MANIFEST_LIST_ITEM_INVALID = 'The Vite manifest entry "%s" in "%s" contains an invalid "%s[%d]" value.';
 
     /**
      * A manifest list contains an invalid asset path.
      *
      * Format: "The Vite manifest entry \"%s\" in \"%s\" contains an invalid \"%s[%d]\" path."
      */
-    case MANIFEST_LIST_ITEM_PATH_INVALID
-        = 'The Vite manifest entry "%s" in "%s" contains an invalid "%s[%d]" path.';
+    case MANIFEST_LIST_ITEM_PATH_INVALID = 'The Vite manifest entry "%s" in "%s" contains an invalid "%s[%d]" path.';
 
     /**
      * A manifest file does not exist.
@@ -274,16 +271,14 @@ enum Message: string
      *
      * Format: "The Vite manifest entry \"%s\" in \"%s\" references missing \"%s\" chunk \"%s\"."
      */
-    case MANIFEST_REFERENCE_MISSING
-        = 'The Vite manifest entry "%s" in "%s" references missing "%s" chunk "%s".';
+    case MANIFEST_REFERENCE_MISSING = 'The Vite manifest entry "%s" in "%s" references missing "%s" chunk "%s".';
 
     /**
      * A resolved manifest import is missing unexpectedly.
      *
      * Format: "The Vite manifest entry \"%s\" in \"%s\" references missing chunk \"%s\"."
      */
-    case MANIFEST_RESOLVER_REFERENCE_MISSING
-        = 'The Vite manifest entry "%s" in "%s" references missing chunk "%s".';
+    case MANIFEST_RESOLVER_REFERENCE_MISSING = 'The Vite manifest entry "%s" in "%s" references missing chunk "%s".';
 
     /**
      * A manifest root is not a JSON object.
diff --git a/src/Html/HtmlRenderOptions.php b/src/Html/HtmlRenderOptions.php
index 79d5df3..3f69a3f 100644
--- a/src/Html/HtmlRenderOptions.php
+++ b/src/Html/HtmlRenderOptions.php
@@ -18,16 +18,22 @@
 final readonly class HtmlRenderOptions
 {
     /**
-     * @var (Closure(AssetInterface): array<string, bool|float|int|string|null>)|null
+     * @var (Closure(AssetInterface): array<string, bool|float|int|string|null>)|null Per-asset attribute callback,
+     * or `null` when only the static per-type attributes apply.
      */
     private Closure|null $attributeProvider;
 
     /**
-     * @param array<string, bool|float|int|string|null> $moduleScriptAttributes
-     * @param array<string, bool|float|int|string|null> $stylesheetAttributes
-     * @param array<string, bool|float|int|string|null> $modulePreloadAttributes
-     * @param array<string, bool|float|int|string|null> $inlineModuleAttributes
-     * @param (callable(AssetInterface): array<string, bool|float|int|string|null>)|null $attributeProvider
+     * @param string|null $nonce CSP nonce applied to every generated tag, or `null` to emit none.
+     * @param array<string, bool|float|int|string|null> $moduleScriptAttributes Extra attributes for module scripts.
+     * @param array<string, bool|float|int|string|null> $stylesheetAttributes Extra attributes for stylesheets.
+     * @param array<string, bool|float|int|string|null> $modulePreloadAttributes Extra attributes for preload hints.
+     * @param array<string, bool|float|int|string|null> $inlineModuleAttributes Extra attributes for inline modules.
+     * @param (callable(AssetInterface): array<string, bool|float|int|string|null>)|null $attributeProvider Callback
+     * returning per-asset attributes that override the per-type ones, or `null` to apply none.
+     * @param string $separator String inserted between two rendered tags.
+     *
+     * @throws HtmlRenderingException if the nonce is not a non-empty base64 or base64url value.
      */
     public function __construct(
         public string|null $nonce = null,
@@ -48,7 +54,16 @@ public function __construct(
     }
 
     /**
-     * @return array<array-key, mixed>
+     * Returns the attributes configured for the supplied asset.
+     *
+     * Starts from the attributes registered for the asset's type and, when a provider is configured, overlays the
+     * values it returns for that asset.
+     *
+     * @param AssetInterface $asset Asset the attributes are resolved for.
+     *
+     * @throws HtmlRenderingException if the asset type is unsupported, or the provider returns a non-array.
+     *
+     * @return array<array-key, mixed> Raw attributes, still to be validated by the renderer.
      */
     public function attributesFor(AssetInterface $asset): array
     {
@@ -78,7 +93,15 @@ public function attributesFor(AssetInterface $asset): array
     }
 
     /**
-     * @param Closure(AssetInterface): array<string, bool|float|int|string|null> $provider
+     * Invokes the attribute provider without narrowing its result.
+     *
+     * The return type stays `mixed` so the caller can reject a provider that breaks its declared contract at
+     * runtime, which static analysis alone cannot guarantee.
+     *
+     * @param Closure(AssetInterface): array<string, bool|float|int|string|null> $provider Configured callback.
+     * @param AssetInterface $asset Asset passed to the callback.
+     *
+     * @return mixed Whatever the provider returned.
      */
     private function provideAttributes(Closure $provider, AssetInterface $asset): mixed
     {
diff --git a/src/Html/HtmlRenderer.php b/src/Html/HtmlRenderer.php
index 935fe47..ab3ea71 100644
--- a/src/Html/HtmlRenderer.php
+++ b/src/Html/HtmlRenderer.php
@@ -25,7 +25,9 @@
 final class HtmlRenderer
 {
     /**
-     * @var array<string, true>
+     * Attribute names the renderer emits itself and therefore refuses to accept from callers.
+     *
+     * @var array<string, true> Lowercased attribute names used as a lookup set.
      */
     private const array RESERVED_ATTRIBUTES = [
         'href' => true,
@@ -35,6 +37,20 @@ final class HtmlRenderer
         'type' => true,
     ];
 
+    /**
+     * Renders a collection of neutral assets as HTML5 tags joined by the configured separator.
+     *
+     * Assets are rendered in collection order; each one is mapped to the tag its type implies, and the URL, the inline
+     * source, and every attribute value are escaped by the underlying UI Awesome tag builders.
+     *
+     * @param AssetCollection $assets Resolved assets to render.
+     * @param HtmlRenderOptions|null $options Per-render policy, or `null` to apply the defaults.
+     *
+     * @throws HtmlRenderingException if an asset type is unsupported, an inline module cannot be neutralized, or a
+     * custom attribute is reserved, duplicated, or carries an unsupported value.
+     *
+     * @return string The rendered tags joined by the configured separator.
+     */
     public function render(AssetCollection $assets, HtmlRenderOptions|null $options = null): string
     {
         $options ??= new HtmlRenderOptions();
@@ -49,7 +65,18 @@ public function render(AssetCollection $assets, HtmlRenderOptions|null $options
     }
 
     /**
-     * @return array<string, bool|float|int|string|null>
+     * Builds the final attribute set for one asset, starting from the CSP nonce and applying validated custom
+     * attributes on top.
+     *
+     * Attributes resolving to `null` or `false` are dropped rather than emitted.
+     *
+     * @param AssetInterface $asset Asset the attributes are computed for.
+     * @param HtmlRenderOptions $options Per-render policy supplying the nonce and the custom attributes.
+     *
+     * @throws HtmlRenderingException if the asset type is unsupported, the attribute provider returns a non-array, or a
+     * custom attribute is invalid.
+     *
+     * @return array<string, bool|float|int|string|null> Attributes ready to hand to the tag builder.
      */
     private function attributesFor(AssetInterface $asset, HtmlRenderOptions $options): array
     {
@@ -76,6 +103,19 @@ private function attributesFor(AssetInterface $asset, HtmlRenderOptions $options
         return $attributes;
     }
 
+    /**
+     * Maps one asset to its HTML5 tag.
+     *
+     * Module scripts and inline modules become `<script type="module">` elements, stylesheets and preload hints
+     * become `<link>` elements. Inline source has its `</script` sequences neutralized before being embedded.
+     *
+     * @param AssetInterface $asset Asset to render.
+     * @param HtmlRenderOptions $options Per-render policy applied to the tag.
+     *
+     * @throws HtmlRenderingException if the inline source cannot be neutralized, or the asset type is unsupported.
+     *
+     * @return string The rendered tag.
+     */
     private function renderAsset(AssetInterface $asset, HtmlRenderOptions $options): string
     {
         if ($asset instanceof ModuleScript) {
@@ -124,9 +164,19 @@ private function renderAsset(AssetInterface $asset, HtmlRenderOptions $options):
     }
 
     /**
-     * @param array<string, true> $seen
+     * Validates one caller-supplied attribute against the renderer's safety rules.
+     *
+     * Rejects malformed names, the attributes the renderer owns, duplicates within a single tag, every `on*` event
+     * handler, `style`, and any value that is not a scalar, `null`, or a finite `float`.
+     *
+     * @param mixed $name Attribute name supplied by the caller.
+     * @param mixed $value Attribute value supplied by the caller.
+     * @param array<string, true> $seen Lowercased names already accepted for the current tag.
+     *
+     * @throws HtmlRenderingException if the name is malformed, reserved, or duplicated, or the value is
+     * unsupported.
      *
-     * @return array{string, bool|float|int|string|null, string}
+     * @return array{string, bool|float|int|string|null, string} The name, the value, and the lowercased name.
      */
     private function validateCustomAttribute(mixed $name, mixed $value, array $seen): array
     {
diff --git a/src/Manifest/Manifest.php b/src/Manifest/Manifest.php
index 1e75bdf..2253a68 100644
--- a/src/Manifest/Manifest.php
+++ b/src/Manifest/Manifest.php
@@ -10,18 +10,27 @@
 final readonly class Manifest
 {
     /**
-     * @param array<string, ManifestChunk> $chunks
+     * @param array<string, ManifestChunk> $chunks Validated chunks indexed by their manifest key.
      */
     public function __construct(private array $chunks) {}
 
     /**
-     * @return array<string, ManifestChunk>
+     * Returns every chunk declared by the manifest.
+     *
+     * @return array<string, ManifestChunk> Chunks indexed by their manifest key.
      */
     public function chunks(): array
     {
         return $this->chunks;
     }
 
+    /**
+     * Looks up a single chunk by its manifest key.
+     *
+     * @param string $key Manifest key, usually the entrypoint source path.
+     *
+     * @return ManifestChunk|null The matching chunk, or `null` when the manifest declares no such key.
+     */
     public function get(string $key): ManifestChunk|null
     {
         return $this->chunks[$key] ?? null;
diff --git a/src/Manifest/ManifestChunk.php b/src/Manifest/ManifestChunk.php
index f502054..a7c3c0a 100644
--- a/src/Manifest/ManifestChunk.php
+++ b/src/Manifest/ManifestChunk.php
@@ -13,10 +13,16 @@
 final readonly class ManifestChunk
 {
     /**
-     * @param list<string> $css
-     * @param list<string> $assets
-     * @param list<string> $imports
-     * @param list<string> $dynamicImports
+     * @param string $key Manifest key under which the entry is declared.
+     * @param string $file Emitted build file, relative to the asset base URL.
+     * @param string|null $src Original source path, or `null` for chunks Vite generated without one.
+     * @param list<string> $css Stylesheets emitted alongside this chunk.
+     * @param list<string> $assets Static assets referenced by this chunk.
+     * @param bool $isEntry Whether the chunk is a build entrypoint.
+     * @param string|null $name Chunk name, or `null` when Vite emitted none.
+     * @param bool $isDynamicEntry Whether the chunk is the target of a dynamic import.
+     * @param list<string> $imports Statically imported chunk keys.
+     * @param list<string> $dynamicImports Dynamically imported chunk keys.
      */
     public function __construct(
         public string $key,
@@ -31,6 +37,13 @@ public function __construct(
         public array $dynamicImports = [],
     ) {}
 
+    /**
+     * Detects whether the emitted file is a stylesheet rather than a JavaScript module.
+     *
+     * The check is a case-insensitive test on the `.css` extension of the emitted file.
+     *
+     * @return bool `true` when the chunk emits a stylesheet.
+     */
     public function isCss(): bool
     {
         return str_ends_with(strtolower($this->file), '.css');
diff --git a/src/Manifest/ManifestLoader.php b/src/Manifest/ManifestLoader.php
index 621204c..8d443cd 100644
--- a/src/Manifest/ManifestLoader.php
+++ b/src/Manifest/ManifestLoader.php
@@ -37,10 +37,18 @@
 final class ManifestLoader
 {
     /**
-     * @var array<string, array{fingerprint: string, manifest: Manifest}>
+     * @var array<string, array{fingerprint: string, manifest: Manifest}> Parsed manifests keyed by absolute path,
+     * each paired with the stat fingerprint that produced it.
      */
     private array $cache = [];
 
+    /**
+     * Discards cached manifests so that the next load reads from disk.
+     *
+     * @param string|null $manifestPath Absolute path of the manifest to forget, or `null` to clear every entry.
+     *
+     * @throws ConfigurationException if a path is supplied and is not absolute.
+     */
     public function clear(string|null $manifestPath = null): void
     {
         if ($manifestPath === null) {
@@ -54,6 +62,22 @@ public function clear(string|null $manifestPath = null): void
         unset($this->cache[$manifestPath]);
     }
 
+    /**
+     * Loads, validates, and caches the manifest stored at the supplied absolute path.
+     *
+     * The cache is keyed by path and invalidated by a stat fingerprint of inode, size, mtime, and ctime, so an
+     * unchanged file is parsed once while a rebuilt file is picked up on the next call.
+     *
+     * @param string $manifestPath Absolute path to the manifest emitted by the Vite build.
+     *
+     * @throws ConfigurationException if the path is not absolute.
+     * @throws InvalidManifestException if the file is not valid JSON, does not decode to an object, or declares an
+     * invalid entry.
+     * @throws ManifestNotFoundException if no file exists at the path.
+     * @throws ManifestReadException if the file cannot be inspected or read.
+     *
+     * @return Manifest The validated manifest.
+     */
     public function load(string $manifestPath): Manifest
     {
         $manifestPath = Path::requireAbsolute($manifestPath, 'manifestPath');
@@ -65,6 +89,7 @@ public function load(string $manifestPath): Manifest
         }
 
         clearstatcache(true, $manifestPath);
+
         $metadata = stat($manifestPath);
 
         if ($metadata === false) {
@@ -110,13 +135,18 @@ public function load(string $manifestPath): Manifest
         }
 
         $manifest = $this->parse($manifestPath, $decoded);
+
         $this->cache[$manifestPath] = ['fingerprint' => $fingerprint, 'manifest' => $manifest];
 
         return $manifest;
     }
 
     /**
-     * @param array<int|string, int> $metadata
+     * Builds the change-detection fingerprint of a manifest file from its stat metadata.
+     *
+     * @param array<int|string, int> $metadata Result of `stat()` for the manifest file.
+     *
+     * @return string Fingerprint combining inode, size, mtime, and ctime.
      */
     private function fingerprint(array $metadata): string
     {
@@ -129,6 +159,18 @@ private function fingerprint(array $metadata): string
         );
     }
 
+    /**
+     * Reads an optional boolean field from a decoded manifest entry.
+     *
+     * @param stdClass $chunk Decoded manifest entry.
+     * @param string $field Field name to read.
+     * @param string $key Manifest key reported in the exception message.
+     * @param string $manifestPath Manifest path reported in the exception message.
+     *
+     * @throws InvalidManifestException if the field is present but is not a `bool`.
+     *
+     * @return bool The field value, or `false` when the field is absent.
+     */
     private function optionalBool(stdClass $chunk, string $field, string $key, string $manifestPath): bool
     {
         if (!property_exists($chunk, $field)) {
@@ -151,7 +193,21 @@ private function optionalBool(stdClass $chunk, string $field, string $key, strin
     }
 
     /**
-     * @return list<string>
+     * Reads an optional list-of-strings field from a decoded manifest entry.
+     *
+     * When `$assetPaths` is `true`, every item is additionally normalized as a relative build path, so a manifest
+     * cannot reference a location outside the configured asset base URL.
+     *
+     * @param stdClass $chunk Decoded manifest entry.
+     * @param string $field Field name to read.
+     * @param string $key Manifest key reported in the exception message.
+     * @param string $manifestPath Manifest path reported in the exception message.
+     * @param bool $assetPaths Whether each item must also be a valid relative asset path.
+     *
+     * @throws InvalidManifestException if the field is not a list, holds a non-string or empty item, or holds an
+     * item that is not a valid asset path while `$assetPaths` is `true`.
+     *
+     * @return list<string> The field items, or an empty list when the field is absent.
      */
     private function optionalList(
         stdClass $chunk,
@@ -215,6 +271,18 @@ private function optionalList(
         return $items;
     }
 
+    /**
+     * Reads an optional string field from a decoded manifest entry.
+     *
+     * @param stdClass $chunk Decoded manifest entry.
+     * @param string $field Field name to read.
+     * @param string $key Manifest key reported in the exception message.
+     * @param string $manifestPath Manifest path reported in the exception message.
+     *
+     * @throws InvalidManifestException if the field is present but is not a `string`.
+     *
+     * @return string|null The field value, or `null` when the field is absent.
+     */
     private function optionalString(stdClass $chunk, string $field, string $key, string $manifestPath): string|null
     {
         if (!property_exists($chunk, $field)) {
@@ -236,6 +304,20 @@ private function optionalString(stdClass $chunk, string $field, string $key, str
         return $value;
     }
 
+    /**
+     * Converts a decoded manifest object into validated chunks and verifies their cross-references.
+     *
+     * Every entry is validated first, then a second pass asserts that each `imports` and `dynamicImports` reference
+     * resolves to a declared chunk.
+     *
+     * @param string $manifestPath Manifest path reported in the exception messages.
+     * @param stdClass $decoded Decoded manifest root object.
+     *
+     * @throws InvalidManifestException if an entry is malformed, declares no valid `file`, holds an invalid field,
+     * or references a chunk the manifest does not declare.
+     *
+     * @return Manifest The validated manifest.
+     */
     private function parse(string $manifestPath, stdClass $decoded): Manifest
     {
         $chunks = [];
diff --git a/src/Resolver/AssetResolverInterface.php b/src/Resolver/AssetResolverInterface.php
index af440ff..a0ab413 100644
--- a/src/Resolver/AssetResolverInterface.php
+++ b/src/Resolver/AssetResolverInterface.php
@@ -5,11 +5,24 @@
 namespace PHPForge\Vite\Resolver;
 
 use PHPForge\Vite\Asset\AssetCollection;
+use PHPForge\Vite\Exception\ViteException;
 
+/**
+ * Resolves normalized Vite entrypoints into framework-neutral assets.
+ */
 interface AssetResolverInterface
 {
     /**
-     * @param list<string> $entrypoints
+     * Resolves the supplied entrypoints into the assets a page must load.
+     *
+     * Implementations receive entrypoints that are already normalized and non-empty, and return them in the order
+     * the consuming page is expected to emit.
+     *
+     * @param list<string> $entrypoints Normalized relative entrypoint paths.
+     *
+     * @throws ViteException if an entrypoint cannot be resolved, or if the underlying source is invalid.
+     *
+     * @return AssetCollection Deduplicated assets in emission order.
      */
     public function resolve(array $entrypoints): AssetCollection;
 }
diff --git a/src/Resolver/DevelopmentAssetResolver.php b/src/Resolver/DevelopmentAssetResolver.php
index 8987a1c..ebc865f 100644
--- a/src/Resolver/DevelopmentAssetResolver.php
+++ b/src/Resolver/DevelopmentAssetResolver.php
@@ -6,12 +6,32 @@
 
 use PHPForge\Vite\Asset\{AssetCollection, ModuleScript};
 use PHPForge\Vite\Configuration\DevelopmentConfiguration;
+use PHPForge\Vite\Exception\ConfigurationException;
 use PHPForge\Vite\Support\Url;
 
+/**
+ * Resolves development assets against a running Vite development server.
+ */
 final readonly class DevelopmentAssetResolver implements AssetResolverInterface
 {
+    /**
+     * @param DevelopmentConfiguration $configuration Validated development-server configuration.
+     */
     public function __construct(private DevelopmentConfiguration $configuration) {}
 
+    /**
+     * Resolves the entrypoints into inline modules, the optional Vite client, and one module script per entrypoint.
+     *
+     * The emitted order is application-owned inline modules, then the Vite client when enabled, then the entrypoints in
+     * the order supplied.
+     *
+     * @param list<string> $entrypoints Normalized relative entrypoint paths.
+     *
+     * @throws ConfigurationException if a composed URL is unsafe, or if an inline module provider yields empty
+     * source.
+     *
+     * @return AssetCollection Deduplicated development assets in emission order.
+     */
     public function resolve(array $entrypoints): AssetCollection
     {
         $assets = [];
diff --git a/src/Resolver/ManifestAssetResolver.php b/src/Resolver/ManifestAssetResolver.php
index 75f6c40..e76d250 100644
--- a/src/Resolver/ManifestAssetResolver.php
+++ b/src/Resolver/ManifestAssetResolver.php
@@ -6,17 +6,49 @@
 
 use PHPForge\Vite\Asset\{AssetCollection, ModulePreload, ModuleScript, Stylesheet};
 use PHPForge\Vite\Configuration\ProductionConfiguration;
-use PHPForge\Vite\Exception\{EntrypointNotFoundException, InvalidManifestException, Message};
+use PHPForge\Vite\Exception\{
+    ConfigurationException,
+    EntrypointNotFoundException,
+    InvalidManifestException,
+    ManifestNotFoundException,
+    ManifestReadException,
+    Message,
+};
 use PHPForge\Vite\Manifest\{Manifest, ManifestChunk, ManifestLoader};
 use PHPForge\Vite\Support\Url;
 
+/**
+ * Resolves production assets and dependency preloads from a validated Vite manifest.
+ */
 final readonly class ManifestAssetResolver implements AssetResolverInterface
 {
+    /**
+     * @param ProductionConfiguration $configuration Validated production configuration.
+     * @param ManifestLoader $manifestLoader Loader providing the validated manifest.
+     */
     public function __construct(
         private ProductionConfiguration $configuration,
         private ManifestLoader $manifestLoader,
     ) {}
 
+    /**
+     * Resolves the entrypoints into stylesheets, module scripts, and optional module-preload hints.
+     *
+     * Every entrypoint must be declared in the manifest and marked as a build entrypoint. Transitive imports are walked
+     * dependency-first, their stylesheets are hoisted, and the remaining chunks become preload hints unless they are
+     * already emitted as scripts or `modulePreload` is disabled. The emitted order is stylesheets, then module scripts,
+     * then preloads.
+     *
+     * @param list<string> $entrypoints Normalized relative entrypoint paths.
+     *
+     * @throws ConfigurationException if the manifest path is not absolute, or a composed asset URL is unsafe.
+     * @throws EntrypointNotFoundException if the manifest does not declare one of the entrypoints.
+     * @throws InvalidManifestException if the manifest is malformed, or an entry is not a build entrypoint.
+     * @throws ManifestNotFoundException if the configured manifest file does not exist.
+     * @throws ManifestReadException if the manifest file cannot be inspected or read.
+     *
+     * @return AssetCollection Deduplicated production assets in emission order.
+     */
     public function resolve(array $entrypoints): AssetCollection
     {
         $manifest = $this->manifestLoader->load($this->configuration->manifestPath);
@@ -98,13 +130,25 @@ public function resolve(array $entrypoints): AssetCollection
         return new AssetCollection($this->orderedAssets($stylesheets, $scripts, $preloads));
     }
 
+    /**
+     * Prefixes an emitted build path with the configured asset base URL.
+     *
+     * @param string $path Build path taken from a manifest chunk.
+     *
+     * @return string Public URL of the asset.
+     */
     private function assetUrl(string $path): string
     {
         return Url::join($this->configuration->assetBaseUrl, $path);
     }
 
     /**
-     * @param array<string, Stylesheet> $stylesheets
+     * Adds every stylesheet declared by a chunk to the accumulator.
+     *
+     * @param array<string, Stylesheet> $stylesheets Accumulator keyed by asset URL, mutated in place.
+     * @param ManifestChunk $chunk Chunk whose `css` field is collected.
+     *
+     * @throws ConfigurationException if a composed stylesheet URL is unsafe.
      */
     private function collectCss(array &$stylesheets, ManifestChunk $chunk): void
     {
@@ -116,9 +160,16 @@ private function collectCss(array &$stylesheets, ManifestChunk $chunk): void
     /**
      * Returns transitive imports in Vite's documented dependency-first order.
      *
-     * @param array<string, true> $seen
+     * Recurses through each static import before appending the import itself, and uses `$seen` to break cycles and
+     * to skip chunks already emitted as entrypoints.
+     *
+     * @param Manifest $manifest Manifest the references are resolved against.
+     * @param ManifestChunk $chunk Chunk whose imports are walked.
+     * @param array<string, true> $seen Keys already visited, mutated in place to guard against cycles.
      *
-     * @return list<ManifestChunk>
+     * @throws InvalidManifestException if an import references a chunk the manifest does not declare.
+     *
+     * @return list<ManifestChunk> Imported chunks, dependencies first.
      */
     private function importedChunks(Manifest $manifest, ManifestChunk $chunk, array &$seen): array
     {
@@ -149,11 +200,14 @@ private function importedChunks(Manifest $manifest, ManifestChunk $chunk, array
     }
 
     /**
-     * @param array<string, Stylesheet> $stylesheets
-     * @param array<string, ModuleScript> $scripts
-     * @param array<string, ModulePreload> $preloads
+     * Yields the accumulated assets in the documented emission order.
+     *
+     * @param array<string, Stylesheet> $stylesheets Stylesheets keyed by asset URL.
+     * @param array<string, ModuleScript> $scripts Module scripts keyed by asset URL.
+     * @param array<string, ModulePreload> $preloads Module-preload hints keyed by asset URL.
      *
-     * @return iterable<Stylesheet|ModuleScript|ModulePreload>
+     * @return iterable<Stylesheet|ModuleScript|ModulePreload> Generator yielding stylesheets, then scripts, then
+     * preloads.
      */
     private function orderedAssets(array $stylesheets, array $scripts, array $preloads): iterable
     {
@@ -163,7 +217,12 @@ private function orderedAssets(array $stylesheets, array $scripts, array $preloa
     }
 
     /**
-     * @param array<string, Stylesheet> $stylesheets
+     * Records one stylesheet in the accumulator, keyed by its resolved URL to suppress duplicates.
+     *
+     * @param array<string, Stylesheet> $stylesheets Accumulator keyed by asset URL, mutated in place.
+     * @param string $file Build path of the stylesheet.
+     *
+     * @throws ConfigurationException if the composed stylesheet URL is unsafe.
      */
     private function pushStylesheet(array &$stylesheets, string $file): void
     {
diff --git a/src/Support/EntrypointNormalizer.php b/src/Support/EntrypointNormalizer.php
index 7a2c0a7..32d75cf 100644
--- a/src/Support/EntrypointNormalizer.php
+++ b/src/Support/EntrypointNormalizer.php
@@ -14,16 +14,28 @@
 use function str_contains;
 use function trim;
 
+/**
+ * Normalizes and validates Vite entrypoint names.
+ */
 final class EntrypointNormalizer
 {
     /**
-     * @param list<mixed>|string $entrypoints
+     * Validates entrypoint values and reduces them to a deduplicated list of relative source paths.
      *
-     * @return list<string>
+     * Trims each value, strips its leading separator, and preserves insertion order while discarding repeats.
+     *
+     * @param list<mixed>|string $entrypoints Single entrypoint, or a list of entrypoints to normalize.
+     * @param bool $required Whether an empty result must be rejected instead of returned.
+     *
+     * @throws InvalidEntrypointException if an entrypoint is not a `string`, is empty, contains a backslash or a
+     * control character, or if the result is empty while `$required` is `true`.
+     *
+     * @return list<string> Deduplicated relative entrypoint paths in insertion order.
      */
     public static function normalize(array|string $entrypoints, bool $required): array
     {
         $entrypoints = is_array($entrypoints) ? $entrypoints : [$entrypoints];
+
         $normalized = [];
 
         foreach ($entrypoints as $entrypoint) {
diff --git a/src/Support/Path.php b/src/Support/Path.php
index 26beb48..f068fbc 100644
--- a/src/Support/Path.php
+++ b/src/Support/Path.php
@@ -9,8 +9,21 @@
 use function preg_match;
 use function str_starts_with;
 
+/**
+ * Validates filesystem paths required by Vite configuration.
+ */
 final class Path
 {
+    /**
+     * Validates that the supplied path is a non-empty absolute filesystem path free of control characters.
+     *
+     * @param string $path Filesystem path to validate.
+     * @param string $name Configuration key reported in the exception message.
+     *
+     * @throws ConfigurationException if the path is empty, relative, or contains control characters.
+     *
+     * @return string The validated path, returned unchanged.
+     */
     public static function requireAbsolute(string $path, string $name): string
     {
         if ($path === '' || self::containsControlCharacter($path) || !self::isAbsolute($path)) {
@@ -22,11 +35,28 @@ public static function requireAbsolute(string $path, string $name): string
         return $path;
     }
 
+    /**
+     * Detects ASCII control characters that would make a path unsafe to use in filesystem calls.
+     *
+     * @param string $value Raw value to inspect.
+     *
+     * @return bool `true` when the value contains a character in the `\x00-\x1F` or `\x7F` ranges.
+     */
     private static function containsControlCharacter(string $value): bool
     {
         return preg_match('/[\x00-\x1F\x7F]/', $value) === 1;
     }
 
+    /**
+     * Recognizes the absolute path forms accepted on the supported platforms.
+     *
+     * Accepts POSIX paths (`/var/www`), Windows UNC paths (`\\server\share`), and Windows drive-letter paths
+     * (`C:\build` or `C:/build`).
+     *
+     * @param string $path Filesystem path to classify.
+     *
+     * @return bool `true` when the path is absolute in any of the recognized forms.
+     */
     private static function isAbsolute(string $path): bool
     {
         return str_starts_with($path, '/')
diff --git a/src/Support/Url.php b/src/Support/Url.php
index 56685c0..6998780 100644
--- a/src/Support/Url.php
+++ b/src/Support/Url.php
@@ -24,8 +24,22 @@
 use const PHP_URL_QUERY;
 use const PHP_URL_SCHEME;
 
+/**
+ * Normalizes and validates development-server and asset URLs.
+ */
 final class Url
 {
+    /**
+     * Concatenates a base URL and an asset path with exactly one separator between them.
+     *
+     * Collapses the trailing separators of the base and the leading separators of the path, so that any combination
+     * of the two yields a single `/` at the boundary. An empty base returns the path without a leading separator.
+     *
+     * @param string $baseUrl Normalized base URL, or an empty `string` to emit a relative URL.
+     * @param string $path Asset path appended to the base URL.
+     *
+     * @return string The composed asset URL.
+     */
     public static function join(string $baseUrl, string $path): string
     {
         $path = ltrim($path, '/');
@@ -37,6 +51,20 @@ public static function join(string $baseUrl, string $path): string
         return rtrim($baseUrl, '/') . '/' . $path;
     }
 
+    /**
+     * Validates a configured asset base URL and strips its trailing separator.
+     *
+     * Accepts an empty value, a relative prefix, and absolute HTTP(S) URLs. Protocol-relative values, queries, and
+     * fragments are rejected because they cannot be composed safely with emitted asset paths. The root value `/` is
+     * preserved verbatim.
+     *
+     * @param string $baseUrl Raw `assetBaseUrl` value supplied by the application.
+     *
+     * @throws ConfigurationException if the value is malformed, protocol-relative, carries a query or fragment, or
+     * uses a scheme other than HTTP(S).
+     *
+     * @return string The normalized base URL without a trailing separator.
+     */
     public static function normalizeAssetBaseUrl(string $baseUrl): string
     {
         $baseUrl = trim($baseUrl);
@@ -72,6 +100,19 @@ public static function normalizeAssetBaseUrl(string $baseUrl): string
         return rtrim($baseUrl, '/');
     }
 
+    /**
+     * Validates an emitted Vite build path and reduces it to its relative form.
+     *
+     * Rejects absolute URLs, backslashes, queries, fragments, and `.` or `..` segments, so that a manifest can never
+     * escape the configured asset base URL.
+     *
+     * @param string $path Raw build path taken from the manifest or from configuration.
+     * @param string $context Human-readable subject reported in the exception message.
+     *
+     * @throws ConfigurationException if the path is empty, schemed, unsafe, or contains dot path segments.
+     *
+     * @return string The path without its leading separator.
+     */
     public static function normalizeAssetPath(string $path, string $context): string
     {
         $normalized = ltrim(trim($path), '/');
@@ -100,6 +141,18 @@ public static function normalizeAssetPath(string $path, string $context): string
         return $normalized;
     }
 
+    /**
+     * Validates a Vite development-server URL and strips its trailing separator.
+     *
+     * Requires an absolute HTTP(S) URL with a non-empty host, and rejects queries and fragments so that entrypoint
+     * paths can be appended directly.
+     *
+     * @param string $url Raw `devServerUrl` value supplied by the application.
+     *
+     * @throws ConfigurationException if the value is not an absolute HTTP(S) URL, or carries a query or fragment.
+     *
+     * @return string The normalized development-server URL, including any path prefix.
+     */
     public static function normalizeDevServerUrl(string $url): string
     {
         $url = rtrim(trim($url), '/');
@@ -123,6 +176,19 @@ public static function normalizeDevServerUrl(string $url): string
         return $url;
     }
 
+    /**
+     * Validates a resolved asset URL before it reaches an asset value object.
+     *
+     * Guards the boundary where a URL becomes renderable: empty values, protocol-relative values, and non-HTTP(S)
+     * schemes such as `javascript:` are rejected, while relative URLs are accepted unchanged.
+     *
+     * @param string $url Resolved asset URL to validate.
+     *
+     * @throws ConfigurationException if the URL is empty, malformed, protocol-relative, or uses a scheme other than
+     * HTTP(S).
+     *
+     * @return string The validated URL, trimmed of surrounding whitespace.
+     */
     public static function requireSafeAssetUrl(string $url): string
     {
         $url = trim($url);
@@ -148,11 +214,25 @@ public static function requireSafeAssetUrl(string $url): string
         return $url;
     }
 
+    /**
+     * Detects ASCII control characters that would make a URL unsafe to emit into markup.
+     *
+     * @param string $value Raw value to inspect.
+     *
+     * @return bool `true` when the value contains a character in the `\x00-\x1F` or `\x7F` ranges.
+     */
     private static function containsControlCharacter(string $value): bool
     {
         return preg_match('/[\x00-\x1F\x7F]/', $value) === 1;
     }
 
+    /**
+     * Classifies a URL as either scheme-less or an absolute HTTP(S) URL with a host.
+     *
+     * @param string $url URL to classify.
+     *
+     * @return bool `true` for relative URLs and for absolute `http`/`https` URLs, `false` for any other scheme.
+     */
     private static function isRelativeOrHttpUrl(string $url): bool
     {
         $scheme = parse_url($url, PHP_URL_SCHEME);
diff --git a/src/Vite.php b/src/Vite.php
index c697f0d..d53bd73 100644
--- a/src/Vite.php
+++ b/src/Vite.php
@@ -6,25 +6,56 @@
 
 use PHPForge\Vite\Asset\AssetCollection;
 use PHPForge\Vite\Configuration\{DevelopmentConfiguration, ProductionConfiguration};
+use PHPForge\Vite\Exception\{
+    ConfigurationException,
+    EntrypointNotFoundException,
+    InvalidEntrypointException,
+    InvalidManifestException,
+    ManifestNotFoundException,
+    ManifestReadException,
+};
 use PHPForge\Vite\Manifest\ManifestLoader;
 use PHPForge\Vite\Resolver\{AssetResolverInterface, DevelopmentAssetResolver, ManifestAssetResolver};
 use PHPForge\Vite\Support\EntrypointNormalizer;
 
 /**
- * Framework-agnostic facade for resolving Vite assets.
+ * Resolves framework-neutral Vite assets for development-server or production-manifest configuration.
  */
 final readonly class Vite
 {
     /**
-     * @var list<string>
+     * @var list<string> Default entrypoints used whenever {@see Vite::resolve()} is called without an override.
      */
     private array $entrypoints;
+
+    /**
+     * Loader backing the production resolver, retained so its cache can be cleared.
+     */
     private ManifestLoader $manifestLoader;
+
+    /**
+     * Absolute manifest path under production configuration, or `null` under development configuration.
+     */
     private string|null $manifestPath;
+
+    /**
+     * Resolver selected from the supplied configuration.
+     */
     private AssetResolverInterface $resolver;
 
     /**
-     * @param list<string> $entrypoints
+     * Selects the resolution strategy implied by the supplied configuration.
+     *
+     * A {@see DevelopmentConfiguration} resolves against a running development server and keeps no manifest state;
+     * a {@see ProductionConfiguration} resolves through the build manifest. The default entrypoints are validated
+     * eagerly but may be empty, since {@see Vite::resolve()} accepts a per-call override.
+     *
+     * @param DevelopmentConfiguration|ProductionConfiguration $configuration Configuration selecting the strategy.
+     * @param list<string> $entrypoints Default entrypoints resolved when no override is supplied.
+     * @param ManifestLoader|null $manifestLoader Loader to share across instances, or `null` to create one.
+     *
+     * @throws InvalidEntrypointException if a default entrypoint is not a `string`, is empty, or contains a
+     * backslash or a control character.
      */
     public function __construct(
         DevelopmentConfiguration|ProductionConfiguration $configuration,
@@ -48,6 +79,11 @@ public function __construct(
         $this->resolver = new ManifestAssetResolver($configuration, $this->manifestLoader);
     }
 
+    /**
+     * Drops the cached manifest so the next resolution re-reads it from disk.
+     *
+     * Does nothing under development configuration, where no manifest is loaded.
+     */
     public function clearManifestCache(): void
     {
         if ($this->manifestPath !== null) {
@@ -56,7 +92,22 @@ public function clearManifestCache(): void
     }
 
     /**
-     * @param list<mixed>|string|null $entrypoints
+     * Resolves entrypoints into the framework-neutral assets a page must load.
+     *
+     * At least one entrypoint is required at this point, whether it comes from the override or from the defaults
+     * supplied to the constructor.
+     *
+     * @param list<mixed>|string|null $entrypoints Single entrypoint or list overriding the configured defaults, or
+     * `null` to resolve those defaults.
+     *
+     * @throws ConfigurationException if a resolved asset URL is unsafe, or the manifest path is not absolute.
+     * @throws EntrypointNotFoundException if the manifest does not declare one of the entrypoints.
+     * @throws InvalidEntrypointException if an entrypoint is invalid, or none is configured.
+     * @throws InvalidManifestException if the manifest is malformed, or an entry is not a build entrypoint.
+     * @throws ManifestNotFoundException if the configured manifest file does not exist.
+     * @throws ManifestReadException if the manifest file cannot be inspected or read.
+     *
+     * @return AssetCollection Deduplicated assets in the order the page is expected to emit.
      */
     public function resolve(array|string|null $entrypoints = null): AssetCollection
     {
diff --git a/tests/AssetCollectionTest.php b/tests/AssetCollectionTest.php
index ad33eb1..5832a93 100644
--- a/tests/AssetCollectionTest.php
+++ b/tests/AssetCollectionTest.php
@@ -6,7 +6,7 @@
 
 use PHPForge\Vite\Asset\{AssetCollection, InlineModule, ModulePreload, ModuleScript, Stylesheet};
 use PHPForge\Vite\Exception\{ConfigurationException, Message};
-use PHPForge\Vite\Tests\Fixtures\UnsupportedAssetStub;
+use PHPForge\Vite\Tests\Fixture\UnsupportedAssetStub;
 use PHPUnit\Framework\Attributes\Group;
 use PHPUnit\Framework\TestCase;
 
diff --git a/tests/ConfigurationTest.php b/tests/ConfigurationTest.php
index 8a53c77..39ba37b 100644
--- a/tests/ConfigurationTest.php
+++ b/tests/ConfigurationTest.php
@@ -7,7 +7,7 @@
 use PHPForge\Vite\Asset\{InlineModule, ModuleScript};
 use PHPForge\Vite\Configuration\{DevelopmentConfiguration, ProductionConfiguration};
 use PHPForge\Vite\Exception\{ConfigurationException, InvalidEntrypointException, Message};
-use PHPForge\Vite\Tests\Fixtures\CapturingInlineModuleProviderStub;
+use PHPForge\Vite\Tests\Fixture\CapturingInlineModuleProviderStub;
 use PHPForge\Vite\Tests\Provider\ConfigurationProvider;
 use PHPForge\Vite\Vite;
 use PHPUnit\Framework\Attributes\{DataProviderExternal, Group};
diff --git a/tests/Fixture/CapturingInlineModuleProviderStub.php b/tests/Fixture/CapturingInlineModuleProviderStub.php
new file mode 100644
index 0000000..e8fd57a
--- /dev/null
+++ b/tests/Fixture/CapturingInlineModuleProviderStub.php
@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Vite\Tests\Fixture;
+
+use PHPForge\Vite\Asset\InlineModule;
+use PHPForge\Vite\Development\InlineModuleProviderInterface;
+
+/**
+ * Inline module provider that records the development-server URL it was called with.
+ *
+ * Lets a test assert both the emitted module source and the URL the resolver passed to the provider.
+ */
+final class CapturingInlineModuleProviderStub implements InlineModuleProviderInterface
+{
+    /**
+     * Development-server URL captured on the last call, or `null` while the provider is untouched.
+     */
+    public string|null $receivedUrl = null;
+
+    /**
+     * Records the supplied URL and returns an inline module that echoes it back.
+     *
+     * @param string $devServerUrl Normalized development-server URL supplied by the resolver.
+     *
+     * @return InlineModule Module assigning the captured URL to a global.
+     */
+    public function provide(string $devServerUrl): InlineModule
+    {
+        $this->receivedUrl = $devServerUrl;
+
+        return new InlineModule("window.devServer = \"$devServerUrl\";");
+    }
+}
diff --git a/tests/Fixture/UnsupportedAssetStub.php b/tests/Fixture/UnsupportedAssetStub.php
new file mode 100644
index 0000000..2f489ab
--- /dev/null
+++ b/tests/Fixture/UnsupportedAssetStub.php
@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Vite\Tests\Fixture;
+
+use PHPForge\Vite\Asset\AssetInterface;
+
+/**
+ * Asset implementing the marker interface without being one of the four supported types.
+ *
+ * Exercises the guard that rejects third-party {@see AssetInterface} implementations.
+ */
+final class UnsupportedAssetStub implements AssetInterface {}
diff --git a/tests/Fixtures/CapturingInlineModuleProviderStub.php b/tests/Fixtures/CapturingInlineModuleProviderStub.php
deleted file mode 100644
index 7b48242..0000000
--- a/tests/Fixtures/CapturingInlineModuleProviderStub.php
+++ /dev/null
@@ -1,20 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace PHPForge\Vite\Tests\Fixtures;
-
-use PHPForge\Vite\Asset\InlineModule;
-use PHPForge\Vite\Development\InlineModuleProviderInterface;
-
-final class CapturingInlineModuleProviderStub implements InlineModuleProviderInterface
-{
-    public string|null $receivedUrl = null;
-
-    public function provide(string $devServerUrl): InlineModule
-    {
-        $this->receivedUrl = $devServerUrl;
-
-        return new InlineModule("window.devServer = \"$devServerUrl\";");
-    }
-}
diff --git a/tests/Fixtures/UnsupportedAssetStub.php b/tests/Fixtures/UnsupportedAssetStub.php
deleted file mode 100644
index af90166..0000000
--- a/tests/Fixtures/UnsupportedAssetStub.php
+++ /dev/null
@@ -1,9 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace PHPForge\Vite\Tests\Fixtures;
-
-use PHPForge\Vite\Asset\AssetInterface;
-
-final class UnsupportedAssetStub implements AssetInterface {}
diff --git a/tests/HtmlRendererTest.php b/tests/HtmlRendererTest.php
index 3f3ce34..c093702 100644
--- a/tests/HtmlRendererTest.php
+++ b/tests/HtmlRendererTest.php
@@ -103,6 +103,7 @@ public function testRendererEscapesUrlsAndCustomAttributes(): void
             'URLs, values, booleans, and omitted attributes must be encoded safely.',
         );
     }
+
     public function testRendererPreservesCollectionOrder(): void
     {
         $assets = new AssetCollection(
diff --git a/tests/ManifestLoaderTest.php b/tests/ManifestLoaderTest.php
index bbb33c9..c6f6d75 100644
--- a/tests/ManifestLoaderTest.php
+++ b/tests/ManifestLoaderTest.php
@@ -34,7 +34,7 @@
 final class ManifestLoaderTest extends TestCase
 {
     /**
-     * @var list<string>
+     * @var list<string> Absolute paths of the manifests created by this test, deleted during teardown.
      */
     private array $temporaryFiles = [];
 
diff --git a/tests/Provider/ConfigurationProvider.php b/tests/Provider/ConfigurationProvider.php
index bd051cd..66ac44a 100644
--- a/tests/Provider/ConfigurationProvider.php
+++ b/tests/Provider/ConfigurationProvider.php
@@ -8,8 +8,6 @@
 
 /**
  * Data provider for {@see \PHPForge\Vite\Tests\ConfigurationTest} test cases.
- *
- * Provides invalid configuration values and their exception messages.
  */
 final class ConfigurationProvider
 {
diff --git a/tests/Provider/HtmlRendererProvider.php b/tests/Provider/HtmlRendererProvider.php
index 397047e..db0bcf2 100644
--- a/tests/Provider/HtmlRendererProvider.php
+++ b/tests/Provider/HtmlRendererProvider.php
@@ -9,8 +9,6 @@
 
 /**
  * Data provider for {@see \PHPForge\Vite\Tests\HtmlRendererTest} test cases.
- *
- * Provides unsafe attributes and their exception message arguments.
  */
 final class HtmlRendererProvider
 {
diff --git a/tests/Provider/ManifestLoaderProvider.php b/tests/Provider/ManifestLoaderProvider.php
index 40bb215..3abb85c 100644
--- a/tests/Provider/ManifestLoaderProvider.php
+++ b/tests/Provider/ManifestLoaderProvider.php
@@ -8,9 +8,6 @@
 
 /**
  * Data provider for {@see \PHPForge\Vite\Tests\ManifestLoaderTest} test cases.
- *
- * Provides invalid manifests and their exception message arguments. A `null` argument represents the temporary
- * manifest path created by the consuming test.
  */
 final class ManifestLoaderProvider
 {
diff --git a/tests/Provider/UrlProvider.php b/tests/Provider/UrlProvider.php
index b44d4fa..a5e301f 100644
--- a/tests/Provider/UrlProvider.php
+++ b/tests/Provider/UrlProvider.php
@@ -6,8 +6,6 @@
 
 /**
  * Data provider for {@see \PHPForge\Vite\Tests\UrlTest} test cases.
- *
- * Provides base URL and asset path combinations for URL joining.
  */
 final class UrlProvider
 {
diff --git a/tests/ViteDevelopmentTest.php b/tests/ViteDevelopmentTest.php
index 862225d..3358e36 100644
--- a/tests/ViteDevelopmentTest.php
+++ b/tests/ViteDevelopmentTest.php
@@ -7,7 +7,7 @@
 use PHPForge\Vite\Asset\{InlineModule, ModuleScript};
 use PHPForge\Vite\Configuration\DevelopmentConfiguration;
 use PHPForge\Vite\Exception\{InvalidEntrypointException, Message};
-use PHPForge\Vite\Tests\Fixtures\CapturingInlineModuleProviderStub;
+use PHPForge\Vite\Tests\Fixture\CapturingInlineModuleProviderStub;
 use PHPForge\Vite\Vite;
 use PHPUnit\Framework\Attributes\Group;
 use PHPUnit\Framework\TestCase;
diff --git a/tests/ViteProductionTest.php b/tests/ViteProductionTest.php
index a32b0d6..fd3a0cb 100644
--- a/tests/ViteProductionTest.php
+++ b/tests/ViteProductionTest.php
@@ -100,6 +100,7 @@ public function testEntrypointsWithSameOutputFileAreDeduplicated(): void
         );
     }
 
+
     public function testImportedCssChunkIsRenderedAndNotPreloaded(): void
     {
         $assets = $this->vite('css-chunk-import-manifest.json', ['resources/js/app.js'])->resolve();
@@ -264,7 +265,11 @@ public function testThrowInvalidManifestExceptionWhenManifestKeyIsNotAnEntrypoin
     }
 
     /**
-     * @return list<string>
+     * Flattens a collection into `type:url` strings so an assertion can compare both order and asset type at once.
+     *
+     * @param AssetCollection $collection Resolved assets to describe.
+     *
+     * @return list<string> One `type:url` entry per URL-bearing asset, in collection order.
      */
     private function describe(AssetCollection $collection): array
     {
@@ -280,7 +285,12 @@ private function describe(AssetCollection $collection): array
     }
 
     /**
-     * @param list<string> $entrypoints
+     * Builds a facade over a manifest fixture, using `/build` as the asset base URL.
+     *
+     * @param string $fixture File name of the manifest fixture under `tests/Fixture`.
+     * @param list<string> $entrypoints Default entrypoints for the facade.
+     *
+     * @return Vite Facade configured for production resolution.
      */
     private function vite(string $fixture, array $entrypoints): Vite
     {

From 2bb3594012ebdac5e34c763a164db4f020a781ca Mon Sep 17 00:00:00 2001
From: Wilmer Arambula <terabytesoftw@gmail.com>
Date: Mon, 24 Aug 2026 12:17:18 -0400
Subject: [PATCH 2/2] Apply fixed Coderabbitai review.

---
 src/Exception/HtmlRenderingException.php |  5 ++++-
 src/Html/HtmlRenderer.php                | 11 ++++++-----
 2 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/src/Exception/HtmlRenderingException.php b/src/Exception/HtmlRenderingException.php
index b761b56..5a6cb6f 100644
--- a/src/Exception/HtmlRenderingException.php
+++ b/src/Exception/HtmlRenderingException.php
@@ -7,6 +7,9 @@
 use InvalidArgumentException;
 
 /**
- * Reports unsafe or unsupported HTML rendering options.
+ * Reports a failure encountered while rendering neutral Vite assets as HTML.
+ *
+ * Raised for an unsafe or unsupported render option, for an asset implementation the renderer cannot map to a tag,
+ * and when inline module source cannot be neutralized.
  */
 final class HtmlRenderingException extends InvalidArgumentException implements ViteException {}
diff --git a/src/Html/HtmlRenderer.php b/src/Html/HtmlRenderer.php
index ab3ea71..b9e96b7 100644
--- a/src/Html/HtmlRenderer.php
+++ b/src/Html/HtmlRenderer.php
@@ -40,14 +40,15 @@ final class HtmlRenderer
     /**
      * Renders a collection of neutral assets as HTML5 tags joined by the configured separator.
      *
-     * Assets are rendered in collection order; each one is mapped to the tag its type implies, and the URL, the inline
-     * source, and every attribute value are escaped by the underlying UI Awesome tag builders.
+     * Assets are rendered in collection order, each one mapped to the tag its type implies. The UI Awesome tag
+     * builders encode URLs and attribute values; inline module source is embedded raw through `Script::html()` and is
+     * protected only by neutralizing its closing `</script` sequences.
      *
      * @param AssetCollection $assets Resolved assets to render.
      * @param HtmlRenderOptions|null $options Per-render policy, or `null` to apply the defaults.
      *
      * @throws HtmlRenderingException if an asset type is unsupported, an inline module cannot be neutralized, or a
-     * custom attribute is reserved, duplicated, or carries an unsupported value.
+     * custom attribute is malformed, reserved, duplicated, or carries an unsupported value.
      *
      * @return string The rendered tags joined by the configured separator.
      */
@@ -73,8 +74,8 @@ public function render(AssetCollection $assets, HtmlRenderOptions|null $options
      * @param AssetInterface $asset Asset the attributes are computed for.
      * @param HtmlRenderOptions $options Per-render policy supplying the nonce and the custom attributes.
      *
-     * @throws HtmlRenderingException if the asset type is unsupported, the attribute provider returns a non-array, or a
-     * custom attribute is invalid.
+     * @throws HtmlRenderingException if the asset type is unsupported, the attribute provider returns a non-array, or
+     * a custom attribute is malformed, reserved, duplicated, or carries an unsupported value.
      *
      * @return array<string, bool|float|int|string|null> Attributes ready to hand to the tag builder.
      */