Fix Static Reset (#164)

Author: wallstop

.github/workflows/markdown-link-validity.yml

@@ -29,15 +29,12 @@ jobs:
         uses: lycheeverse/lychee-action@v2
         with:
           # Include fragments ensures anchors are validated
+          # Use conservative concurrency (4) to avoid GitHub rate limiting
           args: >-
             -c .lychee.toml
             --no-progress
             --include-fragments
             --verbose
-            --max-concurrency 12
-            --timeout 20
-            --retry-wait-time 2
-            --max-retries 2
             "./**/*.md"
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.llm/context.md

@@ -250,7 +250,7 @@ Before acting on PR review feedback:
 
 - Frameworks: NUnit + Unity Test Framework. Use `[Test]`/`[UnityTest]` as needed.
 - Location: add files under [Tests/Runtime](../Tests/Runtime/) `<Area>/` named `*Tests.cs` with classes `*Tests`.
-- Keep tests independent: prefer a local `MessageBus` and explicit `MessageRegistrationToken` lifecycles.
+- Keep tests independent: prefer a local `MessageBus` and explicit `MessageRegistrationToken` lifecycles. When using `MessageHandler`, set `active = true`. When using `MessageRegistrationToken`, pass the local `MessageBus` to `Create()` and call `Enable()` to activate handlers.
 - Do not use underscores in test function names.
 - Prefer expressive assertions and failure messages so it is clear what exactly is failing when a test fails.
 - Do not use regions.

.llm/skills/documentation/link-quality-guidelines.md

@@ -2,9 +2,9 @@
 title: "Link Quality and External URL Management"
 id: "link-quality-guidelines"
 category: "documentation"
-version: "1.2.0"
+version: "1.4.0"
 created: "2026-01-22"
-updated: "2026-01-23"
+updated: "2026-02-09"
 
 source:
   repository: "wallstop/DxMessaging"
@@ -227,6 +227,49 @@ Some domains change URL structures frequently. Extra verification is needed:
 
 For detailed guidance on URL fragment validation (`#section-name` links), see [External URL Fragment Validation](external-url-fragment-validation.md).
 
+### Handling Link Checker False Positives
+
+Automated link checkers (like lychee) can fail on valid URLs when websites block automated requests. This does not mean the link is broken.
+
+#### Common Blocking Status Codes
+
+| Status Code | Meaning                | Example Cause                               |
+| ----------- | ---------------------- | ------------------------------------------- |
+| 403         | Forbidden              | User-agent blocking, geographic restriction |
+| 415         | Unsupported Media Type | Server rejects non-browser Accept headers   |
+| 429         | Too Many Requests      | Rate limiting                               |
+| 503         | Service Unavailable    | Bot protection, Cloudflare challenge        |
+
+#### Investigating Link Checker Failures
+
+When a link checker reports an error:
+
+1. **Manually verify the link**: Open the URL in a browser to confirm it works
+1. **Check the status code**: Some codes (403, 415, 429) often indicate bot blocking, not broken links
+1. **Try a different user-agent**: The link may work with browser-like headers
+1. **Check if the site has bot protection**: Cloudflare, Akamai, or custom protection may block automated clients
+
+#### Adding Exclusions to `.lychee.toml`
+
+When a link is valid but the site blocks automated checkers, add an exclusion pattern:
+
+```toml
+exclude = [
+  # NPM package page serves a Cloudflare JS challenge to non-browser clients
+  "^https://www\\.npmjs\\.com/package/com\\.wallstop-studios\\.dxmessaging$",
+  # Game Programming Patterns site returns 415 to automated clients despite valid content
+  "^https://gameprogrammingpatterns\\.com/"
+]
+```
+
+#### Exclusion Pattern Guidelines
+
+- **Use regex anchors**: Start patterns with `^` to match from the beginning of the URL
+- **Escape special characters**: Dots in domain names need `\\.` escaping
+- **Document the reason**: Add a comment explaining why the exclusion exists
+- **Be specific**: Prefer specific URL patterns over broad domain exclusions when possible
+- **Verify first**: Always manually verify the link is actually valid before adding an exclusion
+
 ### GitHub Actions Version Consistency
 
 Workflow files should use consistent action versions across all workflows. For detailed guidance including version update processes and common actions to monitor, see [GitHub Actions Version Consistency](github-actions-version-consistency.md).
@@ -259,9 +302,10 @@ Before committing documentation or skill files:
 
 ## Changelog
 
-| Version | Date       | Changes                                                                     |
-| ------- | ---------- | --------------------------------------------------------------------------- |
-| 1.3.0   | 2026-01-27 | Split fragment validation and GitHub Actions to separate skills             |
-| 1.2.0   | 2026-01-23 | Added external URL fragment validation section based on CI failure analysis |
-| 1.1.0   | 2026-01-22 | Added documentation linting scripts section with testing guidance           |
-| 1.0.0   | 2026-01-22 | Initial version covering link quality fundamentals                          |
+| Version | Date       | Changes                                                                        |
+| ------- | ---------- | ------------------------------------------------------------------------------ |
+| 1.4.0   | 2026-02-09 | Added guidance for handling link checker false positives and lychee exclusions |
+| 1.3.0   | 2026-01-27 | Split fragment validation and GitHub Actions to separate skills                |
+| 1.2.0   | 2026-01-23 | Added external URL fragment validation section based on CI failure analysis    |
+| 1.1.0   | 2026-01-22 | Added documentation linting scripts section with testing guidance              |
+| 1.0.0   | 2026-01-22 | Initial version covering link quality fundamentals                             |

.llm/skills/index.md

@@ -1,6 +1,6 @@
 # Skills Index
 
-> **Auto-generated** on 2026-02-01. Do not edit manually.
+> **Auto-generated** on 2026-02-09. Do not edit manually.
 > Run `node scripts/generate-skills-index.js` to regenerate.
 
 ---
@@ -42,7 +42,7 @@
 | [Documentation Updates and Maintenance](./documentation/documentation-updates.md)           | 📝 149 | 🟢 Basic        | ✅ Stable | ○○○○○       | documentation, code-comments, xml-docs    |
 | [External URL Fragment Validation](./documentation/external-url-fragment-validation.md)     | 📝 182 | 🟢 Basic        | ✅ Stable | ○○○○○       | documentation, links, urls                |
 | [GitHub Actions Version Consistency](./documentation/github-actions-version-consistency.md) | ✅ 204 | 🟢 Basic        | ✅ Stable | ○○○○○       | github-actions, ci-cd, version-management |
-| [Link Quality and External URL Management](./documentation/link-quality-guidelines.md)      | ✅ 268 | 🟢 Basic        | ✅ Stable | ○○○○○       | documentation, links, urls                |
+| [Link Quality and External URL Management](./documentation/link-quality-guidelines.md)      | ✅ 312 | 🟢 Basic        | ✅ Stable | ○○○○○       | documentation, links, urls                |
 | [Markdown Compatibility Guidelines](./documentation/markdown-compatibility.md)              | ⚠️ 477 | 🟢 Basic        | ✅ Stable | ○○○○○       | documentation, markdown, compatibility    |
 | [Mermaid Diagram Theming](./documentation/mermaid-theming.md)                               | ✅ 327 | 🟡 Intermediate | ✅ Stable | ○○○○○       | documentation, mermaid, theming           |
 | [MkDocs Navigation Management](./documentation/mkdocs-navigation.md)                        | ✅ 291 | 🟢 Basic        | ✅ Stable | ○○○○○       | documentation, mkdocs, navigation         |
@@ -149,7 +149,7 @@
 | [Test Invalid Skill](./testing/test-invalid-skill.md)                                             | 📝 27  | 🔴 Expert       | ✅ Stable | ●●●○○       |                                             |
 | [Test Organization and Assertions](./testing/test-coverage-organization-assertions.md)            | 📝 172 | 🟢 Basic        | ✅ Stable | ○○○○○       | testing, assertions, naming                 |
 | [Test Production Code Directly](./testing/test-production-code.md)                                | ✅ 349 | 🟡 Intermediate | ✅ Stable | ○○○○○       | testing, anti-patterns, code-quality        |
-| [Unity Test Considerations and Anti-Patterns](./testing/test-coverage-unity-anti-patterns.md)     | ✅ 233 | 🟢 Basic        | ✅ Stable | ○○○○○       | testing, unity, anti-patterns               |
+| [Unity Test Considerations and Anti-Patterns](./testing/test-coverage-unity-anti-patterns.md)     | ✅ 260 | 🟢 Basic        | ✅ Stable | ○○○○○       | testing, unity, anti-patterns               |
 
 ---
 

.llm/skills/testing/test-coverage-unity-anti-patterns.md

@@ -146,6 +146,33 @@ Assert.That(component == null, Is.True, "Component should be null");
 Assert.That(gameObject != null, Is.True, "GameObject should exist");
 ```
 
+### MessageRegistrationToken Lifecycle
+
+When testing with `MessageRegistrationToken`, always:
+
+1. Set `MessageHandler.active = true` when creating the handler
+1. Pass the local `MessageBus` to avoid using the global bus
+1. Call `Enable()` after creating the token to activate registrations
+
+```csharp
+// GOOD: Complete setup with active handler, local bus, and Enable()
+MessageBus messageBus = new MessageBus();
+MessageHandler handler = new MessageHandler(instanceId, messageBus) { active = true };
+MessageRegistrationToken token = MessageRegistrationToken.Create(handler, messageBus);
+token.Enable();
+
+// BAD: Missing active = true - handler ignores all messages
+MessageHandler handler = new MessageHandler(instanceId, messageBus);
+// handler.active is false by default!
+
+// BAD: Missing Enable() - handlers are staged but not activated
+MessageRegistrationToken token = MessageRegistrationToken.Create(handler, messageBus);
+// Handlers are registered but inactive!
+
+// BAD: Missing messageBus - uses global state, causes test pollution
+MessageRegistrationToken token = MessageRegistrationToken.Create(handler);
+```
+
 ## Anti-Patterns to Avoid
 
 ### Don't Use Underscores in Test Names

.lychee.toml

@@ -10,9 +10,9 @@ retry_wait_time = 2     # seconds between retries
 max_redirects = 10
 user_agent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0 Safari/537.36"
 
-# Treat successes and rate-limiting as acceptable in CI
-# Accept all 2xx as valid plus 429 (rate limited)
-accept = ["200..=299", 429]
+# Treat successes, rate-limiting, and transient server errors as acceptable in CI
+# Accept all 2xx as valid plus 429 (rate limited) and 502 (bad gateway - transient)
+accept = ["200..=299", 429, 502]
 
 # Only check web links
 scheme = ["https", "http"]
@@ -26,5 +26,7 @@ exclude = [
   # NPM package page serves a Cloudflare JS challenge to non-browser clients; registry endpoint remains covered.
   "^https://www\\.npmjs\\.com/package/com\\.wallstop-studios\\.dxmessaging$",
   # GitHub Pages site - not deployed yet, will be available after first successful deploy
-  "^https://wallstop\\.github\\.io/DxMessaging"
+  "^https://wallstop\\.github\\.io/DxMessaging",
+  # Game Programming Patterns site returns 415 (Unsupported Media Type) to automated clients despite valid content
+  "^https://gameprogrammingpatterns\\.com/"
 ]

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- Fixed a bug where no messages would get received by any listeners due to specifics in Unity play mode timings
+
 ## [2.1.8]
 
 ### Fixed

Runtime/Core/DxMessagingStaticState.cs

@@ -1,12 +1,25 @@
 namespace DxMessaging.Core
 {
     using System;
-    using Helper;
     using MessageBus;
 
     /// <summary>
     /// Centralised utility for resetting DxMessaging static state when Domain Reload is disabled.
     /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This class is designed for Unity's Enter Play Mode Settings with Domain Reload disabled.
+    /// When Domain Reload is disabled, static fields persist between play mode sessions, which
+    /// can cause issues if stale state is not cleared.
+    /// </para>
+    /// <para>
+    /// <strong>Important:</strong> Message type sequential IDs (managed by MessageHelperIndexer)
+    /// are intentionally NOT reset. Once a message type is assigned an ID, it retains that ID
+    /// for the lifetime of the application domain. This prevents ID collisions that would occur
+    /// if a new message type were assigned an ID that was previously used by a different type.
+    /// Resetting IDs could cause messages to be routed to the wrong handlers.
+    /// </para>
+    /// </remarks>
     public static class DxMessagingStaticState
     {
         private static readonly object ResetLock = new object();
@@ -20,6 +33,9 @@ static DxMessagingStaticState()
         /// <summary>
         /// Resets all static variables in DxMessaging to their default values.
         /// </summary>
+        /// <remarks>
+        /// Message type IDs are NOT reset by this method. See the class remarks for details.
+        /// </remarks>
         public static void Reset()
         {
             lock (ResetLock)
@@ -31,13 +47,10 @@ public static void Reset()
                 IMessageBus.GlobalMessageBufferSize = Baseline.GlobalMessageBufferSize;
                 IMessageBus.GlobalSequentialIndex = Baseline.GlobalSequentialIndex;
 
-                MessageHelperIndexer.RestoreState(Baseline.HelperState);
-
                 MessageRegistrationHandle.SetIdSeed(Baseline.MessageRegistrationHandleSeed);
                 MessageRegistrationBuilder.SetSyntheticOwnerCounter(Baseline.SyntheticOwnerCounter);
 
                 MessageHandler.ResetStatics();
-                IMessageBus.GlobalSequentialIndex = Baseline.GlobalSequentialIndex;
             }
         }
 
@@ -50,8 +63,6 @@ private static BaselineState CaptureBaseline()
             int globalSequentialIndex = IMessageBus.GlobalSequentialIndex;
             long messageRegistrationHandleSeed = MessageRegistrationHandle.GetCurrentIdSeed();
             int syntheticOwnerCounter = MessageRegistrationBuilder.GetSyntheticOwnerCounter();
-            MessageHelperIndexer.MessageHelperIndexerState helperState =
-                MessageHelperIndexer.CaptureState();
 
             return new BaselineState(
                 messagingDebugEnabled,
@@ -60,8 +71,7 @@ private static BaselineState CaptureBaseline()
                 globalMessageBufferSize,
                 globalSequentialIndex,
                 messageRegistrationHandleSeed,
-                syntheticOwnerCounter,
-                helperState
+                syntheticOwnerCounter
             );
         }
 
@@ -74,8 +84,7 @@ internal BaselineState(
                 int globalMessageBufferSize,
                 int globalSequentialIndex,
                 long messageRegistrationHandleSeed,
-                int syntheticOwnerCounter,
-                MessageHelperIndexer.MessageHelperIndexerState helperState
+                int syntheticOwnerCounter
             )
             {
                 MessagingDebugEnabled = messagingDebugEnabled;
@@ -85,7 +94,6 @@ MessageHelperIndexer.MessageHelperIndexerState helperState
                 GlobalSequentialIndex = globalSequentialIndex;
                 MessageRegistrationHandleSeed = messageRegistrationHandleSeed;
                 SyntheticOwnerCounter = syntheticOwnerCounter;
-                HelperState = helperState;
             }
 
             internal bool MessagingDebugEnabled { get; }
@@ -101,8 +109,6 @@ MessageHelperIndexer.MessageHelperIndexerState helperState
             internal long MessageRegistrationHandleSeed { get; }
 
             internal int SyntheticOwnerCounter { get; }
-
-            internal MessageHelperIndexer.MessageHelperIndexerState HelperState { get; }
         }
     }
 }