From 744838c41c2073df39b0bc814589f662677bb4bd Mon Sep 17 00:00:00 2001
From: patridunk <78499649+patridunk@users.noreply.github.com>
Date: Wed, 14 Jan 2026 14:59:32 +0100
Subject: [PATCH] docs: add provider detection behavior notes

This document explains provider detection behavior, including multiple providers, timing considerations, recommended usage patterns, and common pitfalls.
---
 docs/provider-detection-notes | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)
 create mode 100644 docs/provider-detection-notes

diff --git a/docs/provider-detection-notes b/docs/provider-detection-notes
new file mode 100644
index 0000000..da3358f
--- /dev/null
+++ b/docs/provider-detection-notes
@@ -0,0 +1,31 @@
+# Provider Detection Notes
+
+This document explains how provider detection behaves in different environments
+and what developers should expect when using detect-provider.
+
+## Multiple providers
+
+- If multiple injected providers are present, the first matching provider is returned.
+- Wallets may inject providers asynchronously, depending on load timing.
+- Avoid assuming a specific wallet implementation is always returned.
+
+## Timing considerations
+
+- Provider injection can occur after page load.
+- Always await the detect-provider promise before using the provider.
+- Do not cache a failed detection result too early.
+
+## Recommended usage pattern
+
+- Call detect-provider once during initialization.
+- Store the resolved provider in application state.
+- Handle the case where no provider is found gracefully.
+
+## Common pitfalls
+
+- Calling provider methods before detection completes.
+- Assuming `window.ethereum` is always immediately available.
+- Hard-coding wallet-specific behavior.
+
+Understanding these behaviors helps prevent subtle integration bugs
+and improves compatibility across different wallets.